This specification describes a set of cryptographic suites created in 2020. The suites define representations and interfaces that support digital signatures and encryption.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

Introduction

"We shape our tools, and thereafter our tools shape us."
-- Marshall McLuhan

These set of suites are designed to addresses the failures of previous specifications and the inability of developers to follow simple instructions.

The language we have used to describe cryptography has created security issues....

More philosphical language goes here....

Terminology

This section describes the vocabulary used by this suite. Some vocabulary is used to describe private data, which must not be made public.

key
Generic term refering to cryptographic material. There are symmetric and assymmetric keys.
symmetric key
Cryptrographic material that is used to produce encryptions and message authentication codes. Sometimes referred to as a secret key.
assymmetric key
Ambigious term for cryptrographic material that is used to produce and verify signatures and derive information used to produce symmetric keys. Used to refer to both the public and private components of a key pair.
key pair
Generic term used to describe key materials which are associated in some way. Commonly used to refer to assymetric cryptographic key material, because they always come in pairs.
private key
The private component of an assymetric key pair, which is commonly used to produce digital signatures and derive bits used to produce symmetric keys.
public key
The public component of an assymetric key pair, which is commonly used to verify digital signatures and derive bits used to produce symmetric keys.
signature suite
A specified set of cryptographic primitives typically consisting of a canonicalization algorithm, a message digest algorithm, and a signature algorithm that are bundled together by cryptographers for developers for the purposes of safety and convenience.
canonicalization algorithm
An algorithm that takes an input document that has more than one possible representation and always transforms it into a canonical form. This process is sometimes also called normalization.
canonical form
The output of applying a canonicalization algorithm to an input document.
message digest algorithm
An algorithm that takes a message and produces a cryptographic output message that is often many orders of magnitude smaller than the input message. These algorithms are often 1) very fast, 2) non-reversible, 3) cause the output to change significantly when even one bit of the input message changes, and 4) make it infeasible to find two different inputs for the same output.
message digest
The result of the application of the message digest algorithm to a message
signature algorithm
An algorithm that takes an input message and produces an output value where the receiver of the message can mathematically verify that the message has not been modified in transit and came from someone possessing a particular secret.
encryption algorithm
An algorithm that takes an input message and produces an output value where only the receiver of the output can recover the original message and confirm that the message has not been modified in transit and came from someone possessing a particular secret.
message
The input to a cryptographic operation, such as signing, hashing or encrypting.
id
Used to identify a node in a graph. Dereferencing an id produces a representation of a node. See json-ld.org.
type
Used to specify the type of a node in a graph. See json-ld.org.
base58btc
Used to encode public and private key components as publicKeyBase58 and privateKeyBase58. See draft-multiformats-multibase.
jwk
Used to encode public and private key components as publicKeyJwk and privateKeyJwk. See rfc7517.
verification method
A verification method is used to verify a linked data proof. See did core.
proof type
The type of a linked data proof. See linked data proofs.
verification method type
A set of parameters required to independently verify the proof, such as an identifier for a public/private key pair that would be used in the proof.. See linked data proof verification-method.
test vectors
A set of inputs and expected outputs used to verify the defined functions of a software specification. See rfc7520.
cryptographic agility
"Crypto-agility (cryptographic agility) is a practice paradigm in designing information security systems that encourages support of rapid adaptations of new cryptographic primitives and algorithms without making significant changes to the system's infrastructure." -- wikipedia

Information Model

The id property of a key pair identifies a node in an information graph which contains both public and private information.

The type property of a key pair specifies different representations of a node in an information graph.

It is RECOMMENDED to use the public key or a deterministic transformation of a represenation of it for the purpose of identifying a key pair via id.

Linked data proofs are nodes in the same information graph as key pairs.

When a linked data proof is produced, an edge is created between the key pair used to produce the proof, and the proof. This edge is identified in the proof by the property verificationMethod.

The same key pair MAY be used to create multiple different proof types, by applying different algorithms.

For example, a type of Ed25519VerificationKey2020 might be used in the verification method representation of the public information associated with a key pair, however type of Ed25519VerificationKey2018 might also be used for the same graph node. Subsequently, a proof of type Ed25519Signature2020, and one of type Ed25519Signature2018 might be produced and linked to the same key pair.

A key pair and a verification method are different represenations of the same node in a graph. Different representations of a node leverage different type property values to express which subset of the information graph is used by the represenation.

