|
| 1 | +# Specification: DAG-JOSE |
| 2 | + |
| 3 | +**Status: Descriptive - Draft** |
| 4 | + |
| 5 | +JOSE is a standard for signing and encrypting JSON objects. The various specifications for JOSE can be found in the [IETF datatracker](https://datatracker.ietf.org/wg/jose/documents/). |
| 6 | + |
| 7 | +## Format |
| 8 | + |
| 9 | +The are two kinds of JOSE objects: JWS ([JSON web signature](https://datatracker.ietf.org/doc/rfc7515/?include_text=1)) and JWE ([JSON web encryption](https://datatracker.ietf.org/doc/rfc7516/?include_text=1)). These two objects are primitives in JOSE and can be used to create JWT and JWM objects etc. The IETF RFCs specify a JSON encoding of JOSE objects. This specification maps the JSON encoding to CBOR. Upon encountering the `dag-jose` multiformat implementations can be sure that the block contains dag-cbor encoded data which matches the IPLD schema we specify below. |
| 10 | + |
| 11 | +### Mapping from the JOSE general JSON serialization to dag-jose serialization |
| 12 | + |
| 13 | +Both JWS and JWE supports three different serialization formats: `Compact Serialization`, `Flattened JSON Serialization`, and `General JSON Serialization`. The first two are more concise, but they only allow for one recipient. Therefore DAG JOSE always uses the `General Serialization` which ensures maximum compatibility with minimum ambiguity. Libraries implementing serialization should accept all JOSE formats including the `Decoded Representation` (see below) and convert them if necessary. |
| 14 | + |
| 15 | +To map the general JSON serialization to CBOR we do the following: |
| 16 | + |
| 17 | +- Any field which is represented as `base64url(<data>)` we map directly to `Bytes` . For fields like `header` and `protected` which are specified as the `base64url(ascii(<some json>))` that means that the value is the `ascii(<some json>)` bytes. |
| 18 | +- For JWS we specify that the `payload` property MUST be a CID, and we set the `payload` of the encoded JOSE object to `Bytes` containing the bytes of the CID. For applications where an additional network request to retrieve the linked content is undesirable then an `identity` multihash should be used. |
| 19 | +- For JWE objects the `ciphertext` must decrypt to a cleartext which is the bytes of a CID. This is for the same reason as the `payload` being a CID, and the same approach of using an `identity` multihash can be used, and most likely will be the only way to retain the confidentiality of data. |
| 20 | + |
| 21 | +Below we present an IPLD schema representing the encoded JOSE objects. Note that there are two IPLD schemas, `EncodedJWE` and `EncodedJWS`. The actual wire format is a single struct which contains all the keys from both the `EncodedJWE` and the `EncodedJWS` structs, implementors should follow [section 9 of the JWE spec](https://tools.ietf.org/html/rfc7516#section-9) and distinguish between these two branches by checking if the `payload` attribute exists, and hence you have a JWS; or the `ciphertext` attribute, hence you have a JWE. |
| 22 | + |
| 23 | +**Encoded JOSE** |
| 24 | + |
| 25 | +```ipldsch |
| 26 | +type EncodedSignature struct { |
| 27 | + header optional {String:Any} |
| 28 | + protected optional Bytes |
| 29 | + signature Bytes |
| 30 | +} |
| 31 | +
|
| 32 | +type EncodedRecipient struct { |
| 33 | + encrypted_key optional Bytes |
| 34 | + header optional {String:Any} |
| 35 | +} |
| 36 | +
|
| 37 | +type EncodedJWE struct { |
| 38 | + aad optional Bytes |
| 39 | + ciphertext Bytes |
| 40 | + iv optional Bytes |
| 41 | + protected optional Bytes |
| 42 | + recipients [EncodedRecipient] |
| 43 | + tag optional Bytes |
| 44 | + unprotected optional {String:Any} |
| 45 | +} |
| 46 | +
|
| 47 | +type EncodedJWS struct { |
| 48 | + payload optional Bytes |
| 49 | + signatures [EncodedSignature] |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +## Padding for encryption |
| 54 | + |
| 55 | +Applications may need to pad the cleartext when encrypting to avoid leaking the size of the cleartext. This raises the question of how the application knows what part of the decrypted cleartext is padding. In this case we use the fact that the cleartext MUST be a valid CID, implementations should parse the cleartext as a CID and discard any content beyond the multihash digest size - which we assume to be the padding. |
| 56 | + |
| 57 | + |
| 58 | +## Decoded JOSE |
| 59 | + |
| 60 | +Typically implementations will want to decode this format into something more useful for applications. Exactly what that will look like depends on the language of the implementation, here we use the IPLD schema language to give a somewhat language agnostic description of what the decoded representation might look like at runtime. Note that everything which is specified as `base64url(ascii(<some JSON>))` in the JOSE specs - and which we encode as `Bytes` in the wire format - is here decoded to a `String`. We also add the `link: &Any` attribute to the `DecodedJWS`, which allows applications to easily retrieve the authenticated content. |
| 61 | + |
| 62 | +Also note that, as with the encoded representation, there are two different representations; `DecodedJWE` and `DecodedJWS`. Applications can distinguish between these two branches in the same way as with the Encoded representation described above. |
| 63 | + |
| 64 | +```ipldsch |
| 65 | +type DecodedSignature struct { |
| 66 | + header optional {String:Any} |
| 67 | + protected optional String |
| 68 | + signature String |
| 69 | +} |
| 70 | +
|
| 71 | +type DecodedJWS struct { |
| 72 | + payload String |
| 73 | + signatures [DecodedSignature] |
| 74 | + link: &Any |
| 75 | +} |
| 76 | +
|
| 77 | +type DecodedRecipient struct { |
| 78 | + encrypted_key optional String |
| 79 | + header optional {String:Any} |
| 80 | +} |
| 81 | +
|
| 82 | +type DecodedJWE struct { |
| 83 | + aad optional String |
| 84 | + ciphertext String |
| 85 | + iv String |
| 86 | + protected String |
| 87 | + recipients [DecodedRecipient] |
| 88 | + tag String |
| 89 | + unprotected optional {String:Any} |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +## Implementations |
| 94 | + |
| 95 | +- [Javascript](https://github.com/oed/js-dag-jose) |
| 96 | +- [Go](https://github.com/alexjg/go-dag-jose) |
0 commit comments