openssl scribblings
svn: r8392
This commit is contained in:
Matthew Flatt
parent
b3007d9088
commit
9be7170b3a
|
|
@ -4,7 +4,7 @@
|
|||
scheme/contract
|
||||
config/config))
|
||||
|
||||
@title{Installation and Search Path Configuration}
|
||||
@title{@bold{Config}: Installation and Search Paths}
|
||||
|
||||
@section{Configuring Directories and Search Paths}
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
(only-in "demos/gui/fred.ss" ft-frame% ft-message% ft-button% ft-check-box% ft-slider%
|
||||
ft-text-field% ft-radio-box% ft-choice% ft-list-box%)))
|
||||
|
||||
@title[#:tag "frtime"]{FrTime: A Language for Reactive Programs}
|
||||
@title[#:tag "frtime"]{@bold{FrTime}: A Language for Reactive Programs}
|
||||
|
||||
The @scheme[frtime.ss] language supports declarative construction of
|
||||
reactive systems in a syntax very similar to that of MzScheme. To
|
||||
|
|
|
|||
|
|
@ -1,283 +0,0 @@
|
|||
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.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
(module info setup/infotab
|
||||
(define name "SSL Driver")
|
||||
(define doc.txt "doc.txt")
|
||||
(define scribblings '(("openssl.scrbl")))
|
||||
(define blurb '("The SSL collection provides a driver for using the OpenSSL "
|
||||
"secure connection library.")))
|
||||
|
|
|
|||
354
collects/openssl/openssl.scrbl
Normal file
354
collects/openssl/openssl.scrbl
Normal file
|
|
@ -0,0 +1,354 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
scribble/bnf
|
||||
(for-label openssl
|
||||
scheme))
|
||||
|
||||
@title{@bold{OpenSSL}}
|
||||
|
||||
@defmodule[openssl]
|
||||
|
||||
The @schememodname[openssl] library provides glue for the OpenSSL
|
||||
library with the Scheme port system. It provides functions nearly
|
||||
identically to the standard TCP subsystem in PLT Scheme, plus a
|
||||
generic @scheme[ports->ssl-ports] interface.
|
||||
|
||||
To use this library, you will need OpenSSL installed on your machine,
|
||||
but
|
||||
|
||||
@itemize{
|
||||
@item{for Windows, the PLT Scheme distribution for Windows includes
|
||||
the necessary DLLs.}
|
||||
|
||||
@item{for Mac OS X, version 10.2 and later provides the necessary
|
||||
OpenSSL libraries.}
|
||||
|
||||
@item{for Unix, @filepath{libssl.so} and @filepath{libcrypto.so} are
|
||||
likely to be installed on your machine, already.}
|
||||
|
||||
}
|
||||
|
||||
|
||||
@defthing[ssl-available? boolean?]{
|
||||
|
||||
A boolean value which says whether the system openssl library was
|
||||
successfully loaded. Calling @scheme[ssl-connect], @|etc| when this
|
||||
value is @scheme[#f] (library not loaded) will raise an exception.}
|
||||
|
||||
|
||||
@defthing[ssl-load-fail-reason (or/c false/c string?)]{
|
||||
|
||||
Either @scheme[#f] (when @scheme[ssl-available?] is @scheme[#t]) or an
|
||||
error string (when @scheme[ssl-available?] is @scheme[#f]).}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{TCP-like Client Procedures}
|
||||
|
||||
@defproc[(ssl-connect (hostname string?)
|
||||
(port-no (integer-in 1 65535))
|
||||
(client-protocol
|
||||
(or/c ssl-client-context? symbol?) 'sslv2-or-v3))
|
||||
(values input-port? output-port?)]{
|
||||
|
||||
Connect to the host given by @scheme[hostname], on the port given by
|
||||
@scheme[port-no]. This connection will be encrypted using SSL. The
|
||||
return values are as for @scheme[tcp-connect]: an input port and an
|
||||
output port.
|
||||
|
||||
The optional @scheme[client-protocol] 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
|
||||
@scheme[ssl-make-client-context], or one of the following symbols:
|
||||
@scheme['sslv2-or-v3] (the default), @scheme['sslv2], @scheme['sslv3],
|
||||
or @scheme['tls]; see @scheme[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 @scheme[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
|
||||
@scheme[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.}
|
||||
|
||||
|
||||
@defproc[(ssl-connect/enable-break
|
||||
(hostname string?)
|
||||
(port-no (integer-in 1 65535))
|
||||
(client-protocol
|
||||
(or/c ssl-client-context? symbol?) 'sslv2-or-v3))
|
||||
(values input-port? output-port?)])]{
|
||||
|
||||
Like @scheme[ssl-connect], but breaking is enabled while trying to
|
||||
connect.}
|
||||
|
||||
|
||||
@defproc[(ssl-make-client-context (protocol symbol? 'sslv2-or-v3))
|
||||
ssl-client-context?]{
|
||||
|
||||
Creates a context to be supplied to @scheme[ssl-connect]. The context
|
||||
identifies a communication protocol (as selected by
|
||||
@scheme[protocol]), and also holds certificate information (i.e., the
|
||||
client's identity, its trusted certificate authorities, etc.). See the
|
||||
section @secref["cert-procs"] below for more information on
|
||||
certificates.
|
||||
|
||||
The @scheme[protocol] must be one of the following:
|
||||
@itemize{
|
||||
@item{@scheme['sslv2-or-v3] : SSL protocol versions 2 or 3, as
|
||||
appropriate (this is the default)}
|
||||
@item{@scheme['sslv2] : SSL protocol version 2}
|
||||
@item{@scheme['sslv3] : SSL protocol version 3}
|
||||
@item{@scheme['tls] : the TLS protocol version 1}
|
||||
}
|
||||
|
||||
By default, the context returned by @scheme[ssl-make-client-context] does not
|
||||
request verification of a server's certificate. Use @scheme[ssl-set-verify!]
|
||||
to enable such verification.}
|
||||
|
||||
|
||||
@defproc[(ssl-client-context? (v any/c)) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if @scheme[v] is a value produced by
|
||||
@scheme[ssl-make-client-context], @scheme[#f] otherwise.}
|
||||
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{TCP-like Server Procedures}
|
||||
|
||||
@defproc[(ssl-listen
|
||||
(port-no (integer-in 1 65535))
|
||||
[queue-k nonnegative-exact-integer?]
|
||||
[reuse? any/c #f]
|
||||
[hostname-or-#f (or/c string? false/c) #f]
|
||||
[server-protocol
|
||||
(or/c ssl-server-context? symbol?) 'sslv2-or-v3])
|
||||
ssl-listener?]{
|
||||
|
||||
Like @scheme[tcp-listen], but the result is an SSL listener (which is
|
||||
a synchronizable value; see @scheme[sync]). The extra optional
|
||||
@scheme[server-protocol] is as for @scheme[ssl-connect], except that a
|
||||
context must be a server context instead of a client context.
|
||||
|
||||
Call @scheme[ssl-load-certificate-chain!] and
|
||||
@scheme[ssl-load-private-key!] to avoid a @emph{no shared cipher}
|
||||
error on accepting connections. The file @filepath{test.pem} in the
|
||||
@filepath{openssl} collection is a suitable argument for both calls
|
||||
when testing. Since @filepath{test.pem} is public, however, such a
|
||||
test configuration obviously provides no security.}
|
||||
|
||||
@deftogether[(
|
||||
@defproc[(ssl-close (listener ssl-listener?)) void?]
|
||||
@defproc[(ssl-listener? (v any/c)) boolean?])]{
|
||||
|
||||
Analogous to @scheme[tcp-close] and @scheme[tcp-listener?].}
|
||||
|
||||
@deftogether[(
|
||||
@defproc[(ssl-accept (listener ssl-listener?))
|
||||
(values input-port? output-port?)]
|
||||
@defproc[(ssl-accept/enable-break (listener ssl-listener?))
|
||||
(values input-port? output-port?)])]{
|
||||
|
||||
Analogous to @scheme[tcp-accept].
|
||||
|
||||
Closing the resulting output port does not send a shutdown message to
|
||||
the client. See also @scheme[ports->ssl-ports].
|
||||
|
||||
See also @scheme[ssl-connect] about the limitations of reading and
|
||||
writing to an SSL connection (i.e., one direction at a time).
|
||||
|
||||
The @scheme[ssl-accept/enable-break] procedure is analogous to
|
||||
@scheme[tcp-accept/enable-break].}
|
||||
|
||||
|
||||
@defproc[(ssl-make-server-context (protocol symbol?))
|
||||
ssl-server-context?]{
|
||||
|
||||
Like @scheme[ssl-make-client-context], but creates a server context.}
|
||||
|
||||
@defproc[(ssl-server-context? (v any/c)) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if @scheme[v] is a value produced by
|
||||
@scheme[ssl-make-server-context], @scheme[#f] otherwise.}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{SSL-wrapper Interface}
|
||||
|
||||
@defproc[(ports->ssl-ports
|
||||
(input-port input-port?)
|
||||
(output-port output-port?)
|
||||
[#:mode mode symbol? 'accept]
|
||||
[#:context context (or/c ssl-client-context? ssl-server-context?)
|
||||
((if (eq? mode 'accept)
|
||||
ssl-make-server-context
|
||||
ssl-make-client-context)
|
||||
protocol)]
|
||||
[#:encrypt protocol symbol? 'sslv2-or-v3]
|
||||
[#:close-original? close-original? boolean? #f]
|
||||
[#:shutdown-on-close? shutdown-on-close? boolean? #f]
|
||||
[#:error/ssl error procedure? error])
|
||||
(values input-port? output-port?)]{
|
||||
|
||||
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 @scheme[mode] argument can be @scheme['connect] or
|
||||
@scheme['accept]. The mode determines how the SSL protocol is
|
||||
initialized over the ports, either as a client or as a server. As with
|
||||
@scheme[ssl-listen], in @scheme['accept] mode, supply a
|
||||
@scheme[context] that has been initialized with
|
||||
@scheme[ssl-load-certificate-chain!] and
|
||||
@scheme[ssl-load-private-key!] to avoid a @emph{no shared cipher}
|
||||
error.
|
||||
|
||||
The @scheme[context] argument should be a client context for
|
||||
@scheme['connect] mode or a server context for @scheme['accept]
|
||||
mode. If it is not supplied, a context is created using the protocol
|
||||
specified by a @scheme[protocol] argument.
|
||||
|
||||
If the @scheme[protocol] argument is not supplied, it defaults to
|
||||
@scheme['sslv2-or-v3]. See @scheme[ssl-make-client-context] for
|
||||
further details (including all options and the meanings of the
|
||||
protocol symbols). This argument is ignored if a @scheme[context]
|
||||
argument is supplied.
|
||||
|
||||
If @scheme[close-original?] is true, then when both SSL ports are
|
||||
closed, the given input and output ports are automatically closed. The
|
||||
default is #f.
|
||||
|
||||
If @scheme[shutdown-on-close?] 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 @scheme[error] argument is an error procedure to use for raising
|
||||
communication errors. The default is @scheme[error], which raises
|
||||
@scheme[exn:fail]; in contrast, @scheme[ssl-accept] and
|
||||
@scheme[ssl-connect] use an error function that raises
|
||||
@scheme[exn:fail:network].
|
||||
|
||||
See also @scheme[ssl-connect] about the limitations of reading and
|
||||
writing to an SSL connection (i.e., one direction at a time).}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section[#:tag "cert-procs"]{Context Procedures}
|
||||
|
||||
@defproc[(ssl-load-certificate-chain!
|
||||
(context-or-listener (or/c ssl-client-context? ssl-server-context?
|
||||
ssl-listener?))
|
||||
(pathname path-string?))
|
||||
void?]{
|
||||
|
||||
Loads a PEM-format certification chain file for connections to made
|
||||
with the given context (created by @scheme[ssl-make-client-context] or
|
||||
@scheme[ssl-make-server-context]) or listener (created by
|
||||
@scheme[ssl-listen]).
|
||||
|
||||
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 @scheme[ssl-load-private-key!] to load the certificate's
|
||||
corresponding key.
|
||||
|
||||
You can use the file @filepath{test.pem} of the @filepath{openssl}
|
||||
collection for testing purposes. Since @filepath{test.pem} is public,
|
||||
such a test configuration obviously provides no security.}
|
||||
|
||||
@defproc[(ssl-load-private-key!
|
||||
(context-or-listener (or/c ssl-client-context? ssl-server-context?
|
||||
ssl-listener?))
|
||||
(pathname path-string?)
|
||||
[rsa? boolean? #t]
|
||||
[asn1? boolean? #f])
|
||||
void?]{
|
||||
|
||||
Loads the first private key from @scheme[pathname] for the given
|
||||
context or listener. The key goes with the certificate that identifies
|
||||
the client or server.
|
||||
|
||||
If @scheme[rsa?] is @scheme[#t] (the default), the first RSA key is
|
||||
read (i.e., non-RSA keys are skipped). If @scheme[asn1?] is
|
||||
@scheme[#t] (the default is @scheme[#f]), the file is parsed as ASN1
|
||||
format instead of PEM.
|
||||
|
||||
You can use the file @filepath{test.pem} of the @filepath{openssl}
|
||||
collection for testing purposes. Since @filepath{test.pem} is public,
|
||||
such a test configuration obviously provides no security.}
|
||||
|
||||
@defproc[(ssl-set-verify!
|
||||
(context-or-listener (or/c ssl-client-context? ssl-server-context?
|
||||
ssl-listener?))
|
||||
(verify? boolean?))
|
||||
void?]{
|
||||
|
||||
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
|
||||
@scheme[ssl-load-verify-root-certificates!].}
|
||||
|
||||
@defproc[(ssl-load-verify-root-certificates!
|
||||
(context-or-listener (or/c ssl-client-context? ssl-server-context?
|
||||
ssl-listener?))
|
||||
(pathname path-string?))
|
||||
void?]{
|
||||
|
||||
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.
|
||||
|
||||
You can use the file @filepath{test.pem} of the @filepath{openssl}
|
||||
collection for testing purposes. Since @filepath{test.pem} is public,
|
||||
such a test configuration obviously provides no security.}
|
||||
|
||||
@defproc[(ssl-load-suggested-certificate-authorities!
|
||||
(context-or-listener (or/c ssl-client-context? ssl-server-context?
|
||||
ssl-listener?))
|
||||
(pathname path-string?))
|
||||
void?]{
|
||||
|
||||
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 @scheme[ssl-load-verify-root-certificates!].
|
||||
|
||||
You can use the file @filepath{test.pem} of the @filepath{openssl}
|
||||
collection for testing purposes where the peer identifies itself using
|
||||
@filepath{test.pem}.}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Implementation Notes}
|
||||
|
||||
For Windows, @schememodname[openssl] relies on @filepath{libeay32.dll}
|
||||
and @filepath{ssleay32.dll}, where the DLLs are located in the same
|
||||
place as @filepath{libmzsch@nonterm{vers}.dll} (where @nonterm{vers}
|
||||
is either @tt{xxxxxxx} or a mangling of PLT Scheme's version
|
||||
number). The DLLs are distributed as part of PLT Scheme.
|
||||
|
||||
For Unix variants, @schememodname[openssl] relies on
|
||||
@filepath{libcryto.so} and @filepath{libssl.so}, which must be
|
||||
installed in a standard library location, or in a directory listed by
|
||||
@envvar{LD_LIBRARY_PATH}.
|
||||
|
||||
For Mac OS X, @schememodname[openssl] relies on
|
||||
@filepath{libssl.dylib} and @filepath{libcryto.dylib}, which are part
|
||||
of the OS distribution for Mac OS X 10.2 and later.
|
||||
Loading…
Reference in New Issue
Block a user