source: project/wiki/eggref/4/openssl @ 34305

Last change on this file since 34305 was 34305, checked in by chust, 6 months ago

[openssl] Documented client-side SNI support

File size: 18.6 KB
Line 
1== openssl
2
3=== Description
4
5Bindings to the OpenSSL SSL/TLS library
6
7=== Author
8
9[[http://www.chust.org/|Thomas Chust]]
10
11=== Requirements
12
13None, except for the openssl C library of course.
14
15=== Documentation
16
17This reference is basically a copy of the documentation of
18[[http://www.plt-scheme.org/|PLT Scheme's]] openssl module.
19The API provided here is largely compatible with that one.
20The exceptions are the missing {{.../enable-break}} and {{ssl-available?}}
21procedures and the missing {{reuse?}} argument to {{ssl-listen}}.
22
23Please note that all the procedures described here may fail and raise
24a non-continuable exception of the composite type {{(exn i/o net openssl)}}.
25The {{openssl}} property condition contains a property called {{status}}
26which will be bound to a symbol corresponding to the OpenSSL error code
27that was encountered. It may have the following values:
28
29; {{'zero-return}} : The SSL/TLS connection was shut down unexpectedly but in a controlled way
30; {{'want-read}} : The operation didn't finish because data must be read from a nonblocking socket. This error condition only occurs though, when it could not be handled automatically because there is actually no socket involved or some other strange thing happended in the OpenSSL library.
31; {{'want-write}} : The operation didn't finish because data must be read from a nonblocking socket. The same comment as for {{'want-read}} applies.
32; {{'want-connect}} : The operation didn't finish because a nonblocking socket must first be connected. The same comment as for {{'want-read}} applies.
33; {{'want-accept}} : The operation didn't finish because a nonblocking socket must first be acepted. The same comment as for {{'want-read}} applies.
34; {{'want-X509-lookup}} : The operation failed because an application callback that could not even have been registered through this API was apparently registered anyway and has asked to be called again.
35; {{'syscall}} : Some low-level I/O error occurred.
36; {{'ssl}} : Something went wrong in the OpenSSL library itself.
37; {{#f}} : The error is not classified
38
39Of course the exception that is thrown also has an appropriate message set.
40If you feel that this documentation lacks some information, please also
41consider the
42[[http://www.openssl.org/docs/ssl/ssl.html|manual pages of OpenSSL itself]].
43
44===== Global parameters
45
46For read and write timeouts, {{tcp-read-timeout}} and {{tcp-write-timeout}} are honored.
47
48<parameter>(ssl-handshake-timeout [TIMEOUT])</parameter>
49
50The time in milliseconds to wait for a SSL handshake to complete (after {{ssl-connect}} or {{ssl-accept}}). Defaults to 120000, ie two minutes.
51
52'''note''': The handshake is only initiated after the first read or the first write action occurs on the connection, so the timer is started upon that first action.
53
54<parameter>(ssl-shutdown-timeout [TIMEOUT])</parameter>
55
56The time in milliseconds to wait for a SSL shutdown operation to complete (after closing a port). Defaults to 120000, ie two minutes.
57
58<parameter>(ssl-default-certificate-authority-directory [DIRECTORY])</parameter>
59
60The default directory containing trusted CA certificates that is used if verification is enabled but not explicitly configured using the convenience constructors.
61
62===== Client procedures
63
64<procedure>(ssl-connect (hostname <string>) #!optional (port <exact>) ((ctx <ssl-client-context|symbol>) 'sslv2-or-v3) (sni-name <string|bool>)) => <input-port>, <output-port></procedure>
65
66Connect to the given {{hostname}} on the given {{port}} (a number from 1 to 65535).
67This connection will be encrypted using SSL.
68The return values are as tcp-connect; an input port and an output port.
69
70The optional {{ctx}} argument determines which encryption protocol is
71used, whether the server's certificate is checked, etc.
72The argument can be either a client context created by {{ssl-make-client-context}}
73(see below), or one of the following symbols: {{'sslv2-or-v3}} (the default), {{'sslv3}}, {{'tls}}, {{'tlsv1}}, {{'tlsv11}} or {{'tlsv12}}. See {{ssl-make-client-context}}
74for further details, including the meanings of the protocol symbols.
75
76The optional {{sni-name}} argument determines whether a virtual hostname is sent with the connection handshake. if {{sni-name}} is a string, that value is sent as the virtual hostname. Otherwise, if {{sni-name}} is not {{#f}}, the value of {{hostname}} is sent as the virtual hostname, too.
77
78<procedure>(ssl-connect* #!key (hostname <string>) (sni-name <string|bool>) (port <exact>) ((protocol <symbol>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string|blob>) (private-key <string|blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #t)) => <input-port>, <output-port></procedure>
79
80Convenience constructor for SSL connections that uses keyword arguments to convey client context initialization information. Uses sensible defaults for the protocol configuration and enables certificate verification.
81
82The {{hostname}} and {{port}} arguments determine the network address to connect to. See {{ssl-make-client-context*}} for a description of the other keyword arguments.
83
84<procedure>(ssl-make-client-context #!optional ((protocol <symbol>) 'sslv2-or-v3)) => <ssl-client-context></procedure>
85
86Creates a context to be supplied to {{ssl-connect}}.
87The context identifies a communication protocol (as selected by {{protocol}}),
88and also holds certificate information (i.e., the client's identity, its
89trusted certificate authorities, etc.).
90See the "Certificate procedures" section below for more information on
91certificates.
92
93The {{protocol}} must be one of the following:
94
95; {{'sslv2-or-v3}} : TLS protocol or SSL protocol versions 2 or 3, as appropriate
96; {{'sslv3}} : SSL protocol version 3
97; {{'tls}} or {{'tlsv1}} : the TLS protocol version 1
98; {{'tlsv11}} : the TLS protocol version 1.1
99; {{'tlsv12}} : the TLS protocol version 1.2
100
101The default protocol is {{'sslv2-or-v3}}, which ensures maximum compatibility with other endpoints. Note, however, that this choice is not particularly secure. Vulnerabilities affecting only the legacy protocols can be avoided by explicitly requesting the {{'tls}} protocol, if every peer you will be communicating with is supporting this.
102
103By default, the context returned by {{ssl-make-client-context}}
104does not request verification of a server's certificate.
105Use {{ssl-set-verify!}} to enable such verification.
106
107<procedure>(ssl-make-client-context* #!key ((protocol <symbol>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string|blob>) (private-key <string|blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #t)) => <ssl-client-context></procedure>
108
109Convenience constructor for client contexts that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration and enables certificate verification.
110
111The {{protocol}} can be any of the choices available for {{ssl-make-client-context}}, but it defaults to the modern {{'tlsv12}}. You can customize the list of allowed cipher suites using the {{cipher-list}} argument, which is passed to {{ssl-set-cipher-list!}}. A client certificate and associated private key can be loaded using the {{certificate}} and {{private-key}} arguments, which may be strings representing file paths or blobs containing the data itself; see {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} for details. The verification of server certificates may be enabled (the default) or disabled using {{verify?}}; the set of trusted CA certificates can be specified by {{certificate-authorities}} and {{certificate-authority-directory}}, which are passed to {{ssl-load-verify-root-certificates!}}.
112
113<procedure>(ssl-client-context? (obj <top>)) => <bool></procedure>
114
115Returns {{#t}} if {{obj}} is a value produced by {{ssl-make-client-context}} or {{ssl-make-client-context*}}, {{#f}} otherwise.
116
117==== Server procedures
118
119<procedure>(ssl-listen (port <exact>) #!optional ((backlog <exact>) 4) ((hostname <string>) #f) ((ctx <ssl-client-context|symbol>) 'sslv2-or-v3)) => <ssl-listener></procedure>
120
121Like {{tcp-listen}}, but the result is an SSL listener.
122The extra optional {{ctx}} argument is as for {{ssl-connect}}.
123
124The default protocol is {{'sslv2-or-v3}}, which ensures maximum compatibility with clients. Note, however, that this choice is not particularly secure. Vulnerabilities affecting only the legacy protocols can be avoided by explicitly requesting the {{'tls}} protocol, if every client that will connect to the server is supporting this.
125
126Call {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} to avoid a
127{{"no shared cipher"}} error on accepting connections.
128
129<procedure>(ssl-listen* #!key (hostname <string>) ((port <exact>) 0) ((backlog <exact>) 4) ((protocol <symbol>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string|blob>) (private-key <string|blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) #f)) => <ssl-listener></procedure>
130
131Convenience constructor for an SSL listener that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration.
132
133The {{hostname}} argument determines the local network interface to listen on and defaults to the wildcard address. The {{port}} arguments determine the local network port to listen to and defaults to a randomly selected port. The {{protocol}} can be any of the choices available for {{ssl-listen}}, but it defaults to the modern {{'tlsv12}}. You can customize the list of allowed cipher suites using the {{cipher-list}} argument, which is passed to {{ssl-set-cipher-list!}}. A server certificate and associated private key can be loaded using the {{certificate}} and {{private-key}} arguments, which may be strings representing file paths or blobs containing the data itself; see {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} for details. The verification of client certificates may be enabled or disabled (the default) using {{verify?}}; the set of trusted CA certificates can be specified by {{certificate-authorities}} and {{certificate-authority-directory}}, which are passed to {{ssl-load-verify-root-certificates!}}.
134
135<procedure>(ssl-close (listener <ssl-listener>)) => <void></procedure><br>
136<procedure>(ssl-listener? (obj <top>)) => <bool></procedure><br>
137<procedure>(ssl-listener-port (listener <ssl-listener>)) => <exact></procedure><br>
138<procedure>(ssl-listener-fileno (listener <ssl-listener>)) => <exact></procedure><br>
139<procedure>(ssl-listener-accept-ready? (listener <ssl-listener>)) => <bool></procedure><br>
140<procedure>(ssl-accept (listener <ssl-listener>)) => <input-port>, <output-port></procedure>
141
142Analogous to {{tcp-close}}, {{tcp-listener?}}, {{tcp-listener-port}},
143{{tcp-listener-fileno}}, {{tcp-accept-ready?}} and {{tcp-accept}}.
144
145==== STARTTLS support
146
147<procedure>(ssl-start* (server? <bool>) (sni-name <string>) (tcp-in <input-port>) (tcp-out <output-port>) #!key ((protocol <symbol>) 'tlsv12) ((cipher-list <any>) "DEFAULT") (certificate <string|blob>) (private-key <string|blob>) ((private-key-type <symbol>) 'rsa) (private-key-asn1? <bool>) (certificate-authorities <string>) (certificate-authority-directory <string>) ((verify? <bool>) (not server?))) => <input-port>, <output-port></procedure>
148
149Given existing TCP input and output ports, {{ssl-start*}} establishes an SSL context working on top of the TCP connection. The returned ports should be used for all further communication with the remote peer. {{ssl-start*}} acts similar to {{ssl-connect*}} if {{server?}} is false or to {{ssl-accept}} if {{server?}} is true. The arguments all behave analogous to those for {{ssl-connect*}} or {{ssl-listen*}}.
150
151==== Certificate procedures
152
153<procedure>(ssl-load-certificate-chain! (obj <ssl-client-context|ssl-listener>) (pathname/blob <string|blob>)) => <void></procedure>
154
155Loads a PEM-format certification chain file or data blob for connections to be made
156with the given context (created by {{ssl-make-context}}) or listener
157(created by {{ssl-listener}}).
158
159This chain is used to identify the client or server when it connects or
160accepts connections. Loading a chain overwrites the old chain.
161Also call {{ssl-load-private-key!}} to load the certificate's
162corresponding key.
163
164<procedure>(ssl-load-private-key! (obj <ssl-client-context|ssl-listener>) (pathname/blob <string|blob>) #!optional ((rsa? <symbol|bool>) #t) ((asn1? <bool>) #f)) => <void></procedure>
165
166Loads the first private key from the file or data blob {{pathname/blob}} for the given client context
167or listener. The key goes with the certificate that identifies the client or server.
168
169If {{rsa?}} is {{#t}} or {{'rsa}}, the first RSA key is read (i.e., non-RSA keys are skipped). If {{rsa?}} is {{#f}} or {{'dsa}}, a DSA key is read.
170
171If {{pathname/blob}} is a data blob, the key must be ASN1 encoded and {{rsa?}} may also take the values {{'dh}} or {{'ec}} to load Diffie-Hellman or Elliptic Curve keys respectively.
172
173If {{asn1?}} is {{#t}} and {{pathname/blob}} refers to a file, that file is parsed as ASN1 format instead of PEM.
174
175<procedure>(ssl-set-verify! (obj <ssl-client-context|ssl-listener>) (v <bool>)) => <void></procedure>
176
177Enables or disables verification of a connection peer's
178certificates. By default, verification is disabled.
179
180Enabling verification also requires, at a minimum, designating
181trusted certificate authorities with {{ssl-load-verify-root-certificates!}}.
182
183<procedure>(ssl-load-verify-root-certificates! (obj <ssl-client-context|ssl-listener>) (pathname <string>) #!optional ((dirname <string>) #f)) => <void></procedure>
184
185Loads a PEM-format file containing trusted certificates that are used
186to verify the certificates of a connection peer. Call this procedure
187multiple times to load multiple sets of trusted certificates.
188
189The optional second argument specifies a directory in which
190certificates are automatically looked up. You may also only pass a
191path in this argument and pass {{#f}} as the first argument to this
192procedure. See the OpenSSL documentation on
193[[http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html|SSL_CTX_load_verify_locations]] for more details.
194
195<procedure>(ssl-load-suggested-certificate-authorities! (obj <ssl-client-context|ssl-listener>) (pathname <string>)) => <void></procedure>
196
197Loads a PEM-format file containing certificates that are used by a
198server. The certificate list is sent to a client when the server
199requests a certificate as an indication of which certificates the
200server trusts.
201
202Loading the suggested certificates does not imply trust, however; any
203certificate presented by the client will be checked using the trusted
204roots loaded by {{ssl-load-verify-root-certificates!}}.
205
206==== Cipher selection
207
208<procedure>(ssl-set-cipher-list! (obj <ssl-client-context|ssl-listener>) (v <any>)) => <void></procedure>
209
210Selects a list of allowed cipher suites that are used by an SSL client or server.
211
212The given value {{v}} may be a string such as {{"DEFAULT"}}; the format of strings accepted by the OpenSSL library is described in its ciphers(1) manual page. If you pass a list as {{v}}, its elements are joined by {{":"}} characters. Any other value for {{v}} and any list elements are converted to strings using {{->string}}.
213
214==== Port procedures
215
216<procedure>(ssl-port? obj) => <boolean></procedure>
217
218Predicate for SSL ports; returns {{#t}} if {{obj}} is an SSL port,
219{{#f}} if it isn't.
220
221<procedure>(ssl-port->tcp-port p) => <tcp-port></procedure>
222
223Convert SSL port {{p}} to the raw underlying TCP port.
224
225This is mostly useful if you need to obtain extra information about
226the connection, like for example {{tcp-addresses}}.  Note that you
227generally ''cannot'' safely send data over the port, as that would
228interfere with OpenSSL's operation.
229
230=== Changelog
231
232* 1.8.0 Add ssl-start* to support layering SSL on top of an existing TCP connection
233* 1.7.0 Various improvements including CHICKEN 4.10 compatibility and new constructors with more secure defaults
234* 1.6.2 Correct read-byte of chars with high bit set; fixes #954
235* 1.5.1 Small bugfixes by Mario Domenech Goulart
236* 1.5 Do not let ssl-accept or ssl-connect block immediately but defer it until reading or writing to the ports. Add {{ssl-handshake-timeout}} and {{ssl-shutdown-timeout}} options.
237* 1.4 Fix intermittent bug in ssl-write caused by the GC's moving around of memory locations
238* 1.3 Make ssl ports completely distinct from tcp ports. Add {{ssl-port?}} and {{ssl-port->tcp-port}} procedures.
239* 1.1.7 fix for vector deref crash (elf, reported by glogic)
240* 1.1.6 windows linking fixes by Alex Queiroz
241* 1.1.5 added static linking support [felix]
242* 1.1.4 fixed problems with the shutdown sequence
243* 1.1.3 fixes problem with older chickens and missing newline before `<#' in blocks of foreign code [Thanks to Dan Muresan]
244* 1.1.2 uses {{foreign-code}} macro insead of obsolete read syntax
245* 1.1.1 Output that would block properly suspends threads now
246* 1.1.0 {{##sys#tcp-port->fileno}} and {{tcp-addresses}} are now supported on SSL ports
247* 1.0.0 Corrections, tests against {{openssl s_server, openssl s_client}} and comparison with the PLT module
248* 0.4.0 Server functionality added
249* 0.3.1 Client-only with certificate functions
250* 0.2.0 Client-only prerelease
251
252=== License
253
254  Copyright (c) 2005, Thomas Chust <chust@web.de>.  All rights reserved.
255 
256  Redistribution and use in source and binary forms, with or without
257  modification, are permitted provided that the following conditions are met:
258 
259  Redistributions of source code must retain the above copyright notice,
260  this list of conditions and the following disclaimer. Redistributions in
261  binary form must reproduce the above copyright notice, this list of
262  conditions and the following disclaimer in the documentation and/or
263  other materials provided with the distribution. Neither the name of the
264  author nor the names of its contributors may be used to endorse or
265  promote products derived from this software without specific prior
266  written permission.
267
268  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
269  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
270  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
271  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
272  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
273  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
274  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
275  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
276  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
277  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
278  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.