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

Last change on this file since 36600 was 36600, checked in by wasamasa, 2 years ago

Release 2.0.1

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