| MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | PRELIMINARY |
| 2 | SYNOPSIS |
| 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 | |
| 7 | DESCRIPTION |
| 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 | |
| 42 | HISTORY |
| 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 | |
| 47 | SEE 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) |