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.


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:

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:



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.

Data Model

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.