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

Last change on this file since 33672 was 33672, checked in by chust, 20 months ago

[openssl] Document ssl-start*

File size: 18.3 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)) => <input-port>, <output-port></procedure>
65
66Connect to the given {{host}} 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
76<procedure>(ssl-connect* #!key (hostname <string>) (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>
77
78Convenience 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.
79
80The {{hostname}} and {{port}} arguments determine the network address to connect to. See {{ssl-make-client-context*}} for a description of the other keyword arguments.
81
82<procedure>(ssl-make-client-context #!optional ((protocol <symbol>) 'sslv2-or-v3)) => <ssl-client-context></procedure>
83
84Creates a context to be supplied to {{ssl-connect}}.
85The context identifies a communication protocol (as selected by {{protocol}}),
86and also holds certificate information (i.e., the client's identity, its
87trusted certificate authorities, etc.).
88See the "Certificate procedures" section below for more information on
89certificates.
90
91The {{protocol}} must be one of the following:
92
93; {{'sslv2-or-v3}} : TLS protocol or SSL protocol versions 2 or 3, as appropriate
94; {{'sslv3}} : SSL protocol version 3
95; {{'tls}} or {{'tlsv1}} : the TLS protocol version 1
96; {{'tlsv11}} : the TLS protocol version 1.1
97; {{'tlsv12}} : the TLS protocol version 1.2
98
99The 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.
100
101By default, the context returned by {{ssl-make-client-context}}
102does not request verification of a server's certificate.
103Use {{ssl-set-verify!}} to enable such verification.
104
105<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>
106
107Convenience constructor for client contexts that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration and enables certificate verification.
108
109The {{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!}}.
110
111<procedure>(ssl-client-context? (obj <top>)) => <bool></procedure>
112
113Returns {{#t}} if {{obj}} is a value produced by {{ssl-make-client-context}} or {{ssl-make-client-context*}}, {{#f}} otherwise.
114
115==== Server procedures
116
117<procedure>(ssl-listen (port <exact>) #!optional ((backlog <exact>) 4) ((hostname <string>) #f) ((ctx <ssl-client-context|symbol>) 'sslv2-or-v3)) => <ssl-listener></procedure>
118
119Like {{tcp-listen}}, but the result is an SSL listener.
120The extra optional {{ctx}} argument is as for {{ssl-connect}}.
121
122The 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.
123
124Call {{ssl-load-certificate-chain!}} and {{ssl-load-private-key!}} to avoid a
125{{"no shared cipher"}} error on accepting connections.
126
127<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>
128
129Convenience constructor for an SSL listener that uses keyword arguments to convey initialization information. Uses sensible defaults for the protocol configuration.
130
131The {{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!}}.
132
133<procedure>(ssl-close (listener <ssl-listener>)) => <void></procedure><br>
134<procedure>(ssl-listener? (obj <top>)) => <bool></procedure><br>
135<procedure>(ssl-listener-port (listener <ssl-listener>)) => <exact></procedure><br>
136<procedure>(ssl-listener-fileno (listener <ssl-listener>)) => <exact></procedure><br>
137<procedure>(ssl-listener-accept-ready? (listener <ssl-listener>)) => <bool></procedure><br>
138<procedure>(ssl-accept (listener <ssl-listener>)) => <input-port>, <output-port></procedure>
139
140Analogous to {{tcp-close}}, {{tcp-listener?}}, {{tcp-listener-port}},
141{{tcp-listener-fileno}}, {{tcp-accept-ready?}} and {{tcp-accept}}.
142
143==== STARTTLS support
144
145<procedure>(ssl-start* (server? <bool>) (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>
146
147Given 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*}}.
148
149==== Certificate procedures
150
151<procedure>(ssl-load-certificate-chain! (obj <ssl-client-context|ssl-listener>) (pathname/blob <string|blob>)) => <void></procedure>
152
153Loads a PEM-format certification chain file or data blob for connections to be made
154with the given context (created by {{ssl-make-context}}) or listener
155(created by {{ssl-listener}}).
156
157This chain is used to identify the client or server when it connects or
158accepts connections. Loading a chain overwrites the old chain.
159Also call {{ssl-load-private-key!}} to load the certificate's
160corresponding key.
161
162<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>
163
164Loads the first private key from the file or data blob {{pathname/blob}} for the given client context
165or listener. The key goes with the certificate that identifies the client or server.
166
167If {{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.
168
169If {{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.
170
171If {{asn1?}} is {{#t}} and {{pathname/blob}} refers to a file, that file is parsed as ASN1 format instead of PEM.
172
173<procedure>(ssl-set-verify! (obj <ssl-client-context|ssl-listener>) (v <bool>)) => <void></procedure>
174
175Enables or disables verification of a connection peer's
176certificates. By default, verification is disabled.
177
178Enabling verification also requires, at a minimum, designating
179trusted certificate authorities with {{ssl-load-verify-root-certificates!}}.
180
181<procedure>(ssl-load-verify-root-certificates! (obj <ssl-client-context|ssl-listener>) (pathname <string>) #!optional ((dirname <string>) #f)) => <void></procedure>
182
183Loads a PEM-format file containing trusted certificates that are used
184to verify the certificates of a connection peer. Call this procedure
185multiple times to load multiple sets of trusted certificates.
186
187The optional second argument specifies a directory in which
188certificates are automatically looked up. You may also only pass a
189path in this argument and pass {{#f}} as the first argument to this
190procedure. See the OpenSSL documentation on
191[[http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html|SSL_CTX_load_verify_locations]] for more details.
192
193<procedure>(ssl-load-suggested-certificate-authorities! (obj <ssl-client-context|ssl-listener>) (pathname <string>)) => <void></procedure>
194
195Loads a PEM-format file containing certificates that are used by a
196server. The certificate list is sent to a client when the server
197requests a certificate as an indication of which certificates the
198server trusts.
199
200Loading the suggested certificates does not imply trust, however; any
201certificate presented by the client will be checked using the trusted
202roots loaded by {{ssl-load-verify-root-certificates!}}.
203
204==== Cipher selection
205
206<procedure>(ssl-set-cipher-list! (obj <ssl-client-context|ssl-listener>) (v <any>)) => <void></procedure>
207
208Selects a list of allowed cipher suites that are used by an SSL client or server.
209
210The 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}}.
211
212==== Port procedures
213
214<procedure>(ssl-port? obj) => <boolean></procedure>
215
216Predicate for SSL ports; returns {{#t}} if {{obj}} is an SSL port,
217{{#f}} if it isn't.
218
219<procedure>(ssl-port->tcp-port p) => <tcp-port></procedure>
220
221Convert SSL port {{p}} to the raw underlying TCP port.
222
223This is mostly useful if you need to obtain extra information about
224the connection, like for example {{tcp-addresses}}.  Note that you
225generally ''cannot'' safely send data over the port, as that would
226interfere with OpenSSL's operation.
227
228=== Changelog
229
230* 1.8.0 Add ssl-start* to support layering SSL on top of an existing TCP connection
231* 1.7.0 Various improvements including CHICKEN 4.10 compatibility and new constructors with more secure defaults
232* 1.6.2 Correct read-byte of chars with high bit set; fixes #954
233* 1.5.1 Small bugfixes by Mario Domenech Goulart
234* 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.
235* 1.4 Fix intermittent bug in ssl-write caused by the GC's moving around of memory locations
236* 1.3 Make ssl ports completely distinct from tcp ports. Add {{ssl-port?}} and {{ssl-port->tcp-port}} procedures.
237* 1.1.7 fix for vector deref crash (elf, reported by glogic)
238* 1.1.6 windows linking fixes by Alex Queiroz
239* 1.1.5 added static linking support [felix]
240* 1.1.4 fixed problems with the shutdown sequence
241* 1.1.3 fixes problem with older chickens and missing newline before `<#' in blocks of foreign code [Thanks to Dan Muresan]
242* 1.1.2 uses {{foreign-code}} macro insead of obsolete read syntax
243* 1.1.1 Output that would block properly suspends threads now
244* 1.1.0 {{##sys#tcp-port->fileno}} and {{tcp-addresses}} are now supported on SSL ports
245* 1.0.0 Corrections, tests against {{openssl s_server, openssl s_client}} and comparison with the PLT module
246* 0.4.0 Server functionality added
247* 0.3.1 Client-only with certificate functions
248* 0.2.0 Client-only prerelease
249
250=== License
251
252  Copyright (c) 2005, Thomas Chust <chust@web.de>.  All rights reserved.
253 
254  Redistribution and use in source and binary forms, with or without
255  modification, are permitted provided that the following conditions are met:
256 
257  Redistributions of source code must retain the above copyright notice,
258  this list of conditions and the following disclaimer. Redistributions in
259  binary form must reproduce the above copyright notice, this list of
260  conditions and the following disclaimer in the documentation and/or
261  other materials provided with the distribution. Neither the name of the
262  author nor the names of its contributors may be used to endorse or
263  promote products derived from this software without specific prior
264  written permission.
265
266  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
267  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
268  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
269  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
270  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
271  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
272  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
273  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
274  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
275  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
276  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.