284 lines
10 KiB
Plaintext
284 lines
10 KiB
Plaintext
The _openssl_ collection provides glue for the OpenSSL library with
|
|
the MzScheme port system. The OpenSSL collection provides functions
|
|
nearly identically to the standard TCP subsystem in PLT Scheme, plus a
|
|
generic `ports->ssl-ports' interface.
|
|
|
|
To use this library, you will need OpenSSL installed on your
|
|
machine, but
|
|
|
|
* for Windows, the PLT Scheme distribution for Windows includes the
|
|
necessary DLLs;
|
|
|
|
* for Mac OS X, version 10.2 and later provides the necessary OpenSSL
|
|
libraries.
|
|
|
|
* for Unix, libssl.so and libcryto.so are likely to be installed on
|
|
your machine, already.
|
|
|
|
==================================================
|
|
|
|
_mzssl.ss_ library
|
|
|
|
The variables below are provided the by "mzssl.ss" library.
|
|
|
|
> ssl-available?
|
|
|
|
A boolean value which says whether the system openssl library was
|
|
successfully loaded. Calling `ssl-connect', etc when this value is
|
|
#f (library not loaded) will raise an error.
|
|
|
|
> ssl-load-failure-reason
|
|
|
|
Either #f (when `ssl-available?' is #t) or an error string (when
|
|
`ssl-available?' is #f).
|
|
|
|
|
|
-- TCP-like Client procedures ----------------------------------------
|
|
|
|
> (ssl-connect hostname port-k [client-context-or-protocol-symbol])
|
|
|
|
Connect to the given host (a string) on the given port-k (a number
|
|
from 1 to 65535). This connection will be encrypted using SSL. The
|
|
return values are as for `tcp-connect': an input port and an output
|
|
port.
|
|
|
|
The optional `context-or-protocol-symbol' argument determines which
|
|
encryption protocol is used, whether the server's certificate is
|
|
checked, etc. The argument can be either a client context created by
|
|
`ssl-make-client-context' (see below), or one of the following
|
|
symbols: 'sslv2-or-v3 (the default), 'sslv2, 'sslv3, or 'tls; see
|
|
`ssl-make-client-context' for further details (including the meanings of
|
|
the protocol symbols).
|
|
|
|
Closing the resulting output port does not send a shutdown message to
|
|
the server. See also `ports->ssl-ports'.
|
|
|
|
Beware that the SSL protocol allows reading or writing in only one
|
|
direction at a time. If you request data from the input port, then
|
|
data cannot be written to the output port (i.e., attempting to write
|
|
will block) until the other end of the connection responds to the
|
|
read. Even merely checking for input data --- using `byte-ready?', for
|
|
example --- commits the connection to reading, and the other end must
|
|
respond with a (possibly zero-length) answer. Protocols that work with
|
|
SSL, such as IMAP, have a well-defined communication pattern, where
|
|
theres no question of whether the other end is supposed to be sending
|
|
or reading data.
|
|
|
|
|
|
> (ssl-connect/enable-break hostname port-k [client-context-or-protocol-symbol])
|
|
|
|
Like `ssl-connect', but breaking is enabled while trying to connect.
|
|
|
|
|
|
> (ssl-make-client-context [protocol-symbol])
|
|
|
|
Creates a context to be supplied to `ssl-connect'. The context
|
|
identifies a communication protocol (as selected by `protocol-symbol'),
|
|
and also holds certificate information (i.e., the client's identity,
|
|
its trusted certificate authorities, etc.). See the "Certificate
|
|
procedures" section below for more information on certificates.
|
|
|
|
The `protocol-symbol' must be one of the following:
|
|
|
|
* _'sslv2-or-v3_ : SSL protocol versions 2 or 3, as
|
|
appropriate (this is the default)
|
|
|
|
* _'sslv2_ : SSL protocol version 2
|
|
|
|
* _'sslv3_ : SSL protocol version 3
|
|
|
|
* _'tls_ : the TLS protocol version 1
|
|
|
|
By default, the context returned by `ssl-make-client-context' does not
|
|
request verification of a server's certificate. Use `ssl-set-verify!'
|
|
to enable such verification.
|
|
|
|
|
|
> (ssl-client-context? v)
|
|
|
|
Returns #t if `v' is a value produced by `ssl-make-client-context', #f
|
|
otherwise.
|
|
|
|
|
|
-- TCP_like Server procedures ----------------------------------------
|
|
|
|
> (ssl-listen port-k [queue-k reuse? hostname-or-#f server-context-or-protocol-symbol])
|
|
|
|
Like `tcp-listen', but the result is an SSL listener (which is a
|
|
waitable object). The extra optional `server-context-protocol-symbol'
|
|
is as for `ssl-connect', except that a context must be a server
|
|
context instead of a client context.
|
|
|
|
Call `ssl-load-certificate-chain!' and `ssl-load-private-key!' to
|
|
avoid a _no shared cipher_ error on accepting connections. The file
|
|
"test.pem" in the "openssl" collection is a suitable argument for both
|
|
calls when testing. Since "test.pem" is public, however, such a test
|
|
configuration obviously provides no security.
|
|
|
|
|
|
> (ssl-close ssl-listener)
|
|
> (ssl-listener? v)
|
|
|
|
Analogous to `tcp-close' and `tcp-listener?'.
|
|
|
|
|
|
> (ssl-accept ssl-listener)
|
|
|
|
Analogous to `tcp-accept'.
|
|
|
|
Closing the resulting output port does not send a shutdown message to
|
|
the client. See also `ports->ssl-ports'.
|
|
|
|
See also `ssl-connect' about the limitations of reading and writing to
|
|
an SSL connection (i.e., one direction at a time).
|
|
|
|
|
|
> (ssl-accept/enable-break ssl-listener)
|
|
|
|
Analogous to `tcp-accept/enable-break'.
|
|
|
|
|
|
> (ssl-make-server-context [protocol-symbol])
|
|
|
|
Like `ssl-make-client-context', but creates a server context.
|
|
|
|
|
|
> (ssl-server-context? v)
|
|
|
|
Returns #t if `v' is a value produced by `ssl-make-server-context', #f
|
|
otherwise.
|
|
|
|
|
|
-- SSL-wrapper interface ----------------------------------------
|
|
|
|
> (ports->ssl-ports input-port output-port
|
|
[#:mode mode-symbol]
|
|
[#:context context]
|
|
[#:encrypt protocol-symbol]
|
|
[#:close-original? close?]
|
|
[#:shutdown-on-close? shutdown?]
|
|
[#:error/ssl error])
|
|
|
|
Returns two values --- an input port and an output port --- that
|
|
implement the SSL protocol over the given input and output port. (The
|
|
given ports should be connected to another process that runs the SSL
|
|
protocol.)
|
|
|
|
The `mode-symbol' argument can be 'connect or 'accept (defaults to
|
|
'accept). The mode determines how the SSL protocol is initialized over
|
|
the ports, either as a client or as a server. As with `ssl-listen', in
|
|
'accept mode supply a `context' that has been initialized with
|
|
`ssl-load-certificate-chain!' and `ssl-load-private-key!' to avoid a
|
|
_no shared cipher_ error.
|
|
|
|
The `context' argument should be a client context for 'connect mode or
|
|
a server context for 'accept mode. If it is not supplied, a context is
|
|
created using the protocol specified by a `protocol-symbol' argument.
|
|
|
|
If the `protocol-symbol' argument is not supplied, it defaults to
|
|
'sslv2-or-v3. See `ssl-make-client-context' for further details
|
|
(including all options and the meanings of the protocol symbols).
|
|
This argument is ignored if a `context' argument is supplied.
|
|
|
|
If `close?' is true, then when both SSL ports are closed, the given
|
|
input and output ports are automatically closed. The default is #f.
|
|
|
|
If `shutdown?' is true, then when the output SSL port is closed, it
|
|
sends a shutdown message to the other end of the SSL connection. The
|
|
default is #f. When shutdown is enabled, closing the output port can
|
|
fail if the given output port becomes unwritable (e.g., because the
|
|
other end of the given port has been closed by another process).
|
|
|
|
The `error' argument is an error procedure to use for raising
|
|
communication errors. The default is `error', which raises `exn:fail';
|
|
in contrast, `ssl-accept' and `ssl-connect' use an error function that
|
|
raises `exn:fail:network'.
|
|
|
|
See also `ssl-connect' about the limitations of reading and writing to
|
|
an SSL connection (i.e., one direction at a time).
|
|
|
|
|
|
-- Context procedures --------------------------------------------
|
|
|
|
> (ssl-load-certificate-chain! context-or-listener pathname)
|
|
|
|
Loads a PEM-format certification chain file for connections to made
|
|
with the given context (created by `ssl-make-client-context' or
|
|
`ssl-make-server-context') or listener (created by `ssl-listener').
|
|
|
|
This chain is used to identify the client or server when it connects
|
|
or accepts connections. Loading a chain overwrites the old chain. Also
|
|
call `ssl-load-private-key!' to load the certificate's corresponding
|
|
key.
|
|
|
|
The file "test.pem" is suitable for testing purposes. Since "test.pem"
|
|
is public, such a test configuration obviously provides no security.
|
|
|
|
|
|
> (ssl-load-private-key! context-or-listener pathname [rsa? asn1?])
|
|
|
|
Loads the first private key from `pathname' for the given context or
|
|
listener. The key goes with the certificate that identifies the client
|
|
or server.
|
|
|
|
If `rsa?' is #t (the default), the first RSA key is read (i.e.,
|
|
non-RSA keys are skipped). If `asn1?' is #t (the default is #f), the
|
|
file is parsed as ASN1 format instead of PEM.
|
|
|
|
The file "test.pem" is suitable for testing purposes. Since "test.pem"
|
|
is public, such a test configuration obviously provides no security.
|
|
|
|
|
|
> (ssl-set-verify! context-or-listener boolean)
|
|
|
|
Enables or disables verification of a connection peer's certificates.
|
|
By default, verification is disabled.
|
|
|
|
Enabling verification also requires, at a minimum, designating trusted
|
|
certificate authorities with `ssl-load-verify-root-certificates!'.
|
|
|
|
|
|
> (ssl-load-verify-root-certificates! context-or-listener pathname)
|
|
|
|
Loads a PEM-format file containing trusted certificates that are used
|
|
to verify the certificates of a connection peer. Call this procedure
|
|
multiple times to load multiple sets of trusted certificates.
|
|
|
|
The file "test.pem" is suitable for testing purposes where the peer
|
|
identifies itself using "test.pem". Since "test.pem" is public, such
|
|
a test configuration obviously provides no security.
|
|
|
|
|
|
> (ssl-load-suggested-certificate-authorities! context-or-listener pathname)
|
|
|
|
Loads a PEM-format file containing certificates that are used by a
|
|
server. The certificate list is sent to a client when the server
|
|
requests a certificate as an indication of which certificates the
|
|
server trusts.
|
|
|
|
Loading the suggested certificates does not imply trust, however; any
|
|
certificate presented by the client will be checked using the trusted
|
|
roots loaded by `ssl-load-verify-root-certificates!'.
|
|
|
|
The file "test.pem" is suitable for testing purposes where the peer
|
|
identifies itself using "test.pem".
|
|
|
|
|
|
==================================================
|
|
|
|
Implementation notes
|
|
--------------------
|
|
|
|
For Windows, "mzssl.ss" relies on "libeay32.dll" and "ssleay32.dll",
|
|
where the DLLs are located in the same place as "libmzsch<VERS>.dll"
|
|
(where <VERS> is either "xxxxxxx" or a mangling of MzScheme's version
|
|
number). The DLLs are distributed as part of PLT Scheme.
|
|
|
|
For Unix variants, "mzssl.ss" relies on "libcryto.so" and "libssl.so",
|
|
which must be installed in a standard library location, or in a
|
|
directory listed by LD_LIBRARY_PATH.
|
|
|
|
For Mac OS X, "mzssl.ss" relies on "libssl.dylib" and
|
|
"libcryto.dylib", which are part of the OS distribution for Mac OS X
|
|
10.2 and later.
|