Table of Contents

Synopsis:

on [<modes>]server_ssl_eval [<serial#>] [-|^]<match> { <action> }

Description:

This hook is triggered when the client is evaluating an SSL connection to decide whether to accept or reject it. It has made a provisional decision, and offers you an opportunity to review and possibly overrule it. Your handler is not obligated to make any change, but if it does make a decision, it will be final and binding.

Parameters:

$0 The server refnum
$1 The “ourname” of the server (what you /server'd to)
$2 Was there any error at all? 0 = no errors of any kind 1 = some kind of error
$3 Was there a hostname mismatch? 0 = no error, 1 = error
$4 Was there a self-signed error? 0 = no error, 1 = error
$5 Was there another (serious) error? 0 = no other error, 1 = other error
$6 What does the client suggest? 0 = reject certificate, 1 = accept certificate

Information for making a decision

Using $serverctl() to get info about the certificate Use $serverctl(GET <refnum> <item>) where <item> is:

SSL_CIPHER The encryption cipher being used
SSL_PEM The certificate (in PEM format)
SSL_CERT_HASH The certificate's hash
SSL_PKEY_BITS The bits in the public key
SSL_SUBJECT Who the cert was issued to
SSL_SUBJECT_URL Who the cert was issued to (url-encoded)
SSL_ISSUER Who issued the cert
SSL_ISSUER_URL Who issued the cert (url-encoded)
SSL_VERSION What version of SSL being used (ie, TLSv1.2)
SSL_SANS Subject Alternate Names in the cert
SSL_CHECKHOST_ERROR Hostname Mismatch error - 0 (no) 1 (yes)
SSL_SELF_SIGNED_ERROR Self-signed error - 0 (no) 1 (yes)
SSL_OTHER_ERROR Any other (serious) error - 0 (no) 1 (yes)
SSL_MOST_SERIOUS_ERROR The OpenSSL error code of the most serious error 18 (self-signed) and 62 (hostname mismatch) are considered non-serious (routine) errors
SSL_VERIFY_ERROR Any error at all - 0 (no) 1 (yes)
SSL_ACCEPT_CERT Is this cert headed for acceptance? 0 (no) 1 (yes)

Making the decision:

To reject the cert:

 $serverctl(SET $0 SSL_ACCEPT_CERT 0) 

To accept the cert:

 $serverctl(SET $0 SSL_ACCEPT_CERT 1) 

Or, you can do nothing, and the server will do the most reasonable thing.

See also:

about ssl_connections

History:

ON SERVER_SSL_EVAL first appeared in EPIC5-2.1.6