JSContact Extensions

This document defines extensions to the JSContact data model for contact card data to provide improved support for describing cryptographic credentials to be used with applications and services and to provide support for authenticated updates to a contact card. The key design considerations for these extensions are as follows: Maintain compatibility with the approach in the base specification. Avoiding unexpected behavior from legacy applications. Allow cryptographic credentials to be specified as JSON Web Key Sets . Provide more descriptive information for use of cryptographic credentials, in particular specifying which key is to be used with which information service. Allow specification of groups of related email addresses and information services. In addition, specific guidance is provided on specifying credentials for use with S/MIME, OpenPGP, SSH and Code Signing.

JSContact 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 is a particular problem with key formats used to support a wide range of applications, an OpenPGP key may be used to sign email or sign a repository commit. 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 an email address entry that has keys for signing and encrypting emails using S/MIME and OpenPGP. { "EmailAddress":{ "@type":"EmailAddress", "address":"alice@example.com", "label":"Main email", "keys":{ "MBSB-DLNX-237N-XZZK-F3CF-KZUE-2MEQ":"smime", "MATY-GK2S-YQ25-W4TI-TNQC-4LSK-CEZZ":"smime", "MCAL-TRSZ-2T5M-C35H-3LVD-SXLQ-FU2X":"openpgp", "MBCB-MCIP-FFUD-BEFU-AOZB-CB3P-5F2S":"openpgp"}}}

The JSContact cryptokeys 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 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, Bob is trying to send an encrypted email to Alice, her contact card lists two keys but only one is an encryption key with the JWK use parameter enc: ["MBSB-DLNX-237N-XZZK-F3CF-KZUE-2MEQ" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"so4Ho0g7DX6U6GMXRlIoU_lwzgQboY1KVMLjbZAa84_LZ12Zhk9e0rjB lQsiX0XFuA5AWUuhJ3WiwzAP3A8A11U9zMzQcooxquvYTyyoQvmxxe3P-E4NuuK7l9 5RPe_eaxzFnhiP_ppW9xziLjZWjxgyXUTs5HjO1ItXA8EZktEIdoZr42cMDt8BgVZk Tkp_GaX6ylkGsynzmugAHJhrfw_Tv1YUSkqG_-jxJ4_m92AfiQiIiYz5wWRd3na8Zm -UFAaCXJVMVQjk4EZg2ikrUhVzraYxDUPndP1icX7U2cYlw42YonL7pIlD-FTiO79o pO-Wgylq9qbrrWo8zJh0BQ", "e":"AQAB"} ]}, "MATY-GK2S-YQ25-W4TI-TNQC-4LSK-CEZZ" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"qBuQYvxpVdU4JBdhPw2DkMgWYWRSg1gvaMIC2y2N0fMX_mrRoaozVjp2 w_zSo268rD-9IHSWpHBHQOKSx4kq0RvrLqX6tAWloprnYtzTA1cNmmRLLnZ1RBFLbS Zy21wSxe_pz_lLjqtYrPo2wwP0oqoPniN6SVD1Jp8Us4Yid9N2WIr2L4Aa1FXeR2jx LzrY9vtmj6OVdVzG1nKIMVRZmlcmH92nbb4tfJKGkllmpUHmKhOCQUa9j8GkCaIC_5 IglxHLGKC40q5T6vBfEyj8n3LcCyszwnWR55B7zTBgbbuQatHHS7PtLa3_tsUYFGH6 _WDAAzwA9E-4rLOnlH8zgQ", "e":"AQAB"} ]} ... ]

It is often convenient to organize related email addresses and online services used for a common purpose into groups. For example, Alice might create separate sets of SSH, repository commit signing and code signing keys for code development: { "Group":{ "@type":"Group", "label":"Developer Key Set", "members":{ "MACQ-Z2ZI-TIPR-OA4J-P7M3-NUS4-V5KI":true, "MBEY-C3DZ-TBJU-44QL-GS5G-V7W4-3ERG":true, "MAQ7-ZP2C-EHGC-DETY-XYB4-UB2J-3CTG":true, "MBFN-PUI6-NMHJ-3DPO-SJ5H-GAZJ-NOAV":true, "MBNZ-X4KY-NSPL-BMIT-YOKJ-HUA4-F26K":true, "MC4Q-CHK5-CJBV-FWPU-CDBD-4AMZ-ZXJH":true, "MALZ-A35Y-JMVB-DFFS-4LN4-TMQ4-B52Z":true}}} Each group identifier is specified as an online service: ["MACQ-Z2ZI-TIPR-OA4J-P7M3-NUS4-V5KI" : { "@type":"OnlineService", "service":"ssh", "keys":{ "MBMU-UB7V-ER7F-SAKS-7EFZ-G66A-2C2I":"ssh"}}, "MBEY-C3DZ-TBJU-44QL-GS5G-V7W4-3ERG" : { "@type":"OnlineService", "service":"commit", "label":"commit", "keys":{ "MDAM-YKVI-RXGL-D2NN-EXGQ-PCWY-SNWP":"credential"}}, "MAQ7-ZP2C-EHGC-DETY-XYB4-UB2J-3CTG" : { "@type":"OnlineService", "service":"code", "contexts":{ "Pkix":true}, "label":"code Pkix", "keys":{ "MA75-ZNSK-WDRZ-Z3GV-2I2Y-3ZDH-RTCB":"credential"}} ... ]

The features described in this document are designed to support but not require the exchange of JSContact data by means of an Encrypted Authenticated Resource Locator (EARL) . An EARL is a URI form that contains a multi-purpose key that MAY be used to locate, decrypt and authenticate an associated ciphertext package. For example, Alice's JSContact information might be retrievable from the EARL: jscontact://example.com/ekth-kwsy-atfy-ipeo-fbj2-quat-7erd Alice might publish her EARL on her business card either as text or as a machine readable code such as a QR code. Alternatively, Alice might publish the information as a prefixed DNS TXT record in the domain she uses as her DNS handle: _jscontact.alice.example.com TXT "jscontact=jscontact://example.com/e kth-kwsy-atfy-ipeo-fbj2-quat-7erd"

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 MAY be used to obtain and authenticate future updates. The updates property provides an open framework for describing the update mechanisms supported. For example, Alice publishes her current contact card by means of a DNS TXT record containing an EARL locating a ciphertext package whose plaintext payload and metadata are signed under the specified key: { "Update":{ "@type":"Update", "keys":{ "MDCN-UUGT-T3ME-MRE4-AYOY-PSZP-7BIM":"sign"}}} ["MDCN-UUGT-T3ME-MRE4-AYOY-PSZP-7BIM" : { "@type":"Jwks", "jwk":[{ "kty":"OKP", "kid":"MDCN-UUGT-T3ME-MRE4-AYOY-PSZP-7BIM", "crv":"Ed448", "x":"HG2qquWqdzMO3PxoRY8QZQ5k1xXn_tUGQudVCDlZgGX0ny59uSQVHvwm _2-jw8S1Y8vIP8lTe-4A"} ]}]

This section presents the related specifications and standards, the terms that are used as terms of art within the documents and the terms used as requirements language.

This is an informational document and does not contain any normative language.

JSContact: A JSON Representation of Contact Data .: Describes the format used for contact data interchange.
Encrypted Authenticated Resource Locator .: Describes a URI form that provides means of retrieving, decrypting and authenticating an associated ciphertext.

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

updates: Id[Update] (optional). The update mechanisms that MAY be used to provide Card updates. An Update object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions: The @type property value MUST be "Calendar", if set keys: Id[Boolean] (optional). The identifiers used within this contact card to identify keys to be used with this update mechanism.

This section defines a means of grouping contact properties and extends the contact properties specified in .

groups: Id[OnlineService] (optional). The online services that are associated with the entity represented by the Card. This can be messaging services, social media profiles, and other @type: String. The JSContact type of the object. The value MUST be "Group", if set. contexts: String[Boolean] (optional). The contexts in which to use the service Members Id[Boolean] (required) The identifiers used within this contact card to identify email addresses or online services belonging to this group. label: String (optional). A custom label for the value.

The EmailAddress object is extended to add the following property: keys: Id[Boolean] (optional). The identifiers used within this contact card to identify keys to be used with this email address.

The OnlineService object is extended to add the following property: keys: Id[Boolean] (optional). The identifiers used within this contact card to identify keys to be used with this email address.

This section defines additional properties for digital resources associated with the entity represented by the Card.

jwkss: Id[Jwks] (optional). The cryptographic resources such as public keys and certificates associated with the entity represented by the Card. A Jwks object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions: The @type property value MUST be " Jwks ", if set. data:JWK[] Where JWK is a JSON Web Key as specified in .

This section provides guidance on how to encode cryptographic keys for specific applications. This section is intentionally left unfinished to solicit input from the relevant expert groups.

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.

["MBSB-DLNX-237N-XZZK-F3CF-KZUE-2MEQ" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"so4Ho0g7DX6U6GMXRlIoU_lwzgQboY1KVMLjbZAa84_LZ12Zhk9e0rjB lQsiX0XFuA5AWUuhJ3WiwzAP3A8A11U9zMzQcooxquvYTyyoQvmxxe3P-E4NuuK7l9 5RPe_eaxzFnhiP_ppW9xziLjZWjxgyXUTs5HjO1ItXA8EZktEIdoZr42cMDt8BgVZk Tkp_GaX6ylkGsynzmugAHJhrfw_Tv1YUSkqG_-jxJ4_m92AfiQiIiYz5wWRd3na8Zm -UFAaCXJVMVQjk4EZg2ikrUhVzraYxDUPndP1icX7U2cYlw42YonL7pIlD-FTiO79o pO-Wgylq9qbrrWo8zJh0BQ", "e":"AQAB"} ]}, "MATY-GK2S-YQ25-W4TI-TNQC-4LSK-CEZZ" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"qBuQYvxpVdU4JBdhPw2DkMgWYWRSg1gvaMIC2y2N0fMX_mrRoaozVjp2 w_zSo268rD-9IHSWpHBHQOKSx4kq0RvrLqX6tAWloprnYtzTA1cNmmRLLnZ1RBFLbS Zy21wSxe_pz_lLjqtYrPo2wwP0oqoPniN6SVD1Jp8Us4Yid9N2WIr2L4Aa1FXeR2jx LzrY9vtmj6OVdVzG1nKIMVRZmlcmH92nbb4tfJKGkllmpUHmKhOCQUa9j8GkCaIC_5 IglxHLGKC40q5T6vBfEyj8n3LcCyszwnWR55B7zTBgbbuQatHHS7PtLa3_tsUYFGH6 _WDAAzwA9E-4rLOnlH8zgQ", "e":"AQAB"} ]} ... ]

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.

["MCAL-TRSZ-2T5M-C35H-3LVD-SXLQ-FU2X" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"8YdYROuUdv2vn765E6i9vZGoUDhxhsg_Q0VYFhH9SC4JnmRBQVeMljbV qiJBKvkjC6HbI3T6yvsz-fMgsq__un_q9Qr5fNSPul5F8ZYxOaI3YyJUdEXv0MscX2 Yhj6679frsQdOQ-IuUeXZjwi2fTQMi3pViiD1QiJ9-a6IjQkZ7WP1vTqDaB__b3Tve HNyz0dfPmnS8BgsIV5uL3osXO7BQdzPSP5FGVpjHlCdIYDmicboGgScGIznSbCiDbQ XdQFLBOfyX1e1ErERaPvlVWeJluBqv8bK6fQ1tMPEBNVUJD_h9LGVkapHYGZgz3ZD9 benDvscr5uZvLE2iPJCwDQ", "e":"AQAB"} ]}, "MBCB-MCIP-FFUD-BEFU-AOZB-CB3P-5F2S" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"uROiUfJ86JQ9PCVIoCUkB8ttUSkrVCQZIz4UeChXODpvnYhGODQF_qDu wEcvteP0JaKs1DxHTb36q4BQecmUQdCMLVlw0oInX68JXijFacmOCVilzSKU4T4c3e QV9VTC-6Yb9bcHp8N-TJssfowknAEQ-Jpu5V_AVpFJGf60YVNAs0c-eh8T2pYr6_Qd 7mgWisCVKmfGL4-mFqXLWQ0_ysq-7HMyWih0u95GCHo7ZNw0GEwtQcA3rzqKWRemyY zGXqVfepegrzIsQAxTk6zTa79QyeyhPnZ1jVM8HBV-b6ueRy7pwNldX8q4wSqInWfj I3grGv0v9slySTN0h1Y1oQ", "e":"AQAB"} ]} ... ]

Although the SSH protocol does support certificates these are not currently widely used on the client side and it is not clear that the use case of a single user specifying multiple SSH client keys for use on multiple devices has been fully distinguished from the use case of a corporation certifying keys for multiple employees. If the user only has a client single key for a given use, this can be specified as JWK public key parameters. If the user is making use of client side SSH certificates to provision each device with separate SSH credentials, the contact card should specify the SSH certificate. ["MD2V-MWFO-F5DD-PBKF-J5VO-RN5B-U2HB" : { "@type":"OnlineService", "service":"ssh", "label":"Main SSH key", "keys":{ "MAPD-PKMV-PCVV-JNXD-JGPG-6OBD-NYKP":"ssh"}}, "MACQ-Z2ZI-TIPR-OA4J-P7M3-NUS4-V5KI" : { "@type":"OnlineService", "service":"ssh", "keys":{ "MBMU-UB7V-ER7F-SAKS-7EFZ-G66A-2C2I":"ssh"}}] ["MAPD-PKMV-PCVV-JNXD-JGPG-6OBD-NYKP" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"wUZ3uKJ6EHu-Txu3VvrtvrpGPdcKocHj-VFx06Fzg82LbW2dfv-cOzVN mxIiNFCGW4OvaynUNQEtICeDEdJ_0R1Jof3Rq98JoJa1afYIgoHDu6muJamTIRsdbx yVNQc87p-Zf1iQWbHivN3Yv21hhUlaXPQ737svSWhZGIIoSPpRFnP6XQim2r-h_TeK p2Dz32yb1EPImH2YOSRm2NRmjJW68NRMNTi0WTM-JDOwSN0glVILQAPKkQn04LBKHR pm5spsxZrNbTevKj9l6w8H4Dj1ZpMm3h685gdMS_wpBlWPRQ753xX6aN2aSZ0oNcCo nBHR0KQW3ckiRNwY4AdgAQ", "e":"AQAB"} ]}, "MBMU-UB7V-ER7F-SAKS-7EFZ-G66A-2C2I" : { "@type":"Jwks", "jwk":[{ "kty":"RSA", "use":"any", "n":"xOSdSOcUX_50-F3EhxEu3s8CVhG75x0rz5etnmqz6papC7loy66wS94F YsO4xRFytq0-z7CqGcYy7yoirDMkI9mBmw53Br2qzlGpB2FSMctyQruSwYwfODIZ8k -1KundlWSCcCrPnqxSR6Q7cjvFY37cCQnwW9Zrb3X_uRwHO5Etu5ndEdbFG4cpo0zs Fi8lsAoreIX2SLopQ8Tjr51zqrURApO4uJNTejj7MkC8sT11pjMzsdMmNXHrTUf6_v iAim6QYvaUJyOerdjxWNdlH5MM1YE8QNNnEt8HAJoWXNXCbVIbl2aS4ldAUbKBoiP0 l5LRUgooBHObQefEM7p7OQ", "e":"AQAB"} ]}]

Code signing typically makes use of PKIX certificates. While a single certificate could in practice be used for multiple platforms, each code signing program tends to have their own requirements and set of recognized CAs. It is however useful for a user to specify their own personal hierarchy with a personal root for testing and development purposes. A developer may have multiple code signing keys for the same platform. For example, separate signing keys for each development machine. Some mechanism is required to allow development and production keys to be distinguished. ["MAQ7-ZP2C-EHGC-DETY-XYB4-UB2J-3CTG" : { "@type":"OnlineService", "service":"code", "contexts":{ "Pkix":true}, "label":"code Pkix", "keys":{ "MA75-ZNSK-WDRZ-Z3GV-2I2Y-3ZDH-RTCB":"credential"}}, "MBFN-PUI6-NMHJ-3DPO-SJ5H-GAZJ-NOAV" : { "@type":"OnlineService", "service":"code", "contexts":{ "Windows":true}, "label":"code Windows", "keys":{ "MC3T-KJSL-5I5Y-N5X5-PMRY-CJIY-4EUD":"credential"}}, "MBNZ-X4KY-NSPL-BMIT-YOKJ-HUA4-F26K" : { "@type":"OnlineService", "service":"code", "contexts":{ "Apple":true}, "label":"code Apple", "keys":{ "MCXH-T3TV-GWD5-7NY7-PYT2-EQFC-RT2O":"credential"}}, "MC4Q-CHK5-CJBV-FWPU-CDBD-4AMZ-ZXJH" : { "@type":"OnlineService", "service":"code", "contexts":{ "Android":true}, "label":"code Android", "keys":{ "MCUX-ZTA3-G3GA-HQFG-OONX-IID6-BQW2":"credential"}}, "MALZ-A35Y-JMVB-DFFS-4LN4-TMQ4-B52Z" : { "@type":"OnlineService", "service":"code", "contexts":{ "Linux":true}, "label":"code Linux", "keys":{ "MDGG-KIMV-R66M-B3VV-W6FG-HZYQ-M3AO":"credential"}}] ["MA75-ZNSK-WDRZ-Z3GV-2I2Y-3ZDH-RTCB" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MA75-ZNSK-WDRZ-Z3GV-2I2Y-3ZDH-RTCB", "crv":"P-256", "x":"Q4tHNiW2ntKBgoQiP_4nrU3VfCGGN14Z83JCdPgxgP4", "y":"kWnJDvEEXuptMLZqYGb9MTOVGhUrxOqXp7XdPySW2nM"} ]}, "MC3T-KJSL-5I5Y-N5X5-PMRY-CJIY-4EUD" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MC3T-KJSL-5I5Y-N5X5-PMRY-CJIY-4EUD", "crv":"P-256", "x":"Me_8agB7f-zJJsskrvZZ119bmbnqvJOQ9gEwDBeqMdM", "y":"KR-mIu39WnQlch1h5TsRXocKPsA561j6tiFUNXIQkAs"} ]}, "MCXH-T3TV-GWD5-7NY7-PYT2-EQFC-RT2O" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MCXH-T3TV-GWD5-7NY7-PYT2-EQFC-RT2O", "crv":"P-256", "x":"TGYg7REBgC9B0NqIXBgiBocno7bjIyHXt1_mRZiSMwc", "y":"Qgzojc72By1j62iv-RV53bJVcDTMlYM5XqSjfa53voo"} ]}, "MCUX-ZTA3-G3GA-HQFG-OONX-IID6-BQW2" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MCUX-ZTA3-G3GA-HQFG-OONX-IID6-BQW2", "crv":"P-256", "x":"KB1Y8QgZ3wEszY5E9IhzNsE7GGYdu0btsCXvBwqso4Q", "y":"D0YASYgWxT2EYpx9exzfgRDcB5FRhZ9RIFRRmtLPCoM"} ]}, "MDGG-KIMV-R66M-B3VV-W6FG-HZYQ-M3AO" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MDGG-KIMV-R66M-B3VV-W6FG-HZYQ-M3AO", "crv":"P-256", "x":"ODpJuMRYkN-bR-uojCyMt6-uIK4r3RboPo-xVBW7CiY", "y":"X0DkuHNkLyCcuM_8SOISwxlMavk53l828zxFLghdv8U"} ]}]

OpenPGP key management is commonly used for signing repository commits. This use is specified by means of an OnlineService with the service type 'commit' with key entries for the set of authorized signing keys. ["MBEY-C3DZ-TBJU-44QL-GS5G-V7W4-3ERG" : { "@type":"OnlineService", "service":"commit", "label":"commit", "keys":{ "MDAM-YKVI-RXGL-D2NN-EXGQ-PCWY-SNWP":"credential"}}] ["MDAM-YKVI-RXGL-D2NN-EXGQ-PCWY-SNWP" : { "@type":"Jwks", "jwk":[{ "kty":"EC", "use":"any", "kid":"MDAM-YKVI-RXGL-D2NN-EXGQ-PCWY-SNWP", "crv":"P-256", "x":"2Zu42xGUPFhEQUdm-YfpVBZlArwv9zuJgb5yyAElGxA", "y":"IOfX7YTcvfL27g7bhJybNXPqHGtYWiF8rbcrKyNzwVU"} ]}]

This document does not specify any actions for IANA yet but it will...[TBS]

Many thanks to Robert Stepanek who helped refine the approach to extending the schema.