Cryptographic authentication systems enable more secure interactions among machines, individuals, and organizations. These systems often use public-private key cryptography or encryption mechanisms to manage both cryptographic material and operations utilizing that material. This specification provides a common data model and interface for interacting with these systems enabling one to perform secure cryptographic operations on keypairs such as creating, wrapping, unwrapping, signing, encrypting, and decrypting.

Introduction

Cryptographic authentication systems enable machines, individuals, and organizations to more securely interact with one another. These systems often use public-private key cryptography or encryption mechanisms in order to manage cryptographic material as well as operations utilizing that material. There are a variety of these sorts of cryptographic systems in use today, sometimes referred to as Key Management Systems. While many of these sorts of systems exist, there is no common interface for accessing and using these systems.

The creation of a common interface for accessing Key Management Systems would enable software to be written once to interact with these systems such that systems with different implementations and properties could be switched without affecting the client software that utilizes such systems. A common API would shift the burden of interacting with each implementation to the vendors of those systems, while eliminating the burden for application developers.

While there are a variety of proprietary enterprise grade Key Management Systems today that would benefit from a common interface, personal Key Management Systems such as those created through the Fast Identity Online (FIDO) initiative could also benefit.

If the interface is provided as a Web-based interface, then Web-based applications could be written against such an API. Similarly, Web-based applications could provide choice in Key Management Systems -- potentially allowing customers to bring their own Key Management Systems with them just as they bring their own devices today.

Ecosystem Overview

This section describes the roles of the core actors and the relationships between them in an ecosystem where this specification is expected to be useful. A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and protocols for standardization. The following roles are introduced in this specification:

controller
A role an entity might perform by demonstrating control of cryptographic key material in order to authenticate itself with a system.
key management client
A role an entity might perform by communicating with a Key Management System.
key management system
A role an entity might perform by providing an interface to the management of cryptographic material and the execution of cryptographic operations.

Use Cases and Requirements

The following use cases outline a number of key scenarios that readers might find useful:

As a result of documenting and analyzing the use cases, the following desirable ecosystem characteristics were identified for this specification:

TBD

Terminology

Core Concepts

There is a relatively small set of common cryptographic operations that Key Management Systems provide. These operations include: generate, wrap, unwrap, sign, verify, encrypt, and decrypt. These cryptographic operations can be thought of as functions that operate on objects, in this case cryptographic keys, in a remote execution environment.

Ensure that the list is updated from here.

The Authorization Capabilities for Linked Data [ZCAP-LD] specification, also know as ZCAPs, outlines how remote execution environments can be manipulated by demonstrating cryptographic control of functions and objects. The ZCAP-LD specification enables one to grant authority to remote clients to call functions on specific objects. This technology enables a Key Management System to provide a Web-based API that enables clients to create keys and execute cryptographic operations using those keys by invoking ZCAPs.

The WebKMS API enables clients to create keystores, a type of object, that they control. That is, the client is the controller of the keystore. The client may also generate a key, another type of object, and associate it with a keystore. Each keystore is identified by a URI. In addition, the controller of a keystore can be changed to enable the transfer of keys without requiring the exfiltration of the key. Other entities can also be added as controllers of the keystore such that multiple parties might control the keystore without having access to the raw key material.

Each key in the keystore has an associated set of functions according to the type of key that it is. Examples of key types include keys used for performing asymmetric cryptographic operations such as digital signatures and keys used for performing symmetric cryptographic operations such as encryption and decryption. These functions can be remotely executed via the use of ZCAPs such that the cryptographic key material never needs to be exfiltrated in order to use the key. In many hardware-backed cryptographic key management systems, the exfiltration of keys is not supported and the system itself is hardened against tampering with the intent to exfiltrate the keys.

In order to execute a function on a key, a KmsOperation of a specific type can be applied to the key, including a ZCAP that invokes the capability that demonstrates the authorization to perform the operation. For example, a KmsOperation might be constructed and POSTed to the key URL with an invocation of a ZCAP performed via HTTP Signatures.

HTTP API

generateKey(options)<map>

Generates a new cryptographic key in the keystore.

getKeyDescription(options)<map>

Gets the key description for the given key ID.

revokeCapability(options)<map>

Store a capability revocation.

wrapKey(options)<string>

Wraps a cryptographic key using a key encryption key (KEK).

unwrapKey(options)<(Uint8Array|null)>

Unwraps a cryptographic key using a key encryption key (KEK).

sign(options)<string>

Signs some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

verify(options)<boolean>

Verifies some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

deriveSecret(options)<Uint8Array>

Derives a shared secret via the given peer public key, typically for use as one parameter for computing a shared key. It should not be used as a shared key itself, but rather input into a key derivation function (KDF) to produce a shared key.

enableCapability(options)<map>

Stores a delegated authorization capability, enabling it to be invoked by its designated invoker.

disableCapability(options)<boolean>

Removes a previously stored delegated authorization capability, preventing it from being invoked by its designated invoker.

createKeystore(options)<map>

Creates a new keystore using the given configuration.

getKeystore(options)<map>

Gets the configuration for a keystore by its ID.

findKeystore(options)<map>

Finds the configuration for a keystore by its controller and reference ID.

generateKey(options) ⇒ <map>

Generates a new cryptographic key in the keystore.

Response: HTTP 200 - <map> - The key description for the key.

Param Type Description
options.kmsModule string The KMS module to use.
options.type string The key type (e.g. 'AesKeyWrappingKey2019').
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

getKeyDescription(options) ⇒ <map>

Gets the key description for the given key ID.

Response: HTTP 200 - <map> - The key description.

Param Type Description
[options.keyId] string The ID of the key.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

revokeCapability(options) ⇒ <map>

Store a capability revocation.

Response: HTTP 200 - <map> - Resolves once the operation completes.

Param Type Description
options.capabilityToRevoke map The capability to enable.
[options.capability] string The zcap authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

wrapKey(options) ⇒ <string>

Wraps a cryptographic key using a key encryption key (KEK).

Response: HTTP 200 - <string> - The base64url-encoded wrapped key bytes.

Param Type Description
options.kekId string The ID of the wrapping key to use.
options.unwrappedKey Uint8Array The unwrapped key material as a Uint8Array.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

unwrapKey(options) ⇒ <(Uint8Array|null)>

Unwraps a cryptographic key using a key encryption key (KEK).

Response: HTTP 200 - <(Uint8Array|null)> - Resolves to the unwrapped key material or null if the unwrapping failed because the key did not match.

Param Type Description
options.kekId string The ID of the unwrapping key to use.
options.wrappedKey string The wrapped key material as a base64url-encoded string.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

sign(options) ⇒ <string>

Signs some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Response: HTTP 200 - <string> - The base64url-encoded signature.

Param Type Description
options.keyId string The ID of the signing key to use.
options.data Uint8Array The data to sign as a Uint8Array.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

verify(options) ⇒ <boolean>

Verifies some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Response: HTTP 200 - <boolean> - true if verified, false if not.

Param Type Description
options.keyId string The ID of the signing key to use.
options.data Uint8Array The data to verify as a Uint8Array.
options.signature string The base64url-encoded signature to verify.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

deriveSecret(options) ⇒ <Uint8Array>

Derives a shared secret via the given peer public key, typically for use as one parameter for computing a shared key. It should not be used as a shared key itself, but rather input into a key derivation function (KDF) to produce a shared key.

Response: HTTP 200 - <Uint8Array> - The shared secret bytes.

Param Type Description
options.keyId string The ID of the key agreement key to use.
options.publicKey map The public key to compute the shared secret against; the public key type must match the key agreement key's type.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

enableCapability(options) ⇒ <map>

Stores a delegated authorization capability, enabling it to be invoked by its designated invoker.

Response: HTTP 200 - <map> - Resolves once the operation completes.

Param Type Description
options.capabilityToEnable map The capability to enable.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

disableCapability(options) ⇒ <boolean>

Removes a previously stored delegated authorization capability, preventing it from being invoked by its designated invoker.

Response: HTTP 200 - <boolean> - Resolves to true if the document was deleted and false if it did not exist.

Param Type Description
options.id map The ID of the capability to revoke.
[options.capability] string The zCAP-LD authorization capability to use to authorize the invocation of this operation.
options.invocationSigner map An API with an id property and a sign function for signing a capability invocation.

createKeystore(options) ⇒ <map>

Creates a new keystore using the given configuration.

Response: HTTP 200 - <map> - Resolves to the configuration for the newly created keystore.

Param Type Description
options.url string The url to post the configuration to.
options.config string The keystore's configuration.

getKeystore(options) ⇒ <map>

Gets the configuration for a keystore by its ID.

Response: HTTP 200 - <map> - Resolves to the configuration for the keystore.

Param Type Description
options.id string The keystore's ID.

findKeystore(options) ⇒ <map>

Finds the configuration for a keystore by its controller and reference ID.

Response: HTTP 200 - <map> - Resolves to the configuration for the keystore.

Param Type Description
[options.url] string The url to query.
options.controller string The keystore's controller.
options.referenceId string The keystore's reference ID.

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.

Security Considerations

There are a number of security considerations that implementers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

Accessibility Considerations

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

Internationalization Considerations

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.