source: project/wiki/eggref/5/openssl @ 37360

Last change on this file since 37360 was 37360, checked in by wasamasa, 3 months ago

Release 2.0.3

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