SYNOPSIS (EXPERIMENTAL)

int	tls_init_connection	(	object ob	)
int	tls_init_connection	(	object ob,	string fun,	string|object fob,	mixed extra...	)
int	tls_init_connection	(	object ob,	closure fun,	mixed extra...	)

DESCRIPTION

Tries to start a TLS-secured connection to the interactive object ob (or this_object() if ob is not given).

Result:

errorcode < 0: unsuccessful, use tls_error() to get a useful description of the error number > 0 : the secure connection is still being set up in the background number == 0 : the secure connection is active.

OpenSSL only:

If the callback <fun>/<fun>:<fob> is specified, it will be called once the fate of the secure connection has been determined. The first argument will be the return code from the handshake (errorcode < 0 on failure, or 0 on success), followed by the interactive object ob and any extra arguments.

If the TLS setup fails, it is not necessary to call tls_deinit_connection(E).

Warning

During the TLS handshake nothing else must be sent to the client! For the most cases (TLS-capable clients logging in) this means that the TLS handshake is the first and only thing the client gets to see while the handshake is in progress.

The driver automatically suppresses the printing of the prompt while the TLS handshake is in progress.

If tls_init_connection(E) is called in the connect(M) function, the driver will either call the set callback in place of logon(A), or if no callback has been set, delay the call of logon(A) until the state of the connection is clear.

HISTORY

• introduced (3.3.474)
• backported (3.2.11)
• changed (3.2.13/3.3.713) – streamlined the handling of secure connections during logon.

SEE ALSO

tls_deinit_connection(E), tls_error(E), tls_query_connection_state(E),:efun:efun::tls_query_connection_info(), tls_available(E),:efun:efun::tls_check_certificate(), tls_refresh_certs(E), connect(M)logon(A)