Class SSL.Context

Inheritance graph
predef::SSL.Context 8.0::SSL.Context
Description

Keeps the state that is shared by all SSL-connections on a client, or for one port on a server. It includes policy configuration, the server or client certificate(s), the corresponding private key(s), etc. It also includes the session cache.

The defaults are usually suitable for a client, but for a server some configuration is necessary.

Typical use is to:

  • Call add_cert() with the certificates belonging to the server or client. Note that clients often don't have or need any certificates, and also that certificate-less server operation is possible, albeit discouraged and not enabled by default.

    Suitable self-signed certificates can be created with Standards.X509.make_selfsigned_certificate().

  • Optionally call get_suites() to get a set of cipher_suites to assign to preferred_suites. This is only needed if the default set of suites from get_suites(128, 1) isn't satisfactory.

The initialized Context object is then passed to File()->create() or used as is embedded in Port.

See also

File, Port, Standards.X509


Variable advertised_protocols

array(string(8bit))|zero SSL.Context.advertised_protocols

Description

List of advertised protocols using using TLS application level protocol negotiation.


Variable auth_level

int SSL.Context.auth_level

Description

Policy for client authentication. One of SSL.Constants.AUTHLEVEL_none, SSL.Constants.AUTHLEVEL_verify, SSL.Constants.AUTHLEVEL_ask and SSL.Constants.AUTHLEVEL_require.

Defaults to SSL.Constants.AUTHLEVEL_none.


Variable client_auth_methods

array(int) SSL.Context.client_auth_methods

Description

The possible client authentication methods. Used only if auth_level is AUTH_ask or AUTH_require. Generated by set_authorities.


Variable ecc_curves

array(int) SSL.Context.ecc_curves

Description

Supported elliptical curve cipher curves in order of preference. Defaults to all supported curves, ordered with the largest curves first.


Variable enable_renegotiation

bool SSL.Context.enable_renegotiation

Description

If set enable SSL/TLS protocol renegotiation.

Defaults to 1 (enabled).

Note

RFC 7540 section 9.2.1 requires this to be turned off after Protocols.HTTP2 communication has started.


Variable encrypt_then_mac

bool SSL.Context.encrypt_then_mac

Description

Attempt to enable encrypt-then-mac mode. Defaults to 1.

Deprecated

Replaced by extensions.


Variable extensions

multiset(int) SSL.Context.extensions

Description

A list of all extensions that will be considered in the handshake process. Extensions not listed will not be sent, and will be ignored if received.

The following values are included by default.

Constants.EXTENSION_renegotiation_info

Protection against renegotiation attack (RFC 5746).

Constants.EXTENSION_max_fragment_length

Allows negotiation of the maximum fragment size (RFC 6066 section 4).

Constants.EXTENSION_encrypt_then_mac

Attempts to address attacks against block ciphers (RFC 7366).

Constants.EXTENSION_application_layer_protocol_negotiation

Required to support more than one protocol on the same TLS port (RFC 7639).

Constants.EXTENSION_signature_algorithms

Required to select which out of several certificates to use (RFC 5246 section 7.4.1.4.1).

Constants.EXTENSION_ec_point_formats

Required for elliptic curve key exchange (RFC 4492 section 5.1.2).

Constants.EXTENSION_elliptic_curves

Required for elliptic curve key exchange (RFC 4492 section 5.1.1).

Constants.EXTENSION_server_name

Allows the client to select which of several domains hosted on the same server it wants to connect to. Required by many websites (RFC 6066 section 3).

Constants.EXTENSION_session_ticket

Support session resumption without server-side state (RFC 4507 and RFC 5077).

Constants.EXTENSION_next_protocol_negotiation

Not supported by Pike. The server side will just check that the client packets are correctly formatted.

Constants.EXTENSION_signed_certificate_timestamp

Not supported by Pike. The server side will just check that the client packets are correctly formatted.

Constants.EXTENSION_early_data

Needed for TLS 1.3 0-RTT handshake. EXPERIMENTAL.

Constants.EXTENSION_padding

This extension is required to avoid a bug in some f5 SSL terminators for certain sizes of client handshake messages.

The following supported values are not included by default.

Constants.EXTENSION_truncated_hmac

This extension allows for the HMAC to be truncated for a small win in payload size. Not widely implemented and may be a security risk (RFC 6066 section 7).

Constants.EXTENSION_heartbeat

This extension allows the client and server to send heartbeats over the connection. Intended to keep TCP connections alive. Required to be set to use heartbleed_probe (RFC 6520).

Constants.EXTENSION_extended_master_secret

Binds the master secret to important session parameters to protect against man in the middle attacks (RFC 7627).

See also

RFC 6066


Variable ffdhe_groups

array(int) SSL.Context.ffdhe_groups

Description

Supported FFDHE groups for DHE key exchanges, in order of preference, most preferred first.

Defaults to the full set of supported FFDHE groups from the FFDHE draft, in order of size with the smallest group (2048 bits) first.

Server-side the first group in the list that satisfies the NIST guide lines for key strength (NIST SP800-57 5.6.1) (if any) for the selected cipher suite will be selected, and otherwise the largest group.

Client-side the list will be reversed (as a precaution if the server actually follows the clients preferences).


Variable heartbleed_probe

bool SSL.Context.heartbleed_probe

Description

If set, the other peer will be probed for the heartbleed bug during handshake. If heartbleed is found the connection is closed with insufficient security fatal error. Requires Constants.EXTENSION_heartbeat to be set in extensions.


Variable max_sessions

int SSL.Context.max_sessions

Description

Maximum number of sessions to keep in the cache.


Variable min_version
Variable max_version

int SSL.Context.min_version
int SSL.Context.max_version

Description

The accepted range of versions for the client/server. List specific versions in supported_versions instead.

Deprecated

Replaced by supported_versions.


Variable packet_max_size

int SSL.Context.packet_max_size

Description

The maximum amount of data that is sent in each SSL packet by File. A value between 1 and Constants.PACKET_MAX_SIZE.


Variable preferred_compressors

array(int) SSL.Context.preferred_compressors

Description

Lists the supported compression algorithms in order of preference.

Defaults to ({ COMPRESSION_null }) due to SSL attacks that target compression.


Variable preferred_suites

array(int)|zero SSL.Context.preferred_suites

Description

Cipher suites we want to support, in order of preference, best first. By default set to all suites with at least 128 bits cipher key length, excluding RC4, and ephemeral and non-ephemeral certificate based key exchange.


Variable private_ffdhe_groups

mapping(int(508..511):Crypto.DH.Parameters) SSL.Context.private_ffdhe_groups

Description

DHE parameter lookup for the FFDHE private range.

Add any custom FFDHE-groups here.

Defaults to the empty mapping.

Note

If you add any groups here, you will also need to update ffdhe_groups accordingly.


Variable random

function(int(0..):string(8bit)) SSL.Context.random

Description

Used to generate random cookies for the hello-message. If we use the RSA keyexchange method, and this is a server, this random number generator is not used for generating the master_secret. By default set to random_string.


Variable require_trust

int SSL.Context.require_trust

Description

When set, require the chain to be known, even if the root is self signed.

Note that if set, and certificates are set to be verified, trusted issuers must be provided, or no connections will be accepted.

Deprecated

Replaced by auth_level.


Variable session_lifetime

int SSL.Context.session_lifetime

Description

Sessions are removed from the cache when they have been inactive more than this number of seconds. Sessions are also removed from the cache if a connection using the session dies unexpectedly.


Variable signature_algorithms

array(int) SSL.Context.signature_algorithms

Description

The set of <hash, signature> combinations to use by us.

Only used with TLS 1.2 and later.

Defaults to all combinations supported by Pike except for MD5.

This list is typically filtered by get_signature_algorithms() to get rid of combinations not supported by the runtime.

Note

According to RFC 5246 section 7.4.2 all certificates need to be signed by any of the supported signature algorithms. To be forward compatible this list needs to be limited to the combinations that have existing PKCS identifiers.

See also

get_signature_algorithms()


Variable supported_versions

array(ProtocolVersion) SSL.Context.supported_versions

Description

List of supported versions, in order of preference. Defaults to PROTOCOL_TLS_1_2, PROTOCOL_TLS_1_1 and PROTOCOL_TLS_1_0.


Variable trusted_issuers_cache

mapping(string(8bit):array(Standards.X509.Verifier)) SSL.Context.trusted_issuers_cache

Description

Mapping from DER-encoded issuer to Standards.X509.Verifiers compatible with eg Standards.X509.verify_certificate() and Standards.X509.load_authorities().

See also

get_trusted_issuers(), set_trusted_issuers()


Variable use_cache

int SSL.Context.use_cache

Description

Non-zero to enable caching of sessions


Variable verifier_algorithms

mapping(Standards.ASN1.Types.Identifier:Crypto.Hash) SSL.Context.verifier_algorithms

Description

Mapping of supported verifier algorithms to hash implementation.

See also

Standards.X509.get_algorithms()


Variable verify_certificates

int SSL.Context.verify_certificates

Description

Determines whether certificates presented by the peer are verified, or just accepted as being valid.

Deprecated

Replaced by auth_level.