In simpler language, type is used to distinguish between public and private represenations of a key pair.

The graph node attribute type is also used to express the intended use of a cryptographic key. For example Ed25519VerificationKey2018 for signature verification, and X25519KeyAgreementKey2019 for key agreement. However, both represenations can be used to describe the same node in an information graph. For more information see DID Key Method Spec.

A verification method use is something like "signing" or "encryption", see WebCrypto KeyUsage.

A verification method purpose is something like "authentication", or "capabilityInvocation", see DID Core Verification Relationships.

It is RECOMMENDED that linked data proof suites, explictly state if the type of the verification method is limited for a single use and or a single algorithm.

It is NOT RECOMMENDED that the same cryptographic key material be used for multiple purposes.

It is NOT RECOMMENDED that the same cryptographic key material be used with different algorithms for the same purpose.

Interfaces

This section describes interfaces used by linked data proof suites. Web IDL and JSON-LD are used to describe a data model and interfaces for representations.

Key Pair

A linked data key pair describes an assymetric crypographic key, which supports digital signature creation via a private key, public key derivation from a private key, signature verification using the public key, and secret derivation us both public and private key components.

Anyone who has a private key, can derive the public key, but the opposite is not true. This is the foundation on which digital signatures and key agreement are built, and is the reason that private keys must remain private.

The type of a linked data key pair allows for control over cryptographic agility. A key pair can be restricted to a limited set of cryptographic algorithms by defining a new type and documenting the restrictions in a signature suite.

If support for cryptographic agility is desired, a signature suite can rely on an external registry for cryptographic key and algorithms representations and guidance. For example, a suite might reuse the vocabulary defined by IANA JOSE.

The private component of assymetric cryptographic key pairs MUST be protected from accidental or intentional disclosure.

Linked data key pair representations MAY use base58btc or jwk to represent public and private components of assymetric cryptographic key pairs. 

         
          [Exposed=SecureContext]
          interface KeyPair {
            attribute ByteString id;
            attribute ByteString type;
            attribute ByteString controller;
            attribute Uint8Array publicKey;
            attribute Uint8Array privateKey;
            Promise<Uint8Array> sign(Uint8Array message);
            Promise<boolean> verify(Uint8Array signature);
            Promise<Uint8Array> deriveBits(Uint8Array remotePublicKey);
            LinkedDataKeyPair toLinkedDataKeyPair();
            LinkedDataVerificationMethod toVerificationMethod();
          };

          [Exposed=SecureContext]
          interface LinkedDataKeyPair {
            attribute ByteString id;
            attribute ByteString type;
            attribute ByteString controller;
            attribute ByteString publicKeyBase58;
            attribute ByteString privateKeyBase58;
          };

It is strongly RECOMMENDED that hardware or software isolation be used to disable read access to the value of privateKey after key pair generation. See the Web Crypto API Crypto Key Interface member extractable.

It is strongly RECOMMENDED that representations of linked data key pairs be encrypted in transit and at rest.

It is strongly RECOMMENDED that concrete implementations of LinkedDataKeyPair mark all attributes private or protected, and that toVerificationMethod() be used to produce a public key verification method suitable for signature verification and key agreement.

Here are a few non normative examples of key pairs:

          {
            "id": "#z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
            "type": "Ed25519LinkedDataKeyPair2020",
            "controller": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
            "publicKeyBase58": "dbDmZLTWuEYYZNHFLKLoRkEX4sZykkSLNQLXvMUyMB1",
            "privateKeyBase58": "47QbyJEDqmHTzsdg8xzqXD8gqKuLufYRrKWTmB7eAaWHG2EAsQ2GUyqRqWWYT15dGuag52Sf3j4hs2mu7w52mgps"
          }
          
          {
            "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
            "type": "JsonWebKey2020",
            "controller": "did:example:123",
            "publicKeyJwk": {
              "kty": "OKP",
              "crv": "Ed25519",
              "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ"
            },
            "privateKeyJwk": {
              "kty": "OKP",
              "crv": "Ed25519",
              "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
              "d": "tP7VWE16yMQWUO2G250yvoevfbfxY25GjHglTP3ZOyU"
            }
          }

Verification Method

A verification method is used to verify linked data proofs.

When a proof is a form of digitial signature, a verification method is a representation of a public key.

The type of a verification method allows for control over cryptographic agility. A public key can be restricted to a limited set of cryptographic algorithms by defining a new type and documenting the restrictions in a signature suite.

If support for cryptographic agility is desired, a signature suite can rely on an external registry for cryptographic key and algorithms representations and guidance. For example, a suite might reuse the vocabulary defined by IANA JOSE.

A linked data verification method representation MAY use base58btc or jwk to represent public and private components of assymetric cryptographic key pairs. 

            [Exposed=Window]
            interface PublicKey {
              attribute ByteString id;
              attribute ByteString type;
              attribute ByteString controller;
              attribute Uint8Array publicKey;
              Promise<boolean> verify(Uint8Array signature);
            };

            [Exposed=Window]
            interface LinkedDataVerificationMethod {
              attribute ByteString id;
              attribute ByteString type;
              attribute ByteString controller;
              attribute ByteString publicKeyBase58;
            };

It is RECOMMENDED that type to used to restrict the verification method to a specific cryptographic key type and signature / proof algorithm.

PII or other information that might be used for correlation should be excluded from the id and public key representation member of verification methods.

A linked data verification method representation MAY use base58btc or jwk to represent public and private components of assymetric cryptographic key pairs.

Here are a few non normative examples of verification methods: 

            {
              "id": "#z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
              "type": "Ed25519VerificationMethod2020",
              "controller": "did:example:123",
              "publicKeyBase58": "dbDmZLTWuEYYZNHFLKLoRkEX4sZykkSLNQLXvMUyMB1"
            }
        
 
          {
            "id": "#key-0",
            "type": "JsonWebKey2020",
            "controller": "did:example:123",
            "publicKeyJwk": {
              "kty": "OKP",
              "crv": "Ed25519",
              "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ"
            }
          }

Suite Definition

A linked data proof suite MUST define at least 1 verification method type type.

A linked data proof suite MUST define at least 1 proof type type.

A linked data proof suite MUST provide at least 1 JSON-LD represenation of a key pair associated with every verification method type it defines.

A linked data proof suite MUST define the relationship between each defined verification method type and proof type.

A linked data proof suite MUST provide test vectors.

A linked data proof suite MAY support cryptographic agility.

A linked data proof suite MAY support verification method types defined by other signature suites.

Test Vectors

This section describes test data used to ensure spec conformance and interoperability.

Relative URIs may be used for the value of id, with the use of @base. See json-ld.org. 

        {
          "id": "#z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
          "type": "Ed25519LinkedDataKeyPair2020",
          "controller": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
          "publicKeyBase58": "dbDmZLTWuEYYZNHFLKLoRkEX4sZykkSLNQLXvMUyMB1",
          "privateKeyBase58": "47QbyJEDqmHTzsdg8xzqXD8gqKuLufYRrKWTmB7eAaWHG2EAsQ2GUyqRqWWYT15dGuag52Sf3j4hs2mu7w52mgps"
        } 
      
        {
          "id": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP#z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
          "type": "Ed25519VerificationKey2020",
          "controller": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
          "publicKeyBase58": "dbDmZLTWuEYYZNHFLKLoRkEX4sZykkSLNQLXvMUyMB1"
        }        
      
        {
          "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
          ],
          "id": "http://example.gov/credentials/3732",
          "type": ["VerifiableCredential", "UniversityDegreeCredential"],
          "issuer": {
            "id": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
          },
          "issuanceDate": "2020-03-10T04:24:12.164Z",
          "credentialSubject": {
            "id": "did:example:456",
            "degree": {
              "type": "BachelorDegree",
              "name": "Bachelor of Science and Arts"
            }
          },
          "proof": {
            "type": "Ed25519Signature2020",
            "created": "2020-03-10T04:24:12.164Z",
            "signatureValue": "4ohH8BvL3fTjNhJJC8bSr7ap6a5C6rHEWersgK6jsSCEWev6mYYNKS2SiprssYmw1a4TE4rMyP6ah6LdoWNsmiNV",
            "proofPurpose": "assertionMethod",
            "verificationMethod": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP#z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
          }
        }
TODO: This specification has no consensus, and should note be relied on by anyone.

Security Considerations

The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.

If a private key is disclosed, digital signatures associated with the public key cannot be trusted. Mechanisms for revoking public keys, or mitigating private key compromisse are out of scope for this spec.

TODO: We need to add a complete list of security considerations.