ssl-connection-copy-peer-certificates

release-certificates-vector

release-certificate Functions

Summary

Expert use: gets pointers to the implementation-specific peer certificate objects.

Package

comm

Signatures

ssl-connection-copy-peer-certificates ssl-connection => vector-of-certificates

release-certificates-vector vector-of-certificates-and-nils

release-certificate foreign-certificate

Arguments

`ssl-connection`⇩	A SSL connection (socket-stream or async-io-state).
`vector-of-certificates-and-nils`⇩
	A simple vector of `nil`s and certificate pointers.
`foreign-certificate`⇩	A certificate pointer.

Values

`vector-of-certificates`⇩
	A newly allocated simple vector of certificate pointers.

Description

The function ssl-connection-copy-peer-certificates returns the certificates that the peer in ssl-connection sent. The result vector-of-certificates is a newly allocated simple vector where each element is a certificate pointer, which means a FLI pointer to a certificate object of the underlying SSL implementation. For the Apple implementation, the pointers are of type sec-certificate-ref, corresponding to the C type SecCertificateRef in the Apple Security Framework. For the OpenSSL implementation, the pointers are of type x509-pointer, corresponding to the C type X509* in the OpenSSL API. ssl-connection can also be a socket-stream using Java sockets (opened by open-tcp-stream-using-java), in which case the certificate pointer is a lw-ji:jobject of Java class java.security.cert.Certificate.

The certificates are "copied", which really means their reference counters are incremented, and when you finish with them they need to be released by calling release-certificates-vector or release-certificate, or using the releasing functions of the underlying SSL implementation. When the certificates are lw-ji:jobjects, it will not leak memory if you do not release them, but it is (slightly) better to release them anyway.

release-certificates-vector calls release-certificate on each of the non-nil elements of vector-of-certificates-and-nils, which must be a simple vector where each element is either a certificate pointer as described above or nil.

release-certificate releases foreign-certificate, that is it decrements its reference count. foreign-certificate must be a certificate pointer.

Notes

The functions get-certificate-data, get-certificate-common-name and get-certificate-serial-number can be used to access the certificate pointers except when they are lw-ji:jobjects, but they do not give anything that you cannot get more simply by calling ssl-connection-get-peer-certificates-data. Thus ssl-connection-copy-peer-certificates is useful when you need more information about the certificates, which you will need to find using functions or methods of the underlying SSL implementation.

sec-certificate-ref, x509-pointer and lw-ji:jobject are proper Lisp types, which can be used in typep, typecase and as specializers in CLOS methods, so it is easy to write code that does different things for different implementations.

Typically, you release all the certificates by calling release-certificates-vector on the result of ssl-connection-get-peer-certificates-data, but sometimes it is useful to keep some of the certificates and release the rest. In this case, set the elements of the vector that correspond to the certificates you want to keep to nil, and then call release-certificates-vector to release all the other certificates.