2 USING: help.markup help.syntax calendar quotations io.sockets ;
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 } "." } ;
8 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
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" } ")." } ;
13 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
15 "SSLv3 is widely used, however it is being supersceded by TLSv1." } ;
18 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
20 "This value indicates that either SSLv2 or SSLv3 is acceptable." } ;
23 { $description "Possible value for the " { $snippet "method" } " slot of a " { $link secure-config } "."
25 "TLSv1 is the newest protocol for secure socket communications." } ;
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:"
30 { $subsection SSLv23 }
33 "The default value is " { $link SSLv23 } "." ;
36 { $class-description "Instances represent secure socket configurations." } ;
39 { $values { "config" secure-config } }
40 { $description "Creates a new secure socket configration with default values." } ;
42 ARTICLE: "ssl-key-file" "The key file and password"
43 "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." ;
45 ARTICLE: "ssl-ca-file" "The CA file and path"
46 "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."
48 "One of these slots are required to be specified so that secure client sockets can verify server certificates."
50 "See " { $url "http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html" } " for details." ;
52 ARTICLE: "ssl-dh-file" "Diffie-Hellman parameter file"
53 "The " { $snippet "dh-file" } " slot of a " { $link secure-config } " can contain the path of a file with Diffie-Hellman key exchange parameters."
55 "This slot is required for secure server sockets." ;
57 ARTICLE: "ssl-ephemeral-rsa" "Ephemeral RSA key bits"
58 "The " { $snippet "ephemeral-key-bits" } " slot of a " { $link secure-config } " contains the length of the empheral RSA key, in bits."
60 "The default value is 1024, and anything less than that is considered insecure. This slot is required for secure server sockets." ;
62 ARTICLE: "ssl-config" "Secure socket configuration"
63 "Secure sockets require some configuration, particularly for server sockets. A class represents secure socket configuration parameters:"
64 { $subsection secure-config }
65 "Creating new instances:"
66 { $subsection <secure-config> }
67 "Configuration parameters:"
68 { $subsection "ssl-methods" }
69 { $subsection "ssl-key-file" }
70 { $subsection "ssl-ca-file" }
71 { $subsection "ssl-dh-file" }
72 { $subsection "ssl-ephemeral-rsa" } ;
74 HELP: <secure-context>
75 { $values { "config" secure-config } { "context" secure-context } }
76 { $description "Creates a new " { $link secure-context } ". This word should not usually be called directly, use " { $link with-secure-context } " instead." } ;
78 HELP: with-secure-context
79 { $values { "config" secure-config } { "quot" quotation } }
80 { $description "Calls the quotation in a new dynamic scope where a " { $link secure-context } " constructed from the specified configuration is available." } ;
82 ARTICLE: "ssl-contexts" "Secure socket contexts"
83 "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."
84 { $subsection with-secure-context } ;
87 { $class-description "The class of secure socket addresses." } ;
89 HELP: <secure> ( addrspec -- secure )
90 { $values { "addrspec" "an address specifier" } { "secure" secure } }
91 { $description "Creates a new secure socket address, which can then be passed to " { $link <client> } " or " { $link <server> } "." } ;
93 ARTICLE: "ssl-addresses" "Secure socket addresses"
94 "Secure socket connections are established by passing a secure socket address to " { $link <client> } " or " { $link <server> } "."
96 "Secure socket addresses form a class:"
97 { $subsection secure }
98 "Constructing secure socket addresses:"
99 { $subsection <secure> }
100 "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." ;
102 HELP: premature-close
103 { $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." } ;
105 HELP: certificate-verify-error
106 { $error-description "Thrown if certificate verification failed. The " { $snippet "result" } " slot contains an object identifying the low-level error that occurred." } ;
108 HELP: common-name-verify-error
109 { $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 " { $snippet "expected" } " and " { $snippet "got" } " slots contain the mismatched host names." } ;
111 ARTICLE: "ssl-errors" "Secure socket errors"
112 "Secure sockets can throw one of several errors in addition to the usual I/O errors:"
113 { $subsection premature-close }
114 { $subsection certificate-verify-error }
115 { $subsection common-name-verify-error } ;
117 ARTICLE: "io.sockets.secure" "Secure sockets (SSL, TLS)"
118 "The " { $vocab-link "io.sockets.secure" } " vocabulary implements secure, encrypted sockets using the OpenSSL library."
119 { $subsection "ssl-config" }
120 { $subsection "ssl-contexts" }
121 { $subsection "ssl-addresses" }
122 { $subsection "ssl-errors" }
123 "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)." ;
125 ABOUT: "io.sockets.secure"