ssl:ssl_context/3

swipl
- library

ssl_context(+Role, -SSL, :Options) is det

Create an SSL context. The context defines several properties of the SSL connection such as involved keys, preferred encryption, and passwords. After establishing a context, an SSL connection can be negotiated using ssl_negotiate/5, turning two arbitrary plain Prolog streams into encrypted streams. This predicate processes the options below.

host(+HostName)

For the client, the host to which it connects. This option should be specified when Role is client. Otherwise, certificate verification may fail when negotiating a secure connection.

certificate_file(+FileName)

Specify where the certificate file can be found. This can be the same as the key_file(+FileName) option. A server must have at least one certificate before clients can connect. A client must have a certificate only if the server demands the client to identify itself with a client certificate using the peer_cert(true) option. If a certificate is provided, it is necessary to also provide a matching private key via the key_file/1 option. To configure multiple certificates, use the option certificate_key_pairs/1 instead. Alternatively, use ssl_add_certificate_key/4 to add certificates and keys to an existing context.

key_file(+FileName)

Specify where the private key that matches the certificate can be found. If the key is encrypted with a password, this must be supplied using the password(+Text) or pem_password_hook(:Goal) option.

certificate_key_pairs(+Pairs)

Alternative method for specifying certificates and keys. The argument is a list of pairs of the form Certificate-Key, where each component is a string or an atom that holds, respectively, the PEM-encoded certificate and key. To each certificate, further certificates of the chain can be appended. Multiple types of certificates can be present at the same time to enable different ciphers. Using multiple certificate types with completely independent certificate chains requires OpenSSL 1.0.2 or greater.

password(+Text)

Specify the password the private key is protected with (if any). If you do not want to store the password you can also specify an application defined handler to return the password (see next option). Text is either an atom or string. Using a string is preferred as strings are volatile and local resources.

pem_password_hook(:Goal)

In case a password is required to access the private key the supplied predicate will be called to fetch it. The hook is called as call(Goal, +SSL, -Password) and typically unifies Password with a string containing the password.

require_crl(+Boolean)

If true (default is false), then all certificates will be considered invalid unless they can be verified as not being revoked. You can do this explicity by passing a list of CRL filenames via the crl/1 option, or by doing it yourself in the cert_verify_hook. If you specify require_crl(true) and provide neither of these options, verification will necessarily fail

crl(+ListOfFileNames)

Provide a list of filenames of PEM-encoded CRLs that will be given to the context to attempt to establish that a chain of certificates is not revoked. You must also set require_crl(true) if you want CRLs to actually be checked by OpenSSL.

cacert_file(+FileName)

Deprecated. Use cacerts/1 instead. Specify a file containing certificate keys of trusted certificates. The peer is trusted if its certificate is signed (ultimately) by one of the provided certificates. Using the FileName system(root_certificates) uses a list of trusted root certificates as provided by the OS. See system_root_certificates/1 for details.

cacerts(+ListOfCATerms)

Specify a list of sources of trusted certificates. Each element in the list should be one of the following:

file(Filename): A file containing one or more PEM-encoded certificates
certificate(Blob): A certificate blob
system(root_certificates): A special term which refers to the certificates trusted by the host OS.

Additional verification of the peer certificate as well as accepting certificates that are not trusted by the given set can be realised using the hook cert_verify_hook(:Goal).

cert_verify_hook(:Goal)

The predicate ssl_negotiate/5 calls Goal as follows:

call(Goal, +SSL,
     +ProblemCertificate, +AllCertificates, +FirstCertificate,
     +Error)

In case the certificate was verified by one of the provided certifications from the cacert_file option, Error is unified with the atom verified. Otherwise it contains the error string passed from OpenSSL. Access will be granted iff the predicate succeeds. See load_certificate/2 for a description of the certificate terms. See cert_accept_any/5 for a dummy implementation that accepts any certificate.

cipher_list(+Atom)

Specify a cipher preference list (one or more cipher strings separated by colons, commas or spaces). See ssl_secure_ciphers/1.

ecdh_curve(+Atom)

Specify a curve for ECDHE ciphers. If this option is not specified, the OpenSSL default parameters are used. With OpenSSL prior to 1.1.0, prime256v1 is used by default.

peer_cert(+Boolean)

Trigger the request of our peer's certificate while establishing the SSL layer. This option is automatically turned on in a client SSL socket. It can be used in a server to ask the client to identify itself using an SSL certificate.

close_parent(+Boolean)

If true, close the raw streams if the SSL streams are closed. Default is false.

close_notify(+Boolean)

If true (default is false), the server sends TLS close_notify when closing the connection. In addition, this mitigates truncation attacks for both client and server role: If EOF is encountered without having received a TLS shutdown, an exception is raised. Well-designed protocols are self-terminating, and this attack is therefore very rarely a concern.

min_protocol_version(+Atom)

Set the minimum protocol version that can be negotiated. Atom is one of sslv3, tlsv1, tlsv1_1, tlsv1_2 and tlsv1_3. This option is available with OpenSSL 1.1.0 and later, and should be used instead of disable_ssl_methods/1.

max_protocol_version(+Atom)

Set the maximum protocol version that can be negotiated. Atom is one of sslv3, tlsv1, tlsv1_1, tlsv1_2 and tlsv1_3. This option is available with OpenSSL 1.1.0 and later, and should be used instead of disable_ssl_methods/1.

disable_ssl_methods(+List)

A list of methods to disable. Unsupported methods will be ignored. Methods include sslv2, sslv3, sslv23, tlsv1, tlsv1_1 and tlsv1_2. This option is deprecated starting with OpenSSL 1.1.0. Use min_protocol_version/1 and max_protocol_version/1 instead.

ssl_method(+Method)

Specify the explicit Method to use when negotiating. For allowed values, see the list for disable_ssl_methods above. Using this option is discouraged. When using OpenSSL 1.1.0 or later, this option is ignored, and a version-flexible method is used to negotiate the connection. Using version-specific methods is deprecated in recent OpenSSL versions, and this option will become obsolete and ignored in the future.

sni_hook(:Goal)

This option provides Server Name Indication (SNI) for SSL servers. This means that depending on the host to which a client connects, different options (certificates etc.) can be used for the server. This TLS extension allows you to host different domains using the same IP address and physical machine. When a TLS connection is negotiated with a client that has provided a host name via SNI, the hook is called as follows:

call(Goal, +SSL0, +HostName, -SSL)

Given the current context SSL0, and the host name of the client request, the predicate computes SSL which is used as the context for negotiating the connection. The first solution is used. If the predicate fails, the default options are used, which are those of the encompassing ssl_context/3 call. In that case, if no default certificate and key are specified, the client connection is rejected.

alpn_protocols(+ListOfProtoIdentifiers)

Provide a list of acceptable ALPN protocol identifiers as atoms. ALPN support requires OpenSSL 1.0.2 or greater.

alpn_protocol_hook(:Goal)

This options provides a callback for a server context to use to select an ALPN protocol. It will be called as follows:

=== call(Goal, +SSLCtx0, +ListOfClientProtocols, -SSLCtx1, -SelectedProtocol) ===

If this option is unset and the alpn_protocols/1 option is set, then the first common protocol between client & server will be selected.

Arguments:

`Role`	- is one of `server` or `client` and denotes whether the `SSL` instance will have a server or client role in the established connection.
`SSL`	- is a SWI-Prolog blob of type `ssl_context`, i.e., the type-test for an `SSL` context is `blob(SSL, ssl_context)`.