Handshake and Authentication Messages

This page documents the authentication and session initialization messages in the Bolt protocol: INIT (V1-V2), HELLO (V3+), LOGON (V5+), and LOGOFF (V5+). These messages establish and authorize the client connection before any query execution can occur.

For query execution messages like RUN, see Query Execution Messages. For session management messages like RESET and GOODBYE, see Session Management Messages. For the overall protocol version selection process, see Bolt Factory and Protocol Negotiation.

Overview of Authentication Flow

The Bolt protocol's authentication mechanism has evolved across versions to provide better separation of concerns and security:

Protocol Version	Initialization Message	Authentication Method	Termination
V1, V2	INIT	Combined in INIT message	Disconnect
V3, V4	HELLO	Combined in HELLO message	GOODBYE
V5+	HELLO	Separate LOGON message	LOGOFF + GOODBYE

In V1-V4, authentication credentials are bundled with the connection initialization. Starting with V5, the protocol separates connection initialization (HELLO) from authentication (LOGON), allowing for re-authentication without reconnecting.

Sources: README.md84-125 Diagram 2 from high-level architecture

Protocol Handshake Preceding Authentication

Before any authentication messages can be sent, the Bolt client must perform a version negotiation handshake:

The handshake consists of:

1. Magic preamble 0x6060B017 identifying the Bolt protocol
2. Four protocol version candidates (32 bits each) in descending priority
3. Server response with selected version (or 0x00000000 if none match)

Only after successful handshake can authentication messages be sent. The Bolt factory class handles this automatically in the build() method.

Sources: README.md89-93 src/protocol/v3/HelloMessage.php1-24

INIT Message (Protocol V1 and V2)

The INIT message combines connection initialization and authentication into a single message. It was used exclusively in Bolt protocol versions 1 and 2.

Message Structure

Implementation

The INIT message is implemented in the InitMessage trait:

src/protocol/v1/InitMessage.php1-24

The message signature is 0x01, followed by:

1. userAgent: String identifying the client application (e.g., "MyApp/1.0")
2. authToken: Dictionary containing authentication credentials (see Authentication Schemes below)

Usage Example

The INIT message must be the first message sent after handshake completion. The server responds with either SUCCESS or FAILURE.

Sources: src/protocol/v1/InitMessage.php1-24 README.md114

HELLO Message (Protocol V3+)

Starting with Bolt protocol V3, INIT was replaced by HELLO, which provides more flexible connection initialization with support for additional metadata via the extra parameter.

Message Structure

Implementation

The HELLO message is implemented in the HelloMessage trait for V3+:

src/protocol/v3/HelloMessage.php1-24

The message signature remains 0x01 (same as INIT), but accepts a single $extra dictionary parameter containing all metadata.

Common Extra Parameters

Key	Type	Description	Protocol Version
user_agent	String	Client application identifier	V3+
scheme	String	Authentication scheme	V3-V4 only
principal	String	Username (basic auth)	V3-V4 only
credentials	String	Password or token	V3-V4 only
routing	Dictionary	Routing context for cluster	V4+
patch_bolt	List	Protocol patches to enable	V4.3+

Usage Examples

Basic authentication (V3-V4):

No authentication (testing/local):

Cluster routing context:

Sources: src/protocol/v3/HelloMessage.php1-24 tests/NornicDBTest.php36 tests/BoltTest.php33

LOGON and LOGOFF Messages (Protocol V5+)

Protocol V5 separates authentication from connection initialization, introducing dedicated LOGON and LOGOFF messages. This allows re-authentication without reconnecting.

Authentication Flow in V5+

LOGON Message

The LOGON message authenticates a user after the connection has been initialized with HELLO.

Structure:

• Signature: (varies by version, typically in v5 message set)
• Parameter: auth dictionary with scheme-specific fields

Method signature:

The $auth array has the same structure as authentication fields in V3-V4 HELLO messages (see Authentication Schemes below).

Usage:

LOGOFF Message

