(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "openssl")
     (description (p "Bindings to the OpenSSL SSL/TLS library"))
     (author (url "http://www.chust.org/" "Thomas Chust"))
     (history
      (version "1.4" "Fix intermittent bug in ssl-write caused by the GC's "
               "moving around of memory locations")
      (version "1.3" "Make ssl ports completely distinct from tcp ports. Add "
               (tt "ssl-port?") " and " (tt "ssl-port->tcp-port") "procedures.")
      (version "1.1.7" "fix for vector deref crash (elf, reported by glogic)")
      (version "1.1.6" "windows linking fixes by Alex Queiroz")
      (version "1.1.5" "added static linking support [felix]")
      (version "1.1.4" "fixed problems with the shutdown sequence")
      (version "1.1.3" "fixes problem with older chickens and missing newline before `<#' in blocks of foreign code [Thanks to Dan Muresan]")
      (version "1.1.2" "uses `foreign-code' macro insead of obsolete read syntax")
      (version "1.1.1" "Output that would block properly suspends threads now")
      (version "1.1.0" (tt "##sys#tcp-port->fileno") " and " (tt "tcp-addresses") " are now supported on SSL ports")
      (version "1.0.0" "Corrections, tests against " (tt "openssl s_server, openssl s_client") " and comparison with the PLT module")
      (version "0.4.0" "Server functionality added")
      (version "0.3.1" "Client-only with certificate functions")
      (version "0.2.0" "Client-only prerelease"))
     
     (usage)
     (download "openssl.egg")

     (documentation
      (p "This reference is basically a copy of the documentation of " (url "http://www.plt-scheme.org/" "PLT Scheme's") " openssl module. The API provided here is largely compatible with that one. The exceptions are the missing " (tt ".../enable-break") " and " (tt "ssl-available?") " procedures and the missing " (tt "reuse?") " argument to " (tt "ssl-listen") ".")
      (p "Please note that all the procedures described here may fail and raise a non-continuable exception of the composite type " (tt "(exn i/o net openssl)") ". The " (tt "openssl") " property condition contains a property called " (tt "status") " which will be bound to a symbol corresponding to the OpenSSL error code that was encountered. It may have the following values:")
	 (table
	  (tr (th "Symbol") (th "Meaning"))
	  (tr (td (tt "'zero-return")) (td "The SSL/TLS connection was shut down unexpectedly but in a controlled way"))
	  (tr (td (tt "'want-read")) (td "The operation didn't finish because data must be read from a nonblocking socket. This error condition only occurs though, when it could not be handled automatically because there is actually no socket involved or some other strange thing happended in the OpenSSL library."))
	  (tr (td (tt "'want-write")) (td "The operation didn't finish because data must be read from a nonblocking socket. The same comment as for " (tt "'want-read") " applies."))
	  (tr (td (tt "'want-connect")) (td "The operation didn't finish because a nonblocking socket must first be connected. The same comment as for " (tt "'want-read") " applies."))
	  (tr (td (tt "'want-accept")) (td "The operation didn't finish because a nonblocking socket must first be acepted. The same comment as for " (tt "'want-read") " applies."))
	  (tr (td (tt "'want-X509-lookup")) (td "The operation failed because an application callback that could not even have been registered through this API was apparently registered anyway and has asked to be called again."))
	  (tr (td (tt "'syscall")) (td "Some low-level I/O error occurred."))
	  (tr (td (tt "'ssl")) (td "Something went wrong in the OpenSSL library itself."))
	  (tr (td (tt "#f")) (td "The error is not classified")))
      (p "Of course the exception that is thrown also has an appropriate message set.")
      (p "If you feel that this documentation lacks some information, please also consider the " (url "http://www.openssl.org/docs/ssl/ssl.html" "manual pages of OpenSSL") ".")

      (subsection
       "Client procedures"
       (group
	(procedure
	 "(ssl-connect (hostname <string>) #!optional (port <exact>) ((ctx <ssl-client-context|symbol>) 'sslv2-or-v3)) => <input-port>, <output-port>"
	 (p "Connect to the given " (tt "host") " on the given " (tt "port") " (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.")
	 (p "The optional " (tt "ctx") " 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 " (tt "ssl-make-client-context") " (see below), or one of the following symbols: " (tt "'sslv2-or-v3") " (the default), " (tt "'sslv2") ", " (tt "'sslv3") ", or " (tt "'tls") ". See " (tt "ssl-make-client-context") " for further details, including the meanings of the protocol symbols."))
	(procedure
	 "(ssl-make-client-context #!optional ((protocol <symbol>) 'sslv2-or-v3)) => <ssl-client-context>"
	 (p "Creates a context to be supplied to " (tt "ssl-connect") ". The context identifies a communication protocol (as selected by " (tt "protocol") "), 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.")
	 (p "The " (tt "protocol") " must be one of the following:")
	    (table
	     (tr (th "Symbol") (th "Meaning"))
	     (tr (td (tt "'sslv2-or-v3")) (td "SSL protocol versions 2 or 3, as appropriate"))
	     (tr (td (tt "'sslv2")) (td "SSL protocol version 2"))
	     (tr (td (tt "'sslv3")) (td "SSL protocol version 3"))
	     (tr (td (tt "'tls")) (td "the TLS protocol version 1")))
	 (p "By default, the context returned by " (tt "ssl-make-client-context") " does not request verification of a server's certificate. Use " (tt "ssl-set-verify!") " to enable such verification."))
	(procedure
	 "(ssl-client-context? (obj <top>)) => <bool>"
	 (p "Returns " (tt "#t") " if " (tt "obj") " is a value produced by " (tt "ssl-make-client-context") ", " (tt "#f") " otherwise."))))

      (subsection
       "Server procedures"
       (group
	(procedure
	 "(ssl-listen (port <exact>) #!optional ((backlog <exact>) 4) ((hostname <string>) #f) ((ctx <ssl-client-context|symbol>) 'sslv2-or-v3)) => <ssl-listener>"
	 (p "Like " (tt "tcp-listen") ", but the result is an SSL listener. The extra optional " (tt "ctx") " argument is as for " (tt "ssl-connect") ".")
	 (p "Call " (tt "ssl-load-certificate-chain!") " and " (tt "ssl-load-private-key!") " to avoid a " (tt "\"no shared cipher\"") " error on accepting connections."))
	(definition
	  (signatures
	   (signature "procedure" "(ssl-close (listener <ssl-listener>)) => <void>")
	   (signature "procedure" "(ssl-listener? (obj <top>)) => <bool>")
	   (signature "procedure" "(ssl-listener-port (listener <ssl-listener>)) => <exact>")
	   (signature "procedure" "(ssl-listener-fileno (listener <ssl-listener>)) => <exact>")
	   (signature "procedure" "(ssl-listener-accept-ready? (listener <ssl-listener>)) => <bool>")
	   (signature "procedure" "(ssl-accept (listener <ssl-listener>)) => <input-port>, <output-port>"))
	  (p "Analogous to " (tt "tcp-close") ", " (tt "tcp-listener?") ", " (tt "tcp-listener-port") ", " (tt "tcp-listener-fileno") ", " (tt "tcp-accept-ready?") " and " (tt "tcp-accept") "."))))

      (subsection
       "Certificate procedures"
       (group
	(procedure
	 "(ssl-load-certificate-chain! (obj <ssl-client-context|ssl-listener>) (pathname <string>)) => <void>"
	 (p "Loads a PEM-format certification chain file for connections to be made with the given context (created by " (tt "ssl-make-context") ") or listener (created by " (tt "ssl-listener") ").")
	 (p "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 " (tt "ssl-load-private-key!") " to load the certificate's corresponding key."))
	(procedure
	 "(ssl-load-private-key! (obj <ssl-client-context|ssl-listener>) (pathname <string>) #!optional ((rsa? <bool>) #t) ((asn1? <bool>) #f)) => <void>"
	 (p "Loads the first private key from " (tt "pathname") " for the given client context or listener. The key goes with the certificate that identifies the client or server.")
	 (p "If " (tt "rsa?") " is " (tt "#t") ", the first RSA key is read (i.e., non-RSA keys are skipped). If " (tt "asn1?") " is " (tt "#t") ", the file is parsed as ASN1 format instead of PEM."))
	(procedure
	 "(ssl-set-verify! (obj <ssl-client-context|ssl-listener>) (v <bool>)) => <void>"
	 (p "Enables or disables verification of a connection peer's certificates. By default, verification is disabled.")
	 (p "Enabling verification also requires, at a minimum, designating trusted certificate authorities with " (tt "ssl-load-verify-root-certificates!") "."))
	(procedure
	 "(ssl-load-verify-root-certificates! (obj <ssl-client-context|ssl-listener>) (pathname <string>) #!optional ((dirname <string>) #f)) => <void>"
	 (p "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.")
	 (p "The optional second argument specifies a directory in which certificates are automatically looked up. You may also only pass a path in this argument and pass " (tt "#f") " as the first argument to this procedure. See the OpenSSL documentation on " (url "http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html" (tt "SSL_CTX_load_verify_locations")) " for more details."))
	(procedure
	 "(ssl-load-suggested-certificate-authorities! (obj <ssl-client-context|ssl-listener>) (pathname <string>)) => <void>"
	 (p "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.")
	 (p "Loading the suggested certificates does not imply trust, however; any certificate presented by the client will be checked using the trusted roots loaded by " (tt "ssl-load-verify-root-certificates!") ".") )))

      (subsection "Port procedures"
        (procedure "(ssl-port? obj)"
          (p "Predicate for SSL ports; returns " (tt "#t") " if " (tt "obj")
             " is an SSL port, " (tt "#f") " if it isn't."))
        (procedure "(ssl-port->tcp-port p)"
          (p "Convert SSL port " (tt "p") " to the raw underlying TCP port. "
             "This is mostly useful if you need to obtain extra information "
             "about the connection, like for example " (tt "tcp-addresses")))))

      (license
       "Copyright (c) 2005, Thomas Chust <chust@web.de>.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer. Redistributions in
  binary form must reproduce the above copyright notice, this list of
  conditions and the following disclaimer in the documentation and/or
  other materials provided with the distribution. Neither the name of the
  author nor the names of its contributors may be used to endorse or
  promote products derived from this software without specific prior
  written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS
IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."))))

(eggdoc->html doc (eggdoc:make-stylesheet doc))