As indicated above, individual channels can be given their own callbacks to handle intermediate processing by the OpenSSL library, using the --command and -password options passed to either of +-command, -password, and +-validate_command options passed to either of tls::socket or tls::import.
@@ -495,11 +497,11 @@
SSL_CTX_sess_set_new_cb(). Where session_id is the current session identifier, ticket is the session ticket info, and lifetime is the the ticket lifetime in seconds. - +
@@ -514,11 +516,11 @@-validatecommand callback Invokes the specified callback script during handshake in - order to verify/validate the provided value. + order to validate the provided value(s). To reject the value and abort connection, the callback should return 0. To accept the value, it should return 1. To reject the value, but continue the connection, it should return 2.
@@ -529,11 +531,11 @@alpn protocol For servers, this form of callback is invoked when the client ALPN - header is received and the first -alpn specified protocol common + extension is received and the first -alpn specified protocol common to the both the client and server is selected. If none, the first client specified protocol is used.
@@ -541,11 +543,11 @@hello servername For servers, this form of callback is invoked during client hello - message processing. Used to select an appropriate certificate to + message processing. It is used to select an appropriate certificate to present, and make other configuration adjustments relevant to that server name and its configuration. Called before SNI and ALPN callbacks.
@@ -552,13 +554,12 @@sni servername - For servers, this form of callback is invoked when the SNI header - from the client is received. Where servername is the client - specified servername. This is used when a server supports multiple + For servers, this form of callback is invoked when the SNI extension + from the client is received. This is used when a server supports multiple names, so the right certificate can be used. Called after hello callback but before ALPN callback.
@@ -583,36 +584,32 @@ A value of0means the certificate is deemed invalid. A value of1means the certificate is deemed valid.The error argument supplies the message, if any, generated by -X509_STORE_CTX_get_error().
-
- The callback may override normal validation processing by explicitly - returning one of the above status values.
Reference implementations of these callbacks are provided in the -distribution as tls::callback and -tls::password respectively. Note that these are +distribution as tls::callback, tls::password, +and tls::validate_command respectively. Note that these are sample implementations only. In a more realistic deployment -you would specify your own callback scripts on each TLS channel -using the -command and -password options. +you would specify your own callback scripts on each TLS channel using the +-command, -password, and -validate_command options.
-The default behavior when the -command option is not specified is for -TLS to process the associated library callbacks internally. -The default behavior when the -password option is not specified is for -TLS to process the associated library callbacks by attempting to call -tls::password. +The default behavior when the -command and -validate_command +options are not specified is for TLS to process the associated library callbacks +internally. The default behavior when the -password option is not +specified is for TLS to process the associated library callbacks by attempting +to call tls::password. The difference between these two behaviors is a consequence of maintaining compatibility with earlier implementations.
@@ -623,13 +620,13 @@ certificate, even when it is invalid.
-The use of the reference callbacks tls::callback and -tls::password is not recommended. They may be removed -from future releases. +The use of the reference callbacks tls::callback, +tls::password, and tls::validate_command +is not recommended. They may be removed from future releases.
@@ -640,11 +637,13 @@
This example uses a sample server.pem provided with the TLS release,
courtesy of the OpenSSL project. The capabilities of this package can vary enormously based
-upon how your OpenSSL library was configured and built. At the
-most macro-level OpenSSL supports a "no patents" build,
-which disables RSA, IDEA, RC(2,4,5) and SSL2 - if your OpenSSL is
-configured this way then you will need to build TLS with the
--DNO_PATENTS option - and the resultant module will function
-correctly and also support ADH certificate-less encryption,
-however you will be unable to utilize this to speak to normal Web
-Servers, which typically require RSA support. Please see http://www.openssl.org/ for
-more information on the whole issue of patents and US export
-restrictions. The capabilities of this package can vary enormously based upon how your
+OpenSSL library was configured and built. New versions may obsolete older
+protocol versions, add or remove ciphers, change default values, etc. Use the
+tls::ciphers and tls::protocols commands to
+obtain the supported versions. socket, fileevent, OpenSSLDEBUG
TLS key logging can be enabled by setting the environment variable
SSLKEYLOGFILE to the name of the file to log to. Then whenever TLS
-key material is generated or received it will be logged to the file.
+key material is generated or received it will be logged to the file. This
+is useful for logging key data for network logging tools to use to
+decrypt the data.
HTTPS EXAMPLE
SPECIAL CONSIDERATIONS
-SEE ALSO