4 Secure Contexts🔗ℹ

If secure is true for ssl.Context.Client, the resulting context is sealed in the sense of ssl.Context.seal, and it is configured for peer certificate and hostname verification.

Non-#false arguments passed to ssl.Context.Server correspond to calling ssl.Context.load_private_key and ssl.Context.load_certificate_chain on the created context, respectively.

The following kinds of verification sources are supported as src:

• A PathString is equivalent to ssl.Context.VerifySource.file(src).

• A ssl.Context.VerifySource.default source loads sources, depending on the platform:

  • On Linux, the default sources are determined by the SSL_CERT_FILE and SSL_CERT_DIR environment variables, if the variables are set, or the system-wide default locations otherwise.

  • On Windows, the default sources consist of the system certificate store for root certificates, the same as ssl.Context.VerifySource.win_store("ROOT").

  • On Mac OS, the default sources consist of the OS trust anchor (root) certificates, the same as ssl.Context.VerifySource.mac_keychain(#false).

• A ssl.Context.VerifySource.file source is treated as a PEM file containing root certificates. The file is loaded immediately.

• A ssl.Context.VerifySource.directory source should contain PEM files with hashed symbolic links (see the openssl c_rehash utility). The directory contents are not loaded immediately; rather, they are searched only when a certificate needs verification.

• A ssl.Context.VerifySource.win_store source loads certificates from the name store immediately. Only supported on Windows.

• A ssl.Context.VerifySource.mac_keychain source loads certificates from the Mac OS keychain stored at the insicated path, or it load from trust anchor (root) certificates (as returned by SecTrustCopyAnchorCertificates) if #false is supplied instead of a path. Only supported on Mac OS.

You can use the file "test.pem" as report by collect.file_path(~collect: "openssl", ~file: "test.pem") for testing purposes. Since "test.pem" is public, such a test configuration obviously provides no security.

If kind is #'rsa (the default), the first RSA key is read (i.e., non-RSA keys are skipped).

The following kinds of key values are supported:

• A PathString key is the same as ssl.Context.PrivateKey.pem(key).

• A ssl.Context.PrivateKey.pem key loads a key from the given path in PEM format.

• A ssl.Context.PrivateKey.pem_bytes parses a key from the given byte string in PEM format.

• A ssl.Context.PrivateKey.der key loads a key from the given path in DER/ASN1 format.

You can use the file "test.pem" as report by collect.file_path(~collect: "openssl", ~file: "test.pem") for testing purposes. Since "test.pem" is public, such a test configuration obviously provides no security.

The ssl.Context.load_suggested_certificate_authorities method loads a PEM-format file containing certificates that are used by a server. The certificate list is sent to a client when the server requests a certificate as an indication of which certificates the server trusts. Loading the suggested certificates does not imply trust, however; any certificate presented by the client will be checked using the trusted roots loaded via ssl.Context.load_verify_source.

You can use the file "test.pem" as report by collect.file_path(~collect: "openssl", ~file: "test.pem") for testing purposes with either of these methods. Since "test.pem" is public, such a test configuration obviously provides no security.

The ssl.Context.set_verify_hostname method requires hostname verification of SSL peers of connections. When hostname verification is enabled, the hostname associated with a connection is checked against the hostnames listed in the peer’s certificate. If the peer certificate does not contain an entry matching the hostname, the connection fails. Currently, mode as #'try is treated the same as mode as #'always. Hostname verification does not imply certificate verification; to verify the certificate itself, also use ssl.Context.set_verify.

Enabling verification also requires, at a minimum, designating trusted certificate authorities with ssl.Context.load_verify_source.

If the client does not use ALPN, then the connection is accepted and no protocol is selected. If the client uses ALPN but has no protocols in common with the server, then if allow_no_match is true, the connection is accepted and no protocol is selected; if allow_no_match is #false, then the connection is refused.