Each MPC node in the TSM is controlled by an SDK. When the SDK is initiated, it must be authenticated. When the authentication succeeds, the SDK is logged into the MPC node on a given application. The MPC node can have many applications. SDKs that are logged into the same application have access to the same keys.

SDK Authentication

The following types of SDK authentication are supported:

Authentication with API Key

Assuming that the MPC node URL is https://node.tsm.sepior.net and that the MPC node is configured to accept the API key apikey, you can log in like this:

config := tsm.Configuration{URL: "https://node.tsm.sepior.net"}
config = config.WithAPIKeyAuthentication("apikey")
node, err := tsm.NewClient(config)

SDK authentication using an API key requires that the MPC node has been configured to accept the API key, and the actual application that this API key maps to, is specified in the TSM configuration.

Authentication with TLS Client Certificate (mTLS)

As an alternative to API key authentication, the SDK can authenticate using a TLS certificate. This means that the connection between the SDK and the MPC node will be secured using a 2-way TLS connection.

This can be done like this:

clientKey := "/path/to/client.key"
clientCrt := "/path/to/client.crt" 
config := tsm.Configuration{URL: "https://node.tsm.sepior.net"}
config, err = config.WithMTLSAuthentication(clientKey, clientCrt, nil)
node, err := tsm.NewClient(config)

SDK authentication with a client certificate requires that the certificate authority (CA) that issued the client certificate has been registered in the MPC node configuration.

Fine-Grained Access Control with Certificate Attributes

The MPC node can be configured with a client certificate filter. The attributes in the client certificate must match this filter in order for the authentication to succeed, and the filter also defines to which application in the Builder Vault the client gets access.

OCSP Stapling

The MPC node might use OCSP to check the revocation status of the client certificate during mTLS authentication. OCSP works by fetching a signed document from the CA (or a delegated entity) that states the validity of the certificate. If fetched by the MPC node, then no client configuration is necessary.

The OCSP stapling configuration is provided as the third parameter to the call WithMTLSAuthentication(clientKey, clientCert string, ocspStapling *OCSPStaplingConfiguration) and has the form:

type OCSPStaplingConfiguration struct {
    RootCAFile string
    CacheTTL string
    ResponderURL string
    HashAlgorithm string
}

Authentication with OIDC

The SDK can also authenticate using an OIDC access token:

config := tsm.Configuration{URL: "https://node.tsm.sepior.net"}
config, err = config.WithOIDCAccessTokenAuthentication(accessToken)

The accessToken is obtained from the login process performed at the OIDC identity provider.

MPC Node Authentication

Above, we have seen three ways for the MPC node to authenticate the SDK. In the other direction, the SDK authenticates the MPC node using TLS. For this there are a few options:

Providing Root Certificates

Normally, the SDK will validate the MPC node certificate using one of the root certificates from the trust store of the operating system where the SDK is running. You can override this, by providing your own list of root certificates when instantiating the SDK.

config := tsm.Configuration{URL: "https://host:port"}.WithRootCAFile(caFileName)

Public Key Pinning

It is also possible to provide a specific public key when instantiating the SDK. In this case, the SDK will only accept a connection with the MPC node if the MPC node provides a certificate that matches the exact private key corresponding to the provided public key.

nodeCertPEM, err := os.ReadFile("/path/to/node.crt")
block, rest := pem.Decode(nodeCertPEM)
cert, err := x509.ParseCertificate(block.Bytes)
nodePKIXPublicKey, err := x509.MarshalPKIXPublicKey(cert.PublicKey)
config, err := tsm.Configuration{URL: "https://node.tsm.sepior.net"}.WithPublicKeyPinning(nodePKIXPublicKey)
node, err := tsm.NewClient(config)

OSCP Validation

Just as the MPC node can use OCSP to check revocation status of the client certificate, the SDK can use OCSP to validate that the MPC node certificate is not revoked.

newConfig := config.WithOCSPValidation(ocspConfig)

Where the ocspConfig parameter is of type:

type OCSPConfiguration struct {
    RequireStapling bool
    ValidateLeafOnly bool
    CacheTTL string
    ResponderURL string
    HashAlgorithm string
}