The LOGOFF message terminates the current authenticated session while keeping the connection open.

Structure:

• Signature: (varies by version, typically in v5 message set)
• Parameters: None

Method signature:

Usage:

After LOGOFF, the connection returns to an unauthenticated state. A new LOGON message can be sent to re-authenticate as a different user or with different credentials.

Sources: README.md100-101 README.md187-188 Diagram 2 from high-level architecture

Authentication Schemes

The Bolt protocol supports four authentication schemes, specified in the scheme field of the authentication dictionary:

Scheme Specifications

Scheme	Principal	Credentials	Use Case
none	(not required)	(not required)	Testing, local development, databases without authentication
basic	Username	Password	Standard username/password authentication
bearer	(not required)	Token	OAuth/JWT token-based authentication
kerberos	(not required)	Token	Kerberos/GSSAPI enterprise authentication

Detailed Scheme Descriptions

none: No authentication required. The server accepts the connection without verifying credentials.

basic: Standard username and password authentication.

bearer: Token-based authentication for OAuth 2.0, JWT, or similar systems.

kerberos: Enterprise authentication using Kerberos tickets.

Sources: README.md128-135

Message Flow by Protocol Version

The following diagram shows the complete authentication message flow for different protocol versions:

Sources: src/protocol/v1/InitMessage.php1-24 src/protocol/v3/HelloMessage.php1-24 README.md99-101

Response Handling

All authentication messages expect a response from the server. The response indicates whether authentication was successful or failed.

SUCCESS Response

A successful authentication returns a SUCCESS message (signature 0x70) with metadata:

INIT SUCCESS metadata:

• server: Server version string (e.g., "Neo4j/4.4.0")
• connection_id: Unique connection identifier

HELLO SUCCESS metadata (V3+):

• server: Server version string
• connection_id: Connection identifier
• hints: Dictionary of server capabilities and hints (V4+)

LOGON SUCCESS metadata:

• Typically empty or contains minimal session info

FAILURE Response

A failed authentication returns a FAILURE message (signature 0x7F) with error details:

• code: Error code string (e.g., "Neo.ClientError.Security.Unauthorized")
• message: Human-readable error description

After a FAILURE response, the connection enters the FAILED state and must be reset (V1-V2) or can retry authentication (V3+).

Example Response Consumption

Sources: tests/BoltTest.php59-73 tests/NornicDBTest.php22-40

State Transitions

Authentication messages affect the server state machine as follows:

The serverState property on the protocol instance tracks the current state, updated automatically when responses are consumed via getResponse() or getResponses().

Sources: README.md278-280 Diagram 5 from high-level architecture

Testing Authentication

The test suite validates authentication across all protocol versions and authentication schemes:

Test Helper: sayHello

The test infrastructure provides a sayHello() helper method that abstracts protocol version differences:

Test Examples

Basic authentication test: tests/BoltTest.php59-73

No-auth scheme test (NornicDB): tests/NornicDBTest.php22-40

SSL/TLS authentication test (Neo4j Aura): tests/BoltTest.php39-57

All tests verify that the authentication response has signature Signature::SUCCESS before proceeding with query execution.

Sources: tests/BoltTest.php33 tests/BoltTest.php59-73 tests/NornicDBTest.php36

Security Considerations

SSL/TLS Transport

Authentication credentials are transmitted in plaintext at the Bolt protocol layer. For production deployments, always use SSL/TLS encryption:

See SSL/TLS Configuration and Security for detailed configuration.

Password Handling

• Never hardcode credentials in source code
• Use environment variables or secure credential stores
• Rotate credentials regularly
• Use bearer tokens for programmatic access when possible

Authentication Scheme Selection

Environment	Recommended Scheme
Development/Testing	none or basic
Production (standalone)	basic with SSL/TLS
Production (enterprise)	kerberos with SSL/TLS
API/Service accounts	bearer with SSL/TLS

Sources: README.md235-268 tests/BoltTest.php39-57