JSContact Cryptographic Key Extensions

1.1. Link Keys to Services

[RFC9553] allows a card to specify online services and cryptographic keys but does not provide a means of specifying which key is to be used for which purpose. This results in ambiguity with key formats used to support a wide range of applications, a key presented in OpenPGP encoding may be used to sign email, sign a repository commit, encrypt a file system or used for many other purposes. For example, a user can specify the separate OpenPGP keys they use for email and signing commits to their source code repository but does not allow the user to specify which key is to be used for which.¶

Best practices for use of cryptographic applications encourage the use of different keys for different cryptographic functions (encryption, signing, authentication), different application protocols and different uses. Without the ability to specify which key is to be used for which purpose, an attacker that has compromised a weakly protected key intended for low consequence purposes (e.g. signing development builds) for a high consequence purpose (e.g. signing production builds and authorizing financial transactions.)¶

The EmailAddress object and OnlineService object are extended to add a keys property which MAY be used to specify the key identifiers of the related keys.¶

For example, Alice has many OpenPGP keys but only one that she uses with her email address alice@example.com:¶

{
  "@type":"Card",
  ...
    ...
  "emails" : {
    "email1" : {
        "@type": "EmailAddress",
        "address": "alice@example.com",
        "cryptoKeyIds": {
          "emailKey1": "bundle",
          "emailKey3": "sign",
          "emailKey4": "encrypt"}}
    },
  "cryptoKeys" : {
    "emailKey1" : {
        "@type": "CryptoKey",
        "uri": "data:application/pgp-keys;base64,9jhpthtFpOVS0FWXsg
5rF3W2-vE.."}
    ...
    }
  }

1.2. Enhanced specification of cryptographic credentials

The Card object's cryptoKeysSP 800-57 Part 1 Revision 5 property allows a card to specify cryptographic credentials as URIs but not their intended uses. A data URI containing an X.509v3 certificate might be intended for use with S/MIME, for code signing or some entirely unrelated purpose. Best design practice (see e.g. section 5.2) encourages the use of common cryptographic infrastructures to support a wide range of applications but best use practices encourage limiting the use of particular cryptographic keys to a single application.¶

The use of the JSON Web Key (JWK) format provides a much richer format for describing cryptographic keys and their properties than a URI and a media type.¶

For example, Alice uses SSH to securely access resources in her network. In accordance with best security practices, she create a separate SSH keypair for each of the devices she uses as a client terminal. Accordingly, her contact has an onlineService entry that describes this use of the SSH protocol that specifies the keys to be used with SSH and a separate JsonWebKeySet entry for each key specifying the key parameters:¶

{
  "@type":"Card",
  ...
    ...
  "onlineServices" : {
    ...
    "ssh1" : {
        "@type": "OnlineService",
        "service": "ssh",
        "cryptoKeyIds": {
          "sshKey1": "sign",
          "sshKey2": "sign",
          "sshKey3": "sign"}}
    ...
    },
  "cryptoKeys" : {
    ...
    "sshKey1" : {
        "@type": "JsonWebKeySet",
        "jsonWebKeys": [{
            "kty": "OKP",
            "kid": "MBWQ-TY2X-SFBR-DWYL-LURE-GHD4-CCP3",
            "crv": "Ed25519",
            "x": "5tKZn7_cQYNz7SU65Vqm4JplTToA4kIIwyX_vWT76ZY"}
          ]}
    ...
    }
  }

1.3. Groups

It is often convenient to organize related email addresses and online services used for a common purpose into groups.¶

For example, Alice might create a ServiceGroup bundling the set of cryptographic keys she uses for code development. This would allow her to create separate sets of keys for different clients she works with and to distinguish the set of keys used for development purposes from those she uses for production use.¶

{
  "@type":"Card",
  ...
  "updates" : {
    "group1" : {
        "@type": "ServiceGroup",
        "members": {
          "email1": true,
          "git1": true,
          "ssh1": true}}
    },
  "serviceGroups" : {
    "group1" : {
        "@type": "ServiceGroup",
        "members": {
          "email1": true,
          "git1": true,
          "ssh1": true}}
    }
  "emails" : {
    "email1" : {
        "@type": "EmailAddress",
        "address": "alice@example.com",
        "cryptoKeyIds": {
          "emailKey1": "bundle",
          "emailKey3": "sign",
          "emailKey4": "encrypt"}}
    },
  "onlineServices" : {
    "git1" : {
        "@type": "OnlineService",
        "service": "commit",
        "user": "alice.example.com",
        "cryptoKeyIds": {
          "gitKey1": "sign"}}
    "ssh1" : {
        "@type": "OnlineService",
        "service": "ssh",
        "cryptoKeyIds": {
          "sshKey1": "sign",
          "sshKey2": "sign",
          "sshKey3": "sign"}}
    ...
    },
    ...
  }

1.4. Authentication

The use of an authenticated exchange mechanism such as [RFC7515] or [draft-hallambaker-earl] allows a JSContact card to be used as an aggregate credential whose contents are used to automatically configure cryptographic applications that use the credentials contained therein.¶

Instead of having to configure every server that Alice might want to access using her SSH keys, Alice can add her keys to her JSContact card and run a script to create the necessary access control entries on each server.¶

The power of this approach is further increased if an authenticated contact update mechanism is used. In this case, updates can be propagated to the target devices automatically by either polling or through a push update mechanism.¶

1.5. Authenticated Updates

The authenticated locator mechanisms described above are intended to be used to establish a 'first contact' between the parties preserving the maximum possible degree of trust from the context.¶

Once the initial contact exchange has been achieved, the credentials exchanged in that first contact SHOULD be used to obtain and authenticate future updates.¶

Contact cards that support updates MUST include a uid property. Updates to contact cards MUST specify the same uid value.¶

The updates property provides an open framework for describing the update mechanisms supported. The mechanisms provided to update the contact MAY be different from the mechanism originally used to distribute it.¶

For example, Alice publishes her current contact card by means of a DNS TXT record containing an EARL [draft-hallambaker-earl] and a QR code encoding the same EARL on the business card she presents when meeting people in person. Applications MAY update the card by polling the URI specified in the updates entry and verifying the signature on the plaintext enveloped data returned.¶

{
  "@type":"Card",
  ...
    ...
  "cryptoKeys" : {
    ...
    "updateKey1" : {
        "@type": "JsonWebKeySet",
        "jsonWebKeys": [{
            "kty": "OKP",
            "kid": "MDMY-XH52-PLPK-H7DZ-WAXW-LDNS-5I7R",
            "crv": "Ed448",
            "x": "QKvMwR_qwWUJoWEeFMb6SlVxnA8MUa8p_diWxgORiVxjPwSqF
vgKvoCZBpRqMx5-u8u5d6g6auIA"}
          ]}
    }
  }

Since it is easier to update information on a Web site than in DNS or on a business card, it is likely that some users will prefer to use these mechanisms to distribute pro-forma contact information consisting of basic contact information and update information alone. Therefore, contact applications SHOULD attempt to update contact cards providing update information on receipt.¶

Retrieving a plaintext signed contact assertion via HTTPS provides a simple but limited update mechanism providing end-to-end integrity but not confidentiality. While the contact information is delivered over an encrypted transport, the contact card is stored unencrypted on the server which may not be acceptable in certain applications. Another limitation is that the relying party is required to poll the contact service for updates. A more sophisticated updates protocol might provide update notifications. Such considerations are outside the scope of this document and left for future work.¶

[Remark: Addition of a JOSE based encryption scheme would be straightforward. This would require extension of the envelope specification and to pass a decryption key to the parties the contact is passed to.]¶

A contact card MAY specify multiple update mechanisms providing a degree of resilience in the case that a publication service stops providing service.¶

For example, Alice might choose three independent contact directory services publishing her contact information on all three ensuring that the people she has shared her contact information with can remain in contact years or even decades after the initial contact exchange.¶

2.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].¶

2.2. Defined Terms

TBS¶

2.3. Related Specifications

JSContact: A JSON Representation of Contact Data [RFC9553].

Describes the format used for contact data interchange.¶

JSON Web Key (JWK) [RFC7517].

Describes publishing public keys in JSON format.¶

Encrypted Authenticated Resource Locator [draft-hallambaker-earl].

Describes a URI form that provides means of retrieving, decrypting and authenticating an associated ciphertext.¶

2.4. Implementation Status

Reference code under the MIT Open-Source license has been developed to demonstrate all the features described in this document.¶

3.1. Additional Card Properties

The following properties are added to the Card object specified in [RFC9553].¶

"updates": {
  "update1": {
    "@type": "Update",
    "uri": "https://contacts.example.com/",
    "cryptoKeyIds": {
      "updateKey1": "sign"}}}

"serviceGroups": {
  "group1": {
    "@type": "ServiceGroup",
    "members": {
      "email1": true,
      "git1": true,
      "ssh1": true}}}

3.2. Extension to the EmailAddress Object

The EmailAddress object specified in [RFC9553] is extended to add the specified property.¶

"cryptoKeyIds": {
  "emailKey1": "bundle",
  "emailKey3": "sign",
  "emailKey4": "encrypt"}

3.3. Extension to the OnlineService Object

The OnlineService object specified in [RFC9553] is extended to add the specified property.¶

3.4. New Object JsonWebKeySet

The JsonWebKeySet object is added to the Card object with the following properties:¶

4.1. S/MIME

S/MIME (Secure/Multipurpose Internet Mail Extensions) provides a consistent way to send and receive secure MIME data over SMTP and other messaging transports.¶

Certificates issued for use with S/MIME are commonly used for other purposes, for example TLS client authentication. For the purposes of this discussion, our focus is strictly limited to the use of the certificate for messaging.¶

If the messaging protocol is SMTP, the service is specified as an EmailAddress, otherwise the OnlineService structure is used with the appropriate service specifier.¶

Strawman proposal:¶

• Use a single JWK entry with an x5c to specify the encryption key cert, signature key cert and cert path.¶
• Specify the JWK in the keys section of the corresponding EmailAddress or OnlineService with the key identifier of the corresponding JWK and the 'smime' use.¶

{
  "@type":"Card",
  ...
    ...
  "cryptoKeys" : {
    ...
    "emailKey3" : {
        "@type": "CryptoKey",
        "uri": "data:application/pkix-cert;base64,VQSUcf253buwsfIgF
UyqNeQ1Ky4.."}
    "emailKey4" : {
        "@type": "CryptoKey",
        "uri": "data:application/pkix-cert;base64,du0OqLzpeCHLXXJD-
HUpt1nN36o.."}
    ...
    }
  }

4.2. OpenPGP

OpenPGP provides encryption with public key or symmetric cryptographic algorithms, digital signatures, compression, and key management.¶

OpenPGP key management is commonly used for many purposes including signing repository commits. For the purposes of this section, our focus is strictly limited to the use of keys for messaging.¶

If the messaging protocol is SMTP, the service is specified as an EmailAddress, otherwise the OnlineService structure is used with the appropriate service specifier.¶

Strawman proposal:¶

• User specifies their OpenPGP primary key as an OnlineService with service type 'openpgp'. This is also the place any key server information would be placed.¶
• The first key in the keys entry of the service is the key identifier of the primary key¶
• The sub keys are the following keys¶
• The corresponding key entries are of type JsonWebKey¶
• The key data is specified as a binary data property¶
• Other services specify the subkeys that they use.¶

{
  "@type":"Card",
  ...
    ...
  "cryptoKeys" : {
    "emailKey1" : {
        "@type": "CryptoKey",
        "uri": "data:application/pgp-keys;base64,9jhpthtFpOVS0FWXsg
5rF3W2-vE.."}
    ...
    }
  }

4.3. SSH

The SSH protocol used for remote shell and file system access supports authentication by means of either passwords or public keys. The set of public keys authorized to allow access to a device is specified by means of:¶

• A raw public key¶
• An SSH user certificate as specified in [draft-ietf-sshm-cert].¶
• A PKIX certificate as specified in [RFC6187].¶

While use of certificates offers clear management advantages and SSH certificates are widely supported in applications and libraries, most users only use raw keys. The JsonWebKey object provides the most convenient means of encoding a raw key.¶

For example, Alice defines separate raw public keys for each of her two user devices and has separately created an SSH user certificate for one of the keys:¶

{
  "@type":"Card",
  ...
    ...
  "onlineServices" : {
    ...
    "ssh1" : {
        "@type": "OnlineService",
        "service": "ssh",
        "cryptoKeyIds": {
          "sshKey1": "sign",
          "sshKey2": "sign",
          "sshKey3": "sign"}}
    ...
    },
  "cryptoKeys" : {
    ...
    "sshKey1" : {
        "@type": "JsonWebKeySet",
        "jsonWebKeys": [{
            "kty": "OKP",
            "kid": "MBWQ-TY2X-SFBR-DWYL-LURE-GHD4-CCP3",
            "crv": "Ed25519",
            "x": "5tKZn7_cQYNz7SU65Vqm4JplTToA4kIIwyX_vWT76ZY"}
          ]}
    "sshKey2" : {
        "@type": "JsonWebKeySet",
        "jsonWebKeys": [{
            "kty": "OKP",
            "kid": "MAAF-677S-5LR7-LZC5-QSZV-EDTW-LYVV",
            "crv": "Ed25519",
            "x": "uWTosF21Jr2cC_JBdM9woCvUHUBFyOA9kZ-ealN2b4Q"}
          ]}
    "sshKey3" : {
        "@type": "CryptoKey",
        "uri": "data:application/ssh-TBS;base64,G1gwyQEpuvag5WQysXs
WjY4qD64.."}
    ...
    }
  }

[Remark: The SSH certificate draft is nearing completion, comments have been submitted on how to bind SSH certificates in JOSE JWK and suggesting creation of a media type.]¶

4.4. Code Signing

Code signing is an important security control both in development and production environments. Most modern executable code formats and many scripting languages support one or more code signing mechanisms. While most signature mechanisms support use of PKIX certificate credentials, OpenPGP keys and even raw keys are used and sometimes required.¶

It is highly desirable for code signing keys used to sign published releases of code be kept separate from those used to sign development builds. In addition, many software distribution channels require the use of credentials issued by the channel operator. Consequently, the number of code signing keys used by a developer may be very large.¶

This use is specified by means of an OnlineService with the service type 'code' with key entries for the set of authorized signing keys.¶

Alice has a single code signing key with a PKIX credential specified in her JsContact card:¶

{
  "@type":"Card",
  ...
    ...
  "onlineServices" : {
    ...
    "code1" : {
        "@type": "OnlineService",
        "service": "code",
        "cryptoKeyIds": {
          "codeSign1": "sign"}}
    "code2" : {
        "@type": "OnlineService",
        "service": "code",
        "cryptoKeyIds": {
          "codeSign1": "sign"}}
    },
  "cryptoKeys" : {
    ...
    "codeSign1" : {
        "@type": "CryptoKey",
        "uri": "data:application/pkix-cert;base64,GvDh6w1P9K3aRa_tH
TxEoF5ya3I.."}
    "codeSign2" : {
        "@type": "CryptoKey",
        "uri": "data:application/pkix-cert;base64,mMT2044jV8LOoWy4u
plhZkQvG1I.."}
    ...
    }
  }

4.5. Commit Signing

Most modern source code repository systems support application of signatures to commit operations. While OpenPGP key management is commonly used for this purpose, the popular git source code repository also supports use of raw keys.¶

This use is specified by means of an OnlineService with the service type 'commit' with key entries for the set of authorized signing keys.¶

{
  "@type":"Card",
  ...
    ...
  "onlineServices" : {
    "git1" : {
        "@type": "OnlineService",
        "service": "commit",
        "user": "alice.example.com",
        "cryptoKeyIds": {
          "gitKey1": "sign"}}
    ...
    },
  "cryptoKeys" : {
    ...
    "gitKey1" : {
        "@type": "CryptoKey",
        "uri": "data:application/pgp-keys;base64,EBIHlPDVEY2rshD2rO
_JQNamX0s.."}
    ...
    }
  }