ssl-connection-verify

ssl-connection-verify Function

Summary

Verify the certificates that the peer in a SSL connection sent.

Package

comm

Signature

ssl-connection-verify ssl-connection => success-p, more-info

Arguments

ssl-connection⇩

A SSL connection (socket-stream or async-io-state).

Values

`success-p`⇩	A boolean.
`more-info`⇩	A number or a keyword (implementation dependent).

Description

The function ssl-connection-verify can be used to verify the certificate(s) that the peer has sent, which means checking that there is a proper chain of certificates that ends with a trusted certificate. ssl-connection must a socket connection (either a socket-stream or an async-io-state) that is associated with SSL using the :ssl-ctx keyword (see 25.9.6 Keyword arguments for use with SSL).

The first value success-p indicates whether the verification succeeded. The second value more-info gives more information about any failure.

On the Apple implementation, more-info is a keyword, which can either be :timeout to indicate timeout, or a keyword corresponding to a C constant in the Apple Security Framework as listed in the table below.

more-info values for the Apple implementation
Keyword	Matching C constant in the Apple Security Framework
`:proceed`	`kSecTrustResultProceed`
`:unspecified`	`kSecTrustResultUnspecified`
`:invalid`	`kSecTrustResultInvalid`
`:deny`	`kSecTrustResultDeny`
`:confirm`	`kSecTrustResultConfirm`
`:recoverable`	`kSecTrustResultRecoverableTrustFailure`
`:error`	`kSecTrustResultError`
`:fatal`	`kSecTrustResultFatal`

On the OpenSSL implementation, more-info is an integer, which is the value of one of the X509_V_ERR_… constants in OpenSSL.

Notes

ssl-connection-verify may be called inside the verify-callbck of an ssl-abstract-context (see create-ssl-client-context). Typically verify-callbck will first call ssl-connection-verify, and then may do further checks.

The result of ssl-connection-verify is depndent on the configuration of ssl-connection. Most importantly, it will return nil if the root certificate is not found in the list of trusted certificates. In this case, more-info is 20 for OpenSSL implementation (value of X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY). For the Apple implementation, more-info is :recoverable in this case, but that may indicate other kinds of failure too. You can configure the trusted certficates by using the keywords apple-use-system-trusted and apple-add-trusted-file (Apple) or openssl-trusted-file and openssl-trusted-directory (OpenSSL) when creating an abstract context using create-ssl-client-context or create-ssl-server-context.

For the Apple implementation, ssl-connection-verify may also return the results of the Apple trust callback of the context used to create ssl-connection, See the discussion of apple-trust-callback in the documentation for create-ssl-client-context and create-ssl-server-context.