Applications that exchange sensitive data with e.g., a backend server
typically need to ensure they have a secure connection to their peer. To
do this, first obtain a non-secure connection to the peer (eg via a TCP
socket connection). Then create an SSL context via
ssl_context/3.
For the client initiating the connection, the role is’client', and
you should pass options host/1
and cacerts/1
at the very least. If you expect the peer to have a certificate which
would be accepted by your host system, you can pass
cacerts([system(root_certificates)]), otherwise you will
need a copy of the CA certificate which was used to sign the peer's
certificate. Alternatively, you can pass cert_verify_hook/1
to write your own custom validation for the peer's certificate.
Depending on the requirements, you may also have to provide your /own/
certificate if the peer demands mutual authentication. This is done via
the
certificate_file/1, key_file/1
and either password/1
or
pem_password_hook/1.
Once you have the SSL context and the non-secure stream, you can call
ssl_negotiate/5
to obtain a secure stream. ssl_negotiate/5
will raise an exception if there were any certificate errors that could
not be resolved.
The peer behaves in a symmetric fashion: First, a non-secure
connection is obtained, and a context is created using ssl_context/3
with the role set to server. In the server case, you must provide
certificate_file/1
and key_file/1,
and then either password/1
or
pem_password_hook/1.
If you require the other party to present a certificate as well, then
peer_cert(true) should be provided. If the peer does not present a
certificate, or the certificate cannot be validated as trusted, the
connection will be rejected.
By default, revocation is not checked. To enable certificate
revocation checking, pass require_crl(true) when creating the SSL
context. See section 6 for more
information about revocations.
