blob: 25946a28aa654840903a61f4f493d5fea4007679 [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001PRELIMINARY
2CONCEPT
3 tls (transport layer security)
4
5DESCRIPTION
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
16USAGE
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
66BUG
67 This manpage might be not quite up to date with the implementation.
68
69HISTORY
70 Introduced in LDMud 3.3.474 and following, backported to 3.2.11.
71
72SEE ALSO
73 tls_* efuns