basis/io/sockets/secure/secure-docs.factor

   1 USING: io help.markup help.syntax calendar quotations io.sockets ;
   2 IN: io.sockets.secure
   3
   4 HELP: secure-socket-timeout
   5 { $var-description "Timeout for operations not associated with a constructed port instance, such as SSL handshake and shutdown. Represented as a " { $link duration } "." } ;
   6
   7 HELP: SSLv2
   8 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
   9 $nl
  10 "Note that the SSLv2 protocol is vulnerable to truncation attacks and its use is discouraged (" { $url "http://www.gnu.org/software/gnutls/manual/html_node/On-SSL-2-and-older-protocols.html" } ")." } ;
  11
  12 HELP: SSLv3
  13 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
  14 $nl
  15 "SSLv3 is widely used, however it is being supersceded by TLSv1." } ;
  16
  17 HELP: SSLv23
  18 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
  19 $nl
  20 "This value indicates that either SSLv2 or SSLv3 is acceptable." } ;
  21
  22 HELP: TLSv1
  23 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
  24 $nl
  25 "TLSv1 is the newest protocol for secure socket communications." } ;
  26
  27 ARTICLE: "ssl-methods" "SSL/TLS methods"
  28 "The " { $snippet "method" } " slot of a " { $link secure-config } " can be set to one of the following values:"
  29 { $subsections
  30     SSLv2
  31     SSLv23
  32     SSLv3
  33     TLSv1
  34 }
  35 "The default value is " { $link SSLv23 } "." ;
  36
  37 HELP: secure-config
  38 { $class-description "Instances represent secure socket configurations." } ;
  39
  40 HELP: <secure-config>
  41 { $values { "config" secure-config } }
  42 { $description "Creates a new secure socket configration with default values." } ;
  43
  44 ARTICLE: "ssl-key-file" "The key file and password"
  45 "The " { $snippet "key-file" } " and " { $snippet "password" } " slots of a " { $link secure-config } " can be set to a private key file in PEM format. These slots are required for secure servers, and also for clients when client-side authentication is used." ;
  46
  47 ARTICLE: "ssl-ca-file" "The CA file and path"
  48 "The " { $snippet "ca-file" } " slot of a " { $link secure-config } " can contain the path of a file with a list of trusted certificates in PEM format. The " { $snippet "ca-path" } " slot can contain the path of a directory of trusted certifications."
  49 $nl
  50 "One of these slots are required to be specified so that secure client sockets can verify server certificates."
  51 $nl
  52 "See " { $url "http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html" } " for details." ;
  53
  54 ARTICLE: "ssl-dh-file" "Diffie-Hellman parameter file"
  55 "The " { $snippet "dh-file" } " slot of a " { $link secure-config } " can contain the path of a file with Diffie-Hellman key exchange parameters."
  56 $nl
  57 "This slot is required for secure server sockets." ;
  58
  59 ARTICLE: "ssl-ephemeral-rsa" "Ephemeral RSA key bits"
  60 "The " { $snippet "ephemeral-key-bits" } " slot of a " { $link secure-config } " contains the length of the ephemeral RSA key, in bits."
  61 $nl
  62 "The default value is 1024, and anything less than that is considered insecure. This slot is required for secure server sockets." ;
  63
  64 ARTICLE: "ssl-config" "Secure socket configuration"
  65 "Secure sockets require some configuration, particularly for server sockets. A class represents secure socket configuration parameters:"
  66 { $subsections secure-config }
  67 "Creating new instances:"
  68 { $subsections <secure-config> }
  69 "Configuration parameters:"
  70 { $subsections
  71     "ssl-methods"
  72     "ssl-key-file"
  73     "ssl-ca-file"
  74     "ssl-dh-file"
  75     "ssl-ephemeral-rsa"
  76 } ;
  77
  78 HELP: <secure-context>
  79 { $values { "config" secure-config } { "context" secure-context } }
  80 { $description "Creates a new " { $link secure-context } ". This word should not usually be called directly, use " { $link with-secure-context } " instead." } ;
  81
  82 HELP: with-secure-context
  83 { $values { "config" secure-config } { "quot" quotation } }
  84 { $description "Calls the quotation in a new dynamic scope where a " { $link secure-context } " constructed from the specified configuration is available." } ;
  85
  86 ARTICLE: "ssl-contexts" "Secure socket contexts"
  87 "All secure socket operations must be performed in a secure socket context. A context is created from a secure socket configuration. An implicit context with the default configuration is always available, however server sockets require a certificate to be set together with other parameters, and the default configuration is insufficient, so a context must be explicitly created in that case."
  88 { $subsections with-secure-context } ;
  89
  90 HELP: secure
  91 { $class-description "The class of secure socket addresses." } ;
  92
  93 HELP: <secure>
  94 { $values { "addrspec" "an address specifier" } { "secure" secure } }
  95 { $description "Creates a new secure socket address, which can then be passed to " { $link <client> } " or " { $link <server> } "." } ;
  96
  97 ARTICLE: "ssl-addresses" "Secure socket addresses"
  98 "Secure socket connections are established by passing a secure socket address to " { $link <client> } " or " { $link <server> } "."
  99 $nl
 100 "Secure socket addresses form a class:"
 101 { $subsections secure }
 102 "Constructing secure socket addresses:"
 103 { $subsections <secure> }
 104 "Instances of this class can wrap an " { $link inet } ", " { $link inet4 } " or an " { $link inet6 } ", although note that certificate validation is only performed for instances of " { $link inet } " since otherwise the host name is not available." ;
 105
 106 HELP: send-secure-handshake
 107 { $contract "Upgrades the socket connection of the current " { $link with-client } " scope to a secure connection and initiates a SSL/TLS handshake." }
 108 { $errors "Throws " { $link upgrade-on-non-socket } " or " { $link upgrade-buffers-full } " if used improperly." }
 109 { $examples "This word is used by the " { $vocab-link "smtp" } " library to implement SMTP-TLS." } ;
 110
 111 HELP: accept-secure-handshake
 112 { $contract "Upgrades the socket connection stored in the " { $link input-stream } " and " { $link output-stream } " variables to a secure connection and waits for an SSL/TLS handshake." }
 113 { $errors "Throws " { $link upgrade-on-non-socket } " or " { $link upgrade-buffers-full } " if used improperly." } ;
 114
 115 ARTICLE: "ssl-upgrade" "Upgrading existing connections"
 116 "Some protocols, such as HTTPS, require that the connection be established as an SSL/TLS connection. Others, such as secure SMTP and POP3 require that the client and server initiate an SSL/TLS handshake upon the client sending a plain-text request. The latter use-case is accommodated by a pair of words."
 117 $nl
 118 "Upgrading a connection to a secure socket by initiating an SSL/TLS handshake with the server:"
 119 { $subsections send-secure-handshake }
 120 "Upgrading a connection to a secure socket by waiting for an SSL/TLS handshake from the client:"
 121 { $subsections accept-secure-handshake } ;
 122
 123 HELP: premature-close
 124 { $error-description "Thrown if an SSL connection is closed without the proper " { $snippet "close_notify" } " sequence. This error is never reported for " { $link SSLv2 } " connections because there is no distinction between expected and unexpected connection closure in that case." } ;
 125
 126 HELP: certificate-verify-error
 127 { $error-description "Thrown if certificate verification failed. The " { $snippet "result" } " slot contains an object identifying the low-level error that occurred." } ;
 128
 129 HELP: common-name-verify-error
 130 { $error-description "Thrown during certificate verification if the host name on the certificate does not match the host name the socket was connected to. This indicates a potential man-in-the-middle attack. The " { $slot "expected" } " and " { $slot "got" } " slots contain the mismatched host names." } ;
 131
 132 HELP: upgrade-on-non-socket
 133 { $error-description "Thrown if " { $link send-secure-handshake } " or " { $link accept-secure-handshake } " is called with the " { $link input-stream } " and " { $link output-stream } " variables not set to a socket. This error can also indicate that the connection has already been upgraded to a secure connection." } ;
 134
 135 HELP: upgrade-buffers-full
 136 { $error-description "Thrown if " { $link send-secure-handshake } " or " { $link accept-secure-handshake } " is called when there is still data which hasn't been read or written." }
 137 { $notes "Clients should ensure to " { $link flush } " their last command to the server before calling " { $link send-secure-handshake } "." } ;
 138
 139 ARTICLE: "ssl-errors" "Secure socket errors"
 140 "Secure sockets can throw one of several errors in addition to the usual I/O errors:"
 141 { $subsections
 142     premature-close
 143     certificate-verify-error
 144     common-name-verify-error
 145 }
 146 "The " { $link send-secure-handshake } " word can throw one of two errors:"
 147 { $subsections
 148     upgrade-on-non-socket
 149     upgrade-buffers-full
 150 } ;
 151
 152 ARTICLE: "io.sockets.secure" "Secure sockets (SSL, TLS)"
 153 "The " { $vocab-link "io.sockets.secure" } " vocabulary implements secure, encrypted sockets using the OpenSSL library."
 154 $nl
 155 "At present, this vocabulary only works on Unix, and not on Windows."
 156 $nl
 157 "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (" { $url "http://www.openssl.org/" } "), cryptographic software written by Eric Young (eay@cryptsoft.com) and software written by Tim Hudson (tjh@cryptsoft.com)."
 158 { $subsections
 159     "ssl-config"
 160     "ssl-contexts"
 161     "ssl-addresses"
 162     "ssl-upgrade"
 163     "ssl-errors"
 164 } ;
 165
 166 ABOUT: "io.sockets.secure"