SSL/TLS Configuration and Security

This document covers SSL/TLS encryption configuration for secure communication with graph databases. It details the StreamSocket connection class, the setSslContextOptions() method, and security best practices for both cloud and self-hosted deployments.

For general connection management and choosing between connection implementations, see Connection Implementations. For persistent connection handling, see Persistent Connections with PStreamSocket.

---

Connection Classes and SSL Support

SSL/TLS encryption is only available with stream-based connection classes. The library provides three connection implementations with different SSL capabilities:

Connection Class	SSL Support	Use Case
Socket	❌ No	Local development, unencrypted connections
StreamSocket	✅ Yes	Standard encrypted connections
PStreamSocket	✅ Yes (inherited)	Persistent encrypted connections with caching

The Socket class src/connection/Socket.php16-160 uses the PHP sockets extension and does not support SSL/TLS. For encrypted connections, you must use either StreamSocket or PStreamSocket.

SSL/TLS Support Architecture

Sources: src/connection/Socket.php1-161 src/connection/StreamSocket.php1-146 README.md215-233

---

Enabling SSL/TLS

SSL/TLS is enabled by calling the setSslContextOptions() method on a StreamSocket or PStreamSocket instance before connecting.

Method Signature

StreamSocket::setSslContextOptions(?array $options = []): void

The method accepts a nullable array parameter src/connection/StreamSocket.php34-37:

• null: Disables SSL/TLS (unencrypted connection)
• [] (empty array): Enables SSL/TLS with default PHP configuration
• [key => value, ...]: Enables SSL/TLS with custom context options

Basic Usage Pattern

Sources: src/connection/StreamSocket.php29-37 README.md236-249

---

SSL/TLS Connection Initialization Flow

The SSL/TLS handshake occurs during the connect() method execution:

The implementation is in src/connection/StreamSocket.php39-67 Key steps:

1. Context Creation src/connection/StreamSocket.php41-46: Creates a stream context with socket and SSL options
2. TCP Connection src/connection/StreamSocket.php48: Establishes the base TCP connection using stream_socket_client()
3. SSL Handshake src/connection/StreamSocket.php58-62: If $sslContextOptions !== null, enables encryption with stream_socket_enable_crypto()

Sources: src/connection/StreamSocket.php39-67

---

SSL Context Options

The setSslContextOptions() method accepts an array following PHP's SSL context specification. All options documented at php.net/manual/en/context.ssl.php are supported.

Common SSL Context Options

Option	Type	Description	Default
peer_name	string	Override peer name for verification	Hostname from connection
verify_peer	bool	Require verification of SSL certificate	true
verify_peer_name	bool	Require verification of peer name	true
allow_self_signed	bool	Allow self-signed certificates	false
cafile	string	Path to CA certificate file	System CA bundle
capath	string	Path to directory of CA certificates	System CA path
local_cert	string	Path to local certificate file	None
local_pk	string	Path to private key file	None
passphrase	string	Passphrase for private key	None
ciphers	string	Allowed cipher list	PHP default
security_level	int	OpenSSL security level (0-5)	System default

Internal Usage

The SSL context is applied in two places:

1. During context creation src/connection/StreamSocket.php41-46:

   $context = stream_context_create([
    'socket' => ['tcp_nodelay' => true],
    'ssl' => (array)$this->sslContextOptions
   ]);
   

2. During crypto enablement src/connection/StreamSocket.php58-62:

   if ($this->sslContextOptions !== null) {
    if (stream_socket_enable_crypto($this->stream, true, STREAM_CRYPTO_METHOD_ANY_CLIENT) !== true) {
    throw new ConnectException('Enable encryption error');
    }
   }
   

Sources: src/connection/StreamSocket.php19 src/connection/StreamSocket.php39-67 README.md250

---

Common Configuration Scenarios

Neo4j Aura (Cloud)

Neo4j Aura requires encrypted connections. The minimal configuration uses default SSL validation:

Aura uses certificates signed by trusted CAs, so the default PHP certificate bundle is sufficient tests/BoltTest.php39-57

With explicit peer verification:

The test suite validates this configuration tests/BoltTest.php39-57:

Self-Signed Certificates (Development)

For localhost development with self-signed certificates, verification must be relaxed README.md252-265:

⚠️ Security Warning: This configuration disables certificate validation and should never be used in production environments.

Production with Custom CA

For production deployments with internal CA or custom certificates:

Persistent Connections with SSL

PStreamSocket extends StreamSocket and inherits SSL support README.md229-233:

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

---

Configuration Decision Matrix

Sources: README.md215-268 src/connection/StreamSocket.php1-146

---

Security Best Practices

1. Always Enable SSL for Production

Unencrypted Bolt connections transmit credentials and data in cleartext. Always use SSL/TLS for:

• Cloud deployments (Neo4j Aura, AWS Neptune, etc.)
• Production on-premise installations
• Any network where traffic may be intercepted

2. Verify Peer Certificates

Never disable verify_peer or verify_peer_name in production:

3. Use Strong Ciphers

For high-security environments, explicitly configure cipher suites:

4. Protect Private Keys

When using client certificates:

• Store private keys with restricted file permissions (600 or 400)
• Use passphrase protection
• Never commit keys to version control
• Use environment variables for paths and passphrases

5. Validate Hostname

For multi-domain certificates or when the connection hostname differs from the certificate:

6. Certificate Pinning (Advanced)

For maximum security, implement certificate pinning by specifying the exact CA:

Sources: README.md236-268

---

Required PHP Extensions

SSL/TLS support requires the openssl PHP extension README.md53-54:

Check extension availability before attempting SSL connections. The StreamSocket class itself does not validate this requirement; SSL operations will fail at runtime if the extension is missing.

Sources: README.md49-54

---

Error Handling

Connection Failures

SSL/TLS connection failures throw ConnectException src/connection/StreamSocket.php50-52:

Crypto Enablement Failures

If stream_socket_enable_crypto() fails, a ConnectException is thrown with the message "Enable encryption error" src/connection/StreamSocket.php60-61:

Common causes:

• Missing or invalid certificates
• Cipher mismatch between client and server
• OpenSSL extension not loaded
• Server doesn't support TLS

Debugging SSL Issues

Enable debug mode to inspect the binary communication:

This outputs hexadecimal representation of all data sent and received src/connection/StreamSocket.php71-72 which can help diagnose:

• Whether SSL handshake completes
• If data is encrypted (appears as random hex)
• Connection timing issues

Sources: src/connection/StreamSocket.php50-62 README.md93

---

Testing SSL Connections

The test suite validates SSL functionality in multiple scenarios tests/BoltTest.php39-57:

Aura Connection Test

The test demonstrates:

• URL parsing with neo4j+s:// scheme
• Peer verification enabled
• Successful authentication over encrypted connection

Local Development Testing

For testing with self-signed certificates:

Sources: tests/BoltTest.php39-57 phpunit.xml1-28

---

Comparison with Socket Class

Feature	Socket	StreamSocket/PStreamSocket
PHP Extension	ext-sockets required	Built-in stream functions
SSL/TLS Support	❌ None	✅ Full support
Configuration Method	N/A	setSslContextOptions()
Use Case	Local unencrypted	Production encrypted
Certificate Validation	N/A	Configurable
Performance	Slightly better memory	Standard

The Socket class src/connection/Socket.php16-160 has no SSL capabilities because the PHP sockets extension does not provide SSL/TLS functions. For any encrypted connection, you must use StreamSocket or its persistent variant PStreamSocket.

Sources: src/connection/Socket.php1-161 src/connection/StreamSocket.php1-146 README.md215-233