| MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | PRELIMINARY |
| 2 | CONCEPT |
| 3 | tls (transport layer security) |
| 4 | |
| 5 | DESCRIPTION |
| 6 | TLS stands for Transport Layer Security which is the successor |
| 7 | of the well known SSL (Secure Socket Layer). Both techniques |
| 8 | provide a way to authenticate and encrypt the data send through |
| 9 | a network connection. |
| 10 | By enabling TLS during compilation of the driver you can provide |
| 11 | a secure channel into the mud to your players. |
| 12 | In difference to other solutions as "sslwrap" or "stunnel" the |
| 13 | driver integrated approach has the advantage that the mud sees |
| 14 | the real IP of the player, not the IP of the local mud host. |
| 15 | |
| 16 | USAGE |
| 17 | To use TLS configure your driver with --enable-tls option. |
| 18 | After starting your driver you have five new efuns |
| 19 | (tls_init_connection(), tls_deinit_connection(), tls_error(), |
| 20 | tls_query_connection_info(), tls_query_connection_state()). |
| 21 | |
| 22 | You can switch on TLS by calling tls_init_connection(). |
| 23 | This can happen in three ways: |
| 24 | |
| 25 | 1) in telnet_neg() |
| 26 | |
| 27 | Advantage of this method is that you can offer TLS on a normal |
| 28 | mud port. If you have a limited number of ports this can |
| 29 | become important. The TLS connection will be started by |
| 30 | the client with help of telnet option STARTTLS. Currently |
| 31 | there are no mudclients that support this method. |
| 32 | |
| 33 | You will have to implement the telnet option STARTTLS (46) for |
| 34 | this method. The draft for this can be found here: |
| 35 | http://www.ietf.org/proceedings/99mar/I-D/draft-ietf-tn3270e-telnet-tls-01.txt |
| 36 | Call tls_init_connection() to initiate the TLS handshake. |
| 37 | |
| 38 | |
| 39 | 2) in master_ob->connect() |
| 40 | |
| 41 | Advantage of this method is that your users can connect with |
| 42 | any program that supports TLS/SSL. Examples are telnet-ssl, |
| 43 | sslwrap or stunnel. Disadvantage is that you have to spend |
| 44 | a dedicated port for this. |
| 45 | |
| 46 | You have to call tls_init_connection() as first command |
| 47 | after the player connected (normally in master_ob->connect()) |
| 48 | |
| 49 | 3) in an interactive object using a callback. |
| 50 | |
| 51 | This method is similar to method (1), but not limited to |
| 52 | telnet: it is useful for implementing protocols thta use |
| 53 | STARTTLS like SMTP or IMAP. tls_init_connection() can be |
| 54 | called at any time by the interactive object. |
| 55 | |
| 56 | You must not write to the connection after calling this |
| 57 | efun until the callback is executed (the prompt will |
| 58 | be supressed automatically during this time). |
| 59 | |
| 60 | To test your code, you can use the openssl binary. |
| 61 | `openssl s_client -connect host:port' should display your certificate |
| 62 | and anything you write after the callback is executed. If you |
| 63 | encounter the error message `SSL3_GET_RECORD: wrong version number' |
| 64 | you're probably writing to the connection while you should not. |
| 65 | |
| 66 | BUG |
| 67 | This manpage might be not quite up to date with the implementation. |
| 68 | |
| 69 | HISTORY |
| 70 | Introduced in LDMud 3.3.474 and following, backported to 3.2.11. |
| 71 | |
| 72 | SEE ALSO |
| 73 | tls_* efuns |