Credentials Manager

A CredentialsManager is a way to abstract how the application stores credentials in a way that is usable by protocol implementations. Currently the main user is the Transport Layer Security implementation.

Vector!X509Certificate 
     trustedCertificateAuthorities(in string type,
                                   in string context);

Return the list of trusted certificate authorities.

When type is "tls-client", context will be the hostname of the server, or empty if the hostname is not known.

When type is "tls-server", the context will again be the hostname of the server, or empty if the client did not send a server name indicator. For TLS servers, these CAs are the ones trusted for signing of client certificates. If you do not want the TLS server to ask for a client cert, trustedCertificateAuthorities should return an empty list for type "tls-server".

The default implementation returns an empty list.

void verifyCertificateChain(in string type,
                            in string hostname,
                            Vector!X509Certificate cert_chain);

Verifies the certificate chain in cert_chain, assuming the leaf certificate is the first element.

If hostname is set, additionally verifyCertificateChain will check that the leaf certificate has a DNS entry matching hostname.

In the default implementation the type argument is passed, along with hostname, to trustedCertificateAuthorities to find out what root(s) should be trusted for verifying this certificate.

This function indicates a validation failure by throwing an exception.

This function has a default implementation that probably sufficies for most uses, however can be overrided for implementing extra validation routines such as public key pinning.

Vector!X509Certificate certChain(in Vector!string cert_key_types, 
                                   in string type,
								   in string context)

Return the certificate chain to use to identify ourselves

Vector!X509Certificate certChainSingleType(in string cert_key_type,
                                               in string type,
                                               in string context);

Return the certificate chain to use to identifier ourselves, if we have one of type cert_key_type and we would like to use a certificate in this type / context.

PrivateKey privateKeyFor(in X509Certificate cert, 
                         in string type,
                         in string context);

Return the private key for this certificate. The cert will be the leaf cert of a chain returned previously by certChain or certChainSingleType.

SRP Authentication

CredentialsManager contains the hooks used by TLS clients and servers for SRP authentication.

bool attemptSrp(in string type, in string context);

Returns true if we should consider using SRP for authentication

string srpIdentifier(in string type, in string context)

Returns the SRP identifier we'd like to use (used by client)

string srpPassword(in string type, in string context, in string identifier);

Returns the password for identifier (used by client)

bool srpVerifier(in string type,
                  in string context,
                  in string identifier,
                  in string group_name,
                  BigInt verifier,
                  Vector!ubyte salt,
                  bool generate_fake_on_unknown)

Returns the SRP verifier information for identifier (used by server)

Preshared Keys

TLS and some other protocols support the use of pre shared keys for authentication.

SymmetricKey psk(in string type,
                 in string context,
                 in string identity);

Return a symmetric key for use with identity

One important special case for psk is where type is "tls-server", context is "session-ticket" and identity is an empty string. If a key is returned for this case, a TLS server will offer session tickets to clients who can use them, and the returned key will be used to encrypt the ticket. The server is allowed to change the key at any time (though changing the key means old session tickets can no longer be used for resumption, forcing a full re-handshake when the client next connects). One simple approach to add support for session tickets in your server is to generate a random key the first time psk is called to retrieve the session ticket key, cache it for later use in the CredentialsManager, and simply let it be thrown away when the process terminates.

See RFC 4507 for more information about TLS session tickets.

string pskIdentityHint(in string type, in string context)

Returns an identity hint which may be provided to the client. This can help a client understand what PSK to use.

string pskIdentity(in string type, 
                   in string context,
                   in string identity_hint);

Returns the identity we would like to use given this type and context and the optional identity_hint. Not all servers or protocols will provide a hint.