diff --git a/collects/config/config.scrbl b/collects/config/config.scrbl index 0619a1418b..42f7c9a176 100644 --- a/collects/config/config.scrbl +++ b/collects/config/config.scrbl @@ -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} diff --git a/collects/frtime/frtime.scrbl b/collects/frtime/frtime.scrbl index e30c6d2640..0a34217840 100644 --- a/collects/frtime/frtime.scrbl +++ b/collects/frtime/frtime.scrbl @@ -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 diff --git a/collects/openssl/doc.txt b/collects/openssl/doc.txt deleted file mode 100644 index d8b3e09fbc..0000000000 --- a/collects/openssl/doc.txt +++ /dev/null @@ -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.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. diff --git a/collects/openssl/info.ss b/collects/openssl/info.ss index faf437131f..b491b12dee 100644 --- a/collects/openssl/info.ss +++ b/collects/openssl/info.ss @@ -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."))) diff --git a/collects/openssl/openssl.scrbl b/collects/openssl/openssl.scrbl new file mode 100644 index 0000000000..cc6a5f03a5 --- /dev/null +++ b/collects/openssl/openssl.scrbl @@ -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.