replacing old ssl implementation with new one

svn: r2773

collects/openssl/doc.txt

@@ -1,19 +1,19 @@
 The _openssl_ collection provides glue for the OpenSSL library with
-the MzScheme port system. The OpenSSL collection functions nearly
+the MzScheme port system. The OpenSSL collection provides functions
-identically to the standard TCP subsystems in PLT Scheme, with a few
+nearly identically to the standard TCP subsystem in PLT Scheme, plus a
-additional flags.
+generic `ports->ssl-ports' interface.
 
 To use this library, you will need OpenSSL installed on your
 machine, but
 
- * the PLT-distributed archive for Windows installs the necessary
+ * for Windows, the PLT Scheme distribution for Windows includes the
-   DLLs, and
+   necessary DLLs;
 
- * Mac OS X 10.2 provides the necessary OpenSSL libraries
+ * for Mac OS X, version 10.2 and later provides the necessary OpenSSL
-   (as do some other operating systems).
+   libraries.
 
-To build from source, you will need a C compiler and linker;
+ * for Unix, libssl.so is likely to be installed on your machine
-see the end of this documentation for build notes.
+   already.
 
 ==================================================
 
@@ -27,25 +27,34 @@ 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
 
--- Client procedures ----------------------------------------
+Either #f (when `ssl-available?' is #t) or an error string (when
+`ssl-available?' is #f).
 
-> (ssl-connect hostname port-k [ssl-client-context-or-protocol-symbol])
+
+-- 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 tcp-connect; an input port and an output port.
+return values are as for `tcp-connect': an input port and an output
+port.
 
-The optional `ssl-context-or-protocol-symbol' argument determines
+The optional `context-or-protocol-symbol' argument determines which
-which encryption protocol is used, whether the server's certificate is
+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:
+`ssl-make-client-context' (see below), or one of the following
-'sslv2-or-v3 (the default), 'sslv2, 'sslv3, or 'tls; see
+symbols: 'sslv2-or-v3 (the default), 'sslv2, 'sslv3, or 'tls; see
-`make-client-context' for further details (including the meanings of
+`ssl-make-client-context' for further details (including the meanings of
-the protocol symbols.)
+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 [protocol-symbol])
+> (ssl-connect/enable-break hostname port-k [client-context-or-protocol-symbol])
 
 Like `ssl-connect', but breaking is enabled while trying to connect. 
 
@@ -80,13 +89,14 @@ Returns #t if `v' is a value produced by `ssl-make-client-context', #f
 otherwise.
 
 
--- Server procedures ----------------------------------------
+-- TCP_like Server procedures ----------------------------------------
 
-> (ssl-listen port-k [queue-k reuse? hostname-or-#f protocol-symbol])
+> (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 `protocol-symbol' is as for
+waitable object). The extra optional `server-context-protocol-symbol'
-`ssl-connect'.
+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
@@ -105,19 +115,73 @@ Analogous to `tcp-close' and `tcp-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'.
 
 
--- Certificate procedures ----------------------------------------
+> (ssl-make-server-context [protocol-symbol])
 
-> (ssl-load-certificate-chain! ssl-client-context-or-listener pathname)
+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
+with the given context (created by `ssl-make-client-context' or
-listener (created by `ssl-listener').
+`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
@@ -128,11 +192,11 @@ 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! ssl-client-context-or-listener pathname [rsa? asn1?])
+> (ssl-load-private-key! context-or-listener pathname [rsa? asn1?])
 
-Loads the first private key from `pathname' for the given client
+Loads the first private key from `pathname' for the given context or
-context or listener. The key goes with the certificate that identifies
+listener. The key goes with the certificate that identifies the client
-the client or server.
+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
@@ -142,7 +206,7 @@ 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! ssl-client-context-or-listener boolean)
+> (ssl-set-verify! context-or-listener boolean)
 
 Enables or disables verification of a connection peer's certificates.
 By default, verification is disabled.
@@ -151,7 +215,7 @@ Enabling verification also requires, at a minimum, designating trusted
 certificate authorities with `ssl-load-verify-root-certificates!'.
 
 
-> (ssl-load-verify-root-certificates! ssl-client-context-or-listener pathname)
+> (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
@@ -162,7 +226,7 @@ identifies itself using "test.pem".  Since "test.pem" is public, such
 a test configuration obviously provides no security.
 
 
-> (ssl-load-suggested-certificate-authorities! ssl-listener pathname)
+> (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
@@ -179,59 +243,18 @@ identifies itself using "test.pem".
 
 ==================================================
 
-Build notes
+Implementation notes
------------
+--------------------
 
-The "mzssl.ss" library is actually implemented in C as "mzssl.c".
+For Windows, "mzssl.ss" relies on "libeay32xxxxxxxx.dll" and
-When you run Setup PLT, setup attempts to compile and link "mzssl.c"
+"ssleay32xxxxxxxx.dll", where the "xxxxxxxx" may be replaced with a
-to create a PLT Scheme extension.
+PLT Scheme verison number, and where the DLLs are located in the same
+place as "libmzschxxxxxxx.dll". The DLLs are distributed as part of
+PLT Scheme.
 
-Per-platform notes:
+For Unix variants, "mzssl.ss" relies on "libssl.so", which must be
+installed in a standard library location, or in a directory listed by
+LD_LIBRARY_PATH.
 
- * Windows
+For Mac OS X, "mzssl.ss" relies on "libssl.dylib", which is part of
-
+the OS distribution for Mac OS X 10.2 and later.
-   The setup script needs "libeay32.lib" and "ssleay32.lib", which it
-   can find automatically if they are installed as
-   plt/collects/openssl/openssl/lib/{lib,ssl}easy32.lib. Similarly, the
-   setup script needs several OpenSSL header files (such as "ssl.h"),
-   which it can find automatically if they are installed as
-   plt/collects/openssl/openssl/include/openssl/ssl.h, etc.
-
-   At run-time, the DLLs "libeay32.dll" and "ssleay32.dll" must be
-   found by Windows as it tries to load the "mzssl.dll" extension. For
-   example, if the two DLLs are installed in the system folder, they
-   will be found. (Another possibility is the folder containing the
-   ".exe" that uses the "mzssl.dll" extension.)
-
-   To designate a directory other than plt/collects/openssl/openssl
-   for .lib and .h files, define the environment variable
-   PLT_EXTENSION_LIB_PATHS. The variable's value should be a
-   semicolon-separated path list, where one of the paths contains
-   "include" and "lib" subdirectories with the OpenSSL headers and
-   libraries.
-
-   If OpenSLL is built with cygwin, ".a" files are generated instead
-   of ".lib" an ".dll" files. Presumably "mzssl.c" could be made to
-   build with those libraries by modifying "pre-installer.ss", but we
-   haven't tried. Similar caveats apply to other build techniques that
-   do not produce DLLs.
-
-   Bonus hack: If "{lib,ssl}easy32xxxxxxx.lib" exist in the lib
-   directory, they are used (instead of "{lib,ssl}eay32.lib") with
-   the expectation that the resulting extension will link to
-   "{lib,ssl}eay32xxxxxxx.dll". This enables the name-mangling version
-   hack for distributing DLLs.
-
- * Mac OS
-
-   "Just works" for Mac OS X version >= 10.2 if you have the developer
-   tools installed. Building for 10.1 requires installing OpenSSL. Mac
-   OS Classic is not supported at all.
-
- * Unix (including Linux)
-
-   Usually "just works" if you have OpenSSL installed.  If the header
-   files or libraries are in a non-standard place, define the
-   environment variable PLT_EXTENSION_LIB_PATHS as a colon-separated
-   path list, where one of the paths contains "include" and "lib"
-   subdirectories with the OpenSSL headers and libraries.

collects/openssl/info.ss

@@ -1,7 +1,6 @@
 (module info (lib "infotab.ss" "setup")
   (define name "SSL Driver")
   (define doc.txt "doc.txt")
-  (define compile-omit-files '("mzssl.ss"))
   (define pre-install-collection "pre-installer.ss")
   (define blurb '("The SSL collection provides a driver for using the OpenSSL "
 		  "secure connection library.")))

collects/openssl/mzssl.ss

@@ -1,26 +0,0 @@
-(module mzssl mzscheme
-  (define ssl-available? #f)
-  (provide ssl-available?)
-
-  (define-syntax provide-wrappers
-    (syntax-rules ()
-      [(_) (begin)]
-      [(_ id1 id ...)
-       (begin
-	 (define (id1 . args)
-	   (error 'id1 "extension not compiled"))
-	 (provide id1)
-	 (provide-wrappers id ...))]))
-
-  (provide-wrappers
-   ssl-connect ssl-connect/enable-break
-   ssl-listen ssl-listener? ssl-close
-   ssl-accept ssl-accept/enable-break
-   ssl-addresses
-   ssl-make-client-context ssl-client-context?
-   ssl-load-certificate-chain!
-   ssl-set-verify!
-   ssl-load-verify-root-certificates!
-   ssl-load-private-key!
-   ssl-load-suggested-certificate-authorities!))
-