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.8.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 the 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.