SecurityContext abstract final

abstract final class SecurityContext

The object containing the certificates to trust when making a secure client connection, and the certificate chain and private key to serve from a secure server.

The SecureSocket and SecureServerSocket classes take a SecurityContext as an argument to their connect and bind methods.

Certificates and keys can be added to a SecurityContext from either PEM or PKCS12 containers.

iOS note: Some methods to add, remove, and inspect certificates are not yet implemented. However, the platform's built-in trusted certificates can be used, by way of SecurityContext.defaultContext.

Constructors

SecurityContext() factory

factory SecurityContext({bool withTrustedRoots = false})

Creates a new SecurityContext.

By default, the created SecurityContext contains no keys or certificates. These can be added by calling the methods of this class.

If withTrustedRoots is passed as true, the SecurityContext will be seeded by the trusted root certificates provided as explained below. To obtain a SecurityContext containing trusted root certificates, SecurityContext.defaultContext is usually sufficient, and should be used instead. However, if the SecurityContext containing the trusted root certificates must be modified per-connection, then withTrustedRoots should be used.

Implementation

external factory SecurityContext({bool withTrustedRoots = false});

Properties

allowLegacyUnsafeRenegotiation read / write

bool allowLegacyUnsafeRenegotiation

getter:

If true, the SecurityContext will allow TLS renegotiation. Renegotiation is only supported as a client and the HelloRequest must be received at a quiet point in the application protocol. This is sufficient to support the legacy use case of requesting a new client certificate between an HTTP request and response in (unpipelined) HTTP/1.1. NOTE: Renegotiation is an extremely problematic protocol feature and should only be used to communicate with legacy servers in environments where it is known to be safe.

setter:

If true, the SecurityContext will allow TLS renegotiation. Renegotiation is only supported as a client and the HelloRequest must be received at a quiet point in the application protocol. This is sufficient to support the legacy use case of requesting a new client certificate between an HTTP request and response in (unpipelined) HTTP/1.1. NOTE: Renegotiation is an extremely problematic protocol feature and should only be used to communicate with legacy servers in environments where it is known to be safe.

Implementation

abstract bool allowLegacyUnsafeRenegotiation;

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

minimumTlsProtocolVersion read / write

TlsProtocolVersion minimumTlsProtocolVersion

getter:

The minimum TLS version to use when establishing a secure connection.

If the peer does not support minimumTlsProtocolVersion or later then SecureSocket.connect will throw a TlsException.

If the value is changed, it will only affect new connections. Existing connections will continue to use the protocol that was negotiated with the peer.

The default value is TlsProtocolVersion.tls1_2.

setter:

The minimum TLS version to use when establishing a secure connection.

If the peer does not support minimumTlsProtocolVersion or later then SecureSocket.connect will throw a TlsException.

If the value is changed, it will only affect new connections. Existing connections will continue to use the protocol that was negotiated with the peer.

The default value is TlsProtocolVersion.tls1_2.

Implementation

abstract TlsProtocolVersion minimumTlsProtocolVersion;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

setAlpnProtocols()

void setAlpnProtocols(List<String> protocols, bool isServer)

Sets the list of application-level protocols supported by a client connection or server connection. The ALPN (application level protocol negotiation) extension to TLS allows a client to send a list of protocols in the TLS client hello message, and the server to pick one and send the selected one back in its server hello message.

Separate lists of protocols can be sent for client connections and for server connections, using the same SecurityContext. The isServer boolean argument specifies whether to set the list for server connections or client connections.

Implementation

void setAlpnProtocols(List<String> protocols, bool isServer);

setClientAuthorities()

void setClientAuthorities(String file, {String? password})

Sets the list of authority names that a SecureServerSocket will advertise as accepted when requesting a client certificate from a connecting client.

The file is a PEM or PKCS12 file containing the accepted signing authority certificates - the authority names are extracted from the certificates. For PKCS12 files, password is the password for the file. For PEM files, password is ignored. Assuming it is well-formatted, all other contents of file are ignored.

NB: This function calls File.readAsBytesSync, and will block on file IO. Prefer using setClientAuthoritiesBytes.

iOS note: This call is not supported.

Implementation

void setClientAuthorities(String file, {String? password});

setClientAuthoritiesBytes()

void setClientAuthoritiesBytes(List<int> authCertBytes, {String? password})

Sets the list of authority names that a SecureServerSocket will advertise as accepted, when requesting a client certificate from a connecting client.

Like setClientAuthorities but takes the contents of the file.

Implementation

void setClientAuthoritiesBytes(List<int> authCertBytes, {String? password});

setTrustedCertificates()

void setTrustedCertificates(String file, {String? password})

Add a certificate to the set of trusted X509 certificates used by SecureSocket client connections.

file is the path to a PEM or PKCS12 file containing X509 certificates, usually root certificates from certificate authorities. For PKCS12 files, password is the password for the file. For PEM files, password is ignored. Assuming it is well-formatted, all other contents of file are ignored.

NB: This function calls File.readAsBytesSync, and will block on file IO. Prefer using setTrustedCertificatesBytes.

iOS note: On iOS, this call takes only the bytes for a single DER encoded X509 certificate. It may be called multiple times to add multiple trusted certificates to the context. A DER encoded certificate can be obtained from a PEM encoded certificate by using the openssl tool:

$ openssl x509 -outform der -in cert.pem -out cert.der

Implementation

void setTrustedCertificates(String file, {String? password});

setTrustedCertificatesBytes()

void setTrustedCertificatesBytes(List<int> certBytes, {String? password})

Add a certificate to the set of trusted X509 certificates used by SecureSocket client connections.

Like setTrustedCertificates but takes the contents of the file.

Implementation

void setTrustedCertificatesBytes(List<int> certBytes, {String? password});

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

useCertificateChain()

void useCertificateChain(String file, {String? password})

Sets the chain of X509 certificates served by SecureServerSocket when making secure connections, including the server certificate.

file is a PEM or PKCS12 file containing X509 certificates, starting with the root authority and intermediate authorities forming the signed chain to the server certificate, and ending with the server certificate. The private key for the server certificate is set by usePrivateKey. For PKCS12 files, password is the password for the file. For PEM files, password is ignored. Assuming it is well-formatted, all other contents of file are ignored.

NB: This function calls File.readAsBytesSync, and will block on file IO. Prefer using useCertificateChainBytes.

iOS note: As noted above, usePrivateKey does the job of both that call and this one. On iOS, this call is a no-op.

Implementation

void useCertificateChain(String file, {String? password});

useCertificateChainBytes()

void useCertificateChainBytes(List<int> chainBytes, {String? password})

Sets the chain of X509 certificates served by SecureServerSocket when making secure connections, including the server certificate.

Like useCertificateChain but takes the contents of the file.

Implementation

void useCertificateChainBytes(List<int> chainBytes, {String? password});

usePrivateKey()

void usePrivateKey(String file, {String? password})

Sets the private key for a server certificate or client certificate.

A secure connection using this SecurityContext will use this key with the server or client certificate to sign and decrypt messages. file is the path to a PEM or PKCS12 file containing an encrypted private key, encrypted with password. Assuming it is well-formatted, all other contents of file are ignored. An unencrypted file can be used, but this is not usual.

NB: This function calls File.readAsBytesSync, and will block on file IO. Prefer using usePrivateKeyBytes.

iOS note: Only PKCS12 data is supported. It should contain both the private key and the certificate chain. On iOS one call to usePrivateKey with this data is used instead of two calls to useCertificateChain and usePrivateKey.

Implementation

void usePrivateKey(String file, {String? password});

usePrivateKeyBytes()

void usePrivateKeyBytes(List<int> keyBytes, {String? password})

Sets the private key for a server certificate or client certificate.

Like usePrivateKey, but takes the contents of the file as a list of bytes.

Implementation

void usePrivateKeyBytes(List<int> keyBytes, {String? password});

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

Static Properties

deprecated alpnSupported no setter

bool get alpnSupported

DEPRECATED

Whether the platform supports ALPN. This always returns true and will be removed in a future release.

Implementation

@deprecated
external static bool get alpnSupported;

defaultContext no setter

SecurityContext get defaultContext

The default security context used by most operation requiring one.

Secure networking classes with an optional context parameter use the defaultContext object if the parameter is omitted. This object can also be accessed, and modified, directly. Each isolate has a different defaultContext object. The defaultContext object uses a list of well-known trusted certificate authorities as its trusted roots. On Linux and Windows, this list is taken from Mozilla, who maintains it as part of Firefox. On, MacOS, iOS, and Android, this list comes from the trusted certificates stores built into the platforms.

Implementation

external static SecurityContext get defaultContext;