net.openssl #

On Linux, TLS socket writes suppress SIGPIPE for each send. A closed peer produces an I/O error without changing the application's SIGPIPE handler. This also applies to writes performed during TLS handshakes, reads and shutdown.

Upgrade an accepted TCP connection to TLS

new_ssl_server_conn(mut tcp_conn, config) performs a server TLS handshake on an existing net.TcpConn, using the certificate and key in SSLConnectConfig. Use it for protocols such as SMTP STARTTLS that begin as plain TCP connections. The returned SSLConn borrows the TCP socket: keep tcp_conn open while using TLS, shut down the TLS connection, and then close tcp_conn.

Set validate: true and supply trusted client CA certificates in verify to require a valid client certificate. Without validate, client authentication is disabled. in_memory_verification makes cert, cert_key, and verify contain PEM data instead of file paths. Missing or invalid trust roots fail the upgrade when validation is enabled. Set alpn_protocols to the protocols the server may select during the handshake; each protocol name must contain 1 to 255 bytes.

Thread safety

SSLConn does not synchronize access to its TLS context. Serialize calls on the same connection, including reads, writes, timeout changes, and shutdown. Concurrent calls from one reader thread and one writer thread are unsupported. A blocking read held under a mutex can prevent the writer from progressing; the mutex alone is not a duplex adapter.

Keep a connected SSLConn at a stable address and stop all users before shutdown. See net.ssl thread safety for retry and lifetime guidance.

fn new_ssl_conn(config SSLConnectConfig) !&SSLConn

new_ssl_conn instance an new SSLCon struct

fn new_ssl_listener(saddr string, config SSLConnectConfig, options SSLListenerOptions) !&SSLListener

new_ssl_listener creates a new SSLListener binding to saddr with config.

fn new_ssl_server_conn(mut tcp_conn net.TcpConn, config SSLConnectConfig) !&SSLConn

new_ssl_server_conn wraps an already-established TCP connection in a server-side TLS connection using config's certificate. It performs the TLS handshake before returning. This enables protocols that upgrade a plain connection to TLS (e.g. SMTP STARTTLS). The caller retains ownership of tcp_conn and must keep it open until the returned TLS connection is shut down. With validate enabled, verify supplies the CA certificates trusted for client authentication. alpn_protocols configures the server's protocol selection.

struct C.BIO {
}

struct C.SSL {
}

struct C.SSL_CTX {
}

struct C.SSL_METHOD {
}

struct C.X509 {
}

struct SSLConn {
pub:
	config SSLConnectConfig
pub mut:
	sslctx        &C.SSL_CTX = unsafe { nil }
	ssl           &C.SSL     = unsafe { nil }
	handle        int
	duration      time.Duration
	read_deadline time.Time

	owns_socket bool
	// last_write_sent reports the most recent write_ptr's progress for retry
	// decisions: 0 = provably nothing was sent (safe to replay), or -1 = the
	// count is indeterminate because a failed/retryable write may have already
	// flushed complete records to the peer (TLS cannot prove zero). On full
	// success it equals the bytes written.
	last_write_sent int
}

SSLConn is a TLS connection. It does not synchronize access to its TLS context. Calls on the same connection must be serialized, including read, write, timeout changes, and close/shutdown. One reader and one writer must not call it concurrently.

fn (mut s SSLConn) close() !

close closes the ssl connection and does cleanup

fn (s &SSLConn) negotiated_alpn() string

negotiated_alpn returns the ALPN protocol selected during the TLS handshake (e.g. 'h2' or 'http/1.1'), or an empty string if no protocol was negotiated.

fn (mut s SSLConn) shutdown() !

shutdown closes the ssl connection and does cleanup

fn (mut s SSLConn) connect(mut tcp_conn net.TcpConn, hostname string) !

connect to server using OpenSSL. The socket of tcp_conn is switched to non-blocking mode and stays that way for the life of the SSL connection: every OpenSSL call in this backend is driven by a WANT_READ/WANT_WRITE retry loop that applies the configured timeout via wait_for_read/wait_for_write, and a blocking socket never yields WANT_READ — SSL_read() would sit in read() with no bound at all, ignoring set_read_timeout() (vlang/v#28506).

fn (mut s SSLConn) dial(hostname string, port int) !

dial opens an ssl connection on hostname:port

fn (s &SSLConn) read_timeout() time.Duration

read_timeout returns the current SSL read timeout.

fn (mut s SSLConn) set_read_timeout(timeout time.Duration)

set_read_timeout sets the read timeout used for subsequent SSL reads. A value of 0, or net.infinite_timeout means "wait forever".

fn (mut s SSLConn) set_read_deadline(deadline time.Time)

set_read_deadline sets an absolute deadline for subsequent reads.

fn (s &SSLConn) addr() !net.Addr

addr retrieves the local ip address and port number for this connection

fn (s &SSLConn) peer_addr() !net.Addr

peer_addr retrieves the ip address and port number used by the peer

fn (mut s SSLConn) socket_read_into_ptr(buf_ptr &u8, len int) !int

fn (mut s SSLConn) read(mut buffer []u8) !int

fn (mut s SSLConn) write_ptr(bytes &u8, len int) !int

write_ptr writes len bytes from bytes to the ssl connection

fn (mut s SSLConn) write(bytes []u8) !int

write writes data from bytes to the ssl connection

fn (mut s SSLConn) write_string(str string) !int

write_string writes a string to the ssl connection

fn (mut s SSLConn) wait_for_write(timeout time.Duration) !

wait_for_write waits for a write io operation to be available. Pure raw-socket select() on s.handle — never touches the TLS context, so it is safe to call without holding any lock that guards concurrent access to the context itself (see h2_pooled_transport.v).

fn (mut s SSLConn) wait_for_read(timeout time.Duration) !

wait_for_read waits for a read io operation to be available. Pure raw-socket select() on s.handle — never touches the TLS context, so it is safe to call without holding any lock that guards concurrent access to the context itself (see h2_pooled_transport.v).

fn (mut conn SSLConn) accept_handshake() !

accept_handshake performs the SSL handshake on the connection.

struct SSLConnectConfig {
pub:
	verify   string // the path to a rootca.pem file, containing trusted CA certificate(s)
	cert     string // the path to a cert.pem file, containing client certificate(s) for the request
	cert_key string // the path to a key.pem file, containing private keys for the client certificate(s)
	validate bool   // set this to true, if you want to stop requests, when their certificates are found to be invalid

	in_memory_verification bool // if true, verify, cert, and cert_key are read from memory, not from a file

	alpn_protocols []string // the list of ALPN protocols to advertise, e.g. ['h2', 'http/1.1']; empty means no ALPN extension is sent
}

struct SSLListener {
	saddr   string
	config  SSLConnectConfig
	options SSLListenerOptions
mut:
	tcp_listener &net.TcpListener = unsafe { nil }
	sslctx       &C.SSL_CTX       = unsafe { nil }
}

SSLListener is the SSL listener implementation for OpenSSL.

fn (mut l SSLListener) accept() !&SSLConn

accept accepts a new TCP connection and performs the SSL handshake.

fn (mut l SSLListener) accept_without_handshake() !&SSLConn

accept_without_handshake accepts a new TCP connection but does not perform the handshake yet.

fn (mut l SSLListener) shutdown() !

shutdown shuts down the SSL listener and releases the context.

struct SSLListenerOptions {
pub:
	family net.AddrFamily = .unspec
}

SSLListenerOptions configures the TCP listener used by an SSLListener.