blob: e33afae4364292c8ae5ff8f8e2388982808190cc [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001PRELIMINARY
2SYNOPSIS
3 int tls_init_connection(object ob)
4 int tls_init_connection(object ob, string fun, string|object fob, mixed extra...)
5 int tls_init_connection(object ob, closure fun, mixed extra...)
6
7DESCRIPTION
8 tls_init_connection() tries to start a TLS secured connection to
9 the interactive object <ob> (or this_object() if <ob> is not given).
10
11 Result:
12 errorcode < 0: unsuccessful, use tls_error() to get an useful
13 description of the error
14 number > 0: the secure connection is still being set up in the
15 background
16 number == 0: the secure connection is active.
17
18 OpenSSL only:
19
20 If the callback <fun>/<fun>:<fob> is specified, it will be called
21 once the fate of the secure connection has been determined. The
22 first argument will be the return code from the handshake
23 (errorcode < 0 on failure, or 0 on success), followed by the
24 interactive object <ob> and any <extra> arguments.
25
26 If the TLS setup fails, it is not necessary to call
27 tls_deinit_connection().
28
29 IMPORTANT: During the TLS handshake nothing else must be sent
30 to the client! For the most cases (TLS-capable clients logging in)
31 this means that the TLS handshake is the first and only thing the
32 client gets to see while the handshake is in progress.
33
34 The driver automatically suppresses the printing of the prompt
35 while the TLS handshake is in progress.
36
37 If tls_init_connection() is called in the master::connect() function,
38 the driver will either call the set callback in place of logon(), or
39 if not callback has been set, delay the call of logon() until the
40 state of the connection is clear.
41
42HISTORY
43 Introduced in LDMud 3.3.474 and following, backported to 3.2.11.
44 LDMud 3.2.13/3.3.713 streamlined the handling of secure connections
45 during logon.
46
47SEE ALSO
48 tls_deinit_connection(E), tls_error(E), tls_query_connection_state(E),
49 tls_query_connection_info(E), tls_available(E),
50 tls_check_certificate(E), tls_refresh_certs(E), connect(M), logon(A)