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?] [#: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'. -- 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.dll" (where 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.