Class SSL.Context

Inheritance graph

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.