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'.


> (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'.


> (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?])

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 SLL
protocol.)

The `mod-symbol' argument can be 'connect or 'accept, and it 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 more 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).


-- 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.
