W3C home > Mailing lists > Public > public-webpayments@w3.org > August 2013

Review of JavaScript Object Signing and Encryption (JOSE)

From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 04 Aug 2013 20:15:35 -0400
Message-ID: <51FEEEA7.2010505@digitalbazaar.com>
To: Web Payments <public-webpayments@w3.org>
Hi all,

One of the things we've been needing to do for a while is to do a
thorough technical comparison of the HTTP Keys (Secure Messaging)
specification with the JavaScript Object Signing and Encryption (JOSE)
technology stack. This is the first article (3,600 words) in that
series, which is a high-level analysis of how the two approaches for
securing JSON messages compare against one another. There may be more
articles if further analysis is required by the group.

You can read a Web-based version that's a little easier on the eyes here:

http://manu.sporny.org/2013/sm-vs-jose/

------------------------------------------------------------------
Secure Messaging vs. Javascript Object Signing and Encryption

   The [1]Web Payments group at the World Wide Web Consortium (W3C)
   is currently performing a thorough analysis on the [2]MozPay API.
   The [3]first part of the analysis examined the contents of the
   payment messages. This is the second part of the analysis, which
   will focus on whether the use of the [4]Javascript Object Signing
   and Encryption (JOSE) group's solutions to achieve message
   security is adequate, or if the Web Payment group's solutions
   should be used instead.

The Contenders

   The IETF JOSE Working Group is actively standardizing the
   following specifications for the purposes of adding message
   security to JSON:

   [5]JSON Web Algorithms (JWA)
          Details the cryptographic algorithms and identifiers that
          are meant to be used with the JSON Web Signature (JWS),
          JSON Web Encryption (JWE), JSON Web Token (JWT), and JSON
          Web Key (JWK) specifications. For example, when specifying
          an encryption algorithm, a JSON key/value pair that has alg
          as the key may have HS256 as the value, which means HMAC
          using the SHA-256 hash algorithm.

   [6]JSON Web Key (JWK)
          Details a data structure that represents one or more
          cryptographic keys. If you need to express one of the many
          types of cryptographic key types in use today, this
          specification details how you do that in a standard way.

   [7]JSON Web Token (JWT)
          Defines a way of representing claims such as "Bob was born
          on November 15th, 1984''. These claims are digitally signed
          and/or encrypted using either the JSON Web Signature (JWS)
          or JSON Web Encryption (JWE) specifications.

   [8]JSON Web Encryption (JWE)
          Defines a way to express encrypted content using JSON-based
          data structures. Basically, if you want to encrypt JSON
          data so that only the intended receiver can read the data,
          this specification tells you how to do it in an
          interoperable way.

   [9]JSON Web Signature (JWS)
          Defines a way to digitally sign JSON data structures. If
          your application needs to be able to verify the creator of
          a JSON data structure, you can use this specification to do
          so.

   The W3C Web Payments group is actively standardizing a similar
   specification for the purpose of adding message security to JSON
   messages:

   [10]Secure Messaging (code named: HTTP Keys)
          Describes a simple, decentralized security infrastructure
          for the Web based on JSON, Linked Data, and public key
          cryptography. This system enables Web applications to
          establish identities for agents on the Web, associate
          security credentials with those identities, and then use
          those security credentials to send and receive messages
          that are both encrypted and verifiable via digital
          signatures.

   Both groups are relying on technology that has existed and been
   used for over a decade to achieve secure communications on the
   Internet (symmetric and asymmetric cryptography, public key
   infrastructure, X509 certificates, etc.). The key differences
   between the two have to do more with flexibility, implementation
   complexity, and how the data is published on the Web and used
   between systems.

Basic Differences

   In general, the JOSE group is attempting to create a
   flexible/generalized way of expressing cryptography parameters in
   JSON. They are then using that information and encrypting or
   signing specific data (called claims in the specifications).

   The Web Payments group's specification achieves the same thing,
   but while not trying to be as generalized as the JOSE group.
   Flexibility and generalization tends to 1) make the ecosystem more
   complex than it needs to be for 95% of the use cases, 2) make
   implementations harder to security audit, and 3) make it more
   difficult to achieve interoperability between all implementations.
   The Secure Messaging specification attempts to outline a single
   best practice that will work for 95% of the applications out
   there. The 5% of Web applications that need to do more than the
   Secure Messaging spec can use the JOSE specifications. The Secure
   Messaging specification is also more Web-y. The more Web-y nature
   of the spec gives us a number of benefits, such as giving us a
   Web-scale public key infrastructure as a pleasant side-effect,
   that we will get into below.

JSON-LD Advantages over JSON

   Fundamentally, the Secure Messaging specification relies on the
   Web and [11]Linked Data to remove some of the complexity that
   exists in the JOSE specs while also achieving greater flexibility
   from a data model perspective. Specifically, the Secure Messaging
   specification utilizes Linked Data via a new standards-track
   technology called [12]JSON-LD to allow anyone to build on top of
   the core protocol in a decentralized way. JSON-LD data is
   fundamentally more Web-y than JSON data. Here are the benefits of
   using JSON-LD over regular JSON:

     * A universal identifier mechanism for JSON objects via the use
       of URLs.
     * A way to disambiguate JSON keys shared among different JSON
       documents by mapping them to URLs via a [13]context.
     * A standard mechanism in which a value in a JSON object may
       refer to a JSON object on a different document or site on the
       Web.
     * A way to associate datatypes with values such as dates and
       times.
     * The ability to annotate strings with their language. For
       example, the word `chat' means something different in English
       and French and it helps to know which language was used when
       expressing the text.
     * A facility to express one or more directed graphs, such as a
       social network, in a single document. Graphs are the native
       data structure of the Web.
     * A standard way to map external JSON application data to your
       application data domain.
     * A deterministic way to generate a hash on JSON data, which is
       helpful when attempting to figure out if two data sources are
       expressing the same information.
     * A standard way to digitally sign JSON data.
     * A deterministic way to merge JSON data from multiple data
       sources.

   Plain old JSON, while incredibly useful, does not allow you to do
   the things mentioned above in a standard way. There is a valid
   argument that applications may not need this amount of
   flexibility, and for those applications, JSON-LD does not require
   any of the features above to be used and does not require the JSON
   data to be modified in any way. So people that want to remain in
   the plain `ol JSON bucket can do so without the need to jump into
   the JSON-LD bucket with both feet.

JSON Web Algorithms vs. Secure Messaging

   The JSON Web Algorithms specification details the cryptographic
   algorithms and identifiers that are meant to be used with the JSON
   Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Token
   (JWT), and JSON Web Key (JWK) specifications. For example, when
   specifying an encryption algorithm, a JSON key/value pair that has
   alg as the key may have HS256 as the value, which means HMAC using
   the SHA-256 hash algorithm. The specification is 70 pages long and
   is effectively just a collection of what values are allowed for
   each key used in JOSE-based JSON documents. The design approach
   taken for the JOSE specifications requires that such a document
   exists.

   The Secure Messaging specification takes a different approach.
   Rather than declare all of the popular algorithms and cryptography
   schemes in use today, it defines just one digital signature scheme
   ([14]RSA encryption with a SHA-256 hashing scheme), one encryption
   scheme ([15]128-bit AES with cyclic block chaining), and one way
   of expressing keys (as [16]PEM-formatted data). If placed into a
   single specification, like the JWA spec, it would be just a few
   pages long (really, just 1 page of actual content).

   The most common argument against the Secure Messaging spec, with
   respect to the JWA specification, is that it lacks the same amount
   of [17]cryptographic algorithm agility that the JWA specification
   provides. While this may seem like a valid argument on the
   surface, keep in mind that the core algorithms used by the Secure
   Messaging specification can be changed at any point to any other
   set of algorithms. So, the specification achieves algorithm
   agility while greatly reducing the need for a large 70-page
   specification detailing the allowable values for the various
   cryptographic algorithms. The other benefit is that since the
   cryptography parameters are outlined in a Linked Data vocabulary,
   instead of a process-heavy specification, that they can be added
   to at any point as long as there is community consensus. Note that
   while the vocabulary can be added to, thus providing algorithm
   agility if a particular cryptography scheme is weakened or broken,
   already defined cryptography schemes in the vocabulary must not be
   changed once the cryptography vocabulary terms become widely used
   to ensure that production deployments that use the older mechanism
   aren't broken.

   Providing just one way, the best practice at the time, to do
   digital signatures, encryption, and key publishing reduces
   implementation complexity. Reducing implementation complexity
   makes it easier to perform security audits on implementations.
   Reducing implementation complexity also helps ensure better
   interoperability and more software library implementations, as the
   barrier to creating a fully conforming implementation is greatly
   reduced.

   The Web Payments group believes that new digital signature and
   encryption schemes will have to be updated every 5-7 years. It is
   better to delay the decision to switch to another primary
   algorithm as long as as possible (and as long as it is safe to do
   so). Delaying the cryptographic algorithm decision ensures that
   the group will be able to make a more educated decision than
   attempting to predict which cryptographic algorithms may be the
   successors to currently deployed algorithms.

   Bottom line: The Secure Messaging specification utilizes a much
   simpler approach than the JWA specification while supporting the
   same level of algorithm agility.

JSON Web Key vs. Secure Messaging

   The JSON Web Key (JWK) specification details a data structure that
   is capable of representing one or more cryptographic keys. If you
   need to express one of the many types of cryptographic key types
   in use today, JWK details how you do that in an standard way. A
   typical RSA public key looks like the following using the JWK
   specification:

{
  "keys": [{
    "kty":"RSA",
    "n": "0vx7agoe ... DKgw",
    "e":"AQAB",
    "alg":"RS256",
    "kid":"2011-04-29"
  }]
}

   A similar RSA public key looks like the following using the Secure
   Messaging specification:

{
  "@context": "https://w3id.org/security/v1",
  "@id": "https://example.com/i/bob/keys/1",
  "@type": "Key",
  "owner": "https://example.com/i/bob",
  "publicKeyPem": "-----BEGIN PRIVATE
KEY-----\nMIIBG0BA...OClDQAB\n-----END PRIVATE KEY-----\n"
}

   There are a number of differences between the two key formats.
   Specifically:

    1. The JWK format expresses key information by specifying the key
       parameters directly. The Secure Messaging format places all of
       the key parameters into a PEM-encoded blob. This approach was
       taken because it is easier for developers to use the PEM data
       without introducing errors. Since most Web developers do not
       understand what variables like dq (the second factor Chinese
       Remainder Theorem exponent parameter) or d (the Elliptic Curve
       private key parameter) are, the likelihood of transporting and
       publishing that sort of data without error is lower than
       placing all parameters in an opaque blob of information that
       has a clear beginning and end (-----BEGIN RSA PRIVATE
       KEY-----, and --- END RSA PRIVATE KEY ---)
    2. In the general case, the Secure Messaging key format assigns
       URL identifiers to keys and publishes them on the Web as
       JSON-LD, and optionally as RDFa. This means that public key
       information is discoverable and human and machine-readable by
       default, which means that all of the key parameters can be
       read from the Web. The JWK mechanism does assign a key ID to
       keys, but does not require that they are published to the Web
       if they are to be used in message exchanges. The JWK
       specification could be extended to enable this, but by
       default, doesn't provide this functionality.
    3. The Secure Messaging format is also capable of specifying an
       identity that owns the key, which allows a key to be tied to
       an identity and that identity to be used for thinks like
       Access Control to Web resources and REST APIs. The JWK format
       has no such mechanism outlined in the specification.

   Bottom line: The Secure Messaging specification provides four
   major advantages over the JWK format: 1) the key information is
   expressed at a higher level, which makes it easier to work with
   for Web developers, 2) it allows key information to be discovered
   by deferencing the key ID, 3) the key information can be published
   (and extended) in a variety of Linked Data formats, and 4) it
   provides the ability to assign ownership information to keys.

JSON Web Tokens vs. Secure Messaging

   The JSON Web Tokens (JWT) specification defines a way of
   representing claims such as "Bob was born on November 15th,
   1984''. These claims are digitally signed and/or encrypted using
   either the JSON Web Signature (JWS) or JSON Web Encryption (JWE)
   specifications. Here is an example of a JWT document:

{
  "iss": "joe",
  "exp": 1300819380,
  "http://example.com/is_root": true
}

   JWT documents contain keys that are public, such as iss and exp
   above, and keys that are private (which could conflict with keys
   from the JWT specification). The data format is fairly free-form,
   meaning that any data can be placed inside a JWT Claims Set like
   the one above.

   Since the Secure Messaging specification utilizes JSON-LD for its
   data expression mechanism, it takes a fundamentally different
   approach. There are no headers or claims sets in the Secure
   Messaging specification, just data. For example, the data below is
   effectively a JWT claims set expressed in JSON-LD:

{
  "@context": "http://json-ld.org/contexts/person",
  "@type": "Person",
  "name": "Manu Sporny",
  "gender": "male",
  "homepage": "http://manu.sporny.org/"
}

   Note that there are no keywords specific to the Secure Messaging
   specification, just keys that are mapped to URLs (to prevent
   collisions) and data. In JSON-LD, these keys and data are
   machine-interpretable in a standards-compliant manner (unlike JWT
   data), and can be merged with other data sources without the
   danger of data being overwritten or colliding with other
   application data.

   Bottom line: The Secure Messaging specifications use of a native
   Linked Data format removes the requirement for a specification
   like JWT. As far as the Secure Messaging specification is
   concerned, there is just data, which you can then digitally sign
   and encrypt. This makes the data easier to work with for Web
   developers as they can continue to use their application data
   as-is instead of attempting to restructure it into a JWT.

JSON Web Encryption vs. Secure Messaging

   The JSON Web Encryption (JWE) specification defines a way to
   express encrypted content using JSON-based data structures.
   Basically, if you want to encrypt JSON data so that only the
   intended receiver can read the data, this specification tells you
   how to do it in an interoperable way. A JWE-encrypted message
   looks like this:

{
  "protected": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
  "unprotected": {"jku": "https://server.example.com/keys.jwks"},
  "recipients": [{
    "header": {
      "alg":"RSA1_5"
        "kid":"2011-04-29",
        "enc":"A128CBC-HS256",
        "jku":"https://server.example.com/keys.jwks"
      },
      "encrypted_key": "UGhIOgu ... MR4gp_A"
    }]
  }],
  "iv": "AxY8DCtDaGlsbGljb3RoZQ",
  "ciphertext": "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY",
  "tag": "Mz-VPPyU4RlcuYv1IwIvzw"
}

   To decrypt this information, an application would retrieve the
   private key associated with the recipients[0].header, and then
   decrypt the encrypted_key. Using the decrypted encrypted_key
   value, it would then use the iv to decrypt the protected header.
   Using the algorithm provided in the protected header, it would
   then use the decrypted encrypted_key, iv, the algorithm specified
   in the protected header, and the ciphertext to retrieve the
   original message as a result.

   For comparison purposes, a Secure Messaging encrypted message
   looks like this:

{
  "@context": "https://w3id.org/security/v1",
  "@type": "EncryptedMessage2012",
  "data": "VTJGc2RH ... Fb009Cg==",
  "encryptionKey": "uATte ... HExjXQE=",
  "iv": "vcDU1eWTy8vVGhNOszREhSblFVqVnGpBUm0zMTRmcWtMrRX==",
  "publicKey": "https://example.com/people/john/keys/23"
}

   To decrypt this information, an application would use the private
   key associated with the publicKey to decrypt the encryptionKey and
   iv. It would then use the decrypted encryptionKey and iv to
   decrypt the value in data, retrieving the original message as a
   result.

   The Secure Messaging encryption protocol is simpler than the JWE
   protocol for three major reasons:
    1. The @type of the message, EncryptedMessage2012, encapsulates
       all of the cryptographic algorithm information in a
       machine-readable way (that can also be hard-coded in
       implementations). The JWE specification utilizes the protected
       field to express the same sort of information, which is
       allowed to get far more complicated than the Secure Messaging
       equivalent, leading to more complexity.
    2. Key information is expressed in one entry, the publicKey
       entry, which is a link to a machine-readable document that can
       express not only the public key information, but who owns the
       key, the name of the key, creation and revocation dates for
       the key, as well as a number of other Linked Data values that
       result in a full-fledged Web-based PKI system. Not only is
       Secure Messaging encryption simpler than JWE, but it also
       enables many more types of extensibility.
    3. The key data is expressed in a PEM-encoded format, which is
       expressed as a base-64 encoded blob of information. This
       approach was taken because it is easier for developers to use
       the data without introducing errors. Since most Web developers
       do not understand what variables like dq (the second factor
       Chinese Remainder Theorem exponent parameter) or d (the
       Elliptic Curve private key parameter) are, the likelihood of
       transporting and publishing that sort of data without error is
       lower than placing all parameters in an opaque blob of
       information that has a clear beginning and end (-----BEGIN RSA
       PRIVATE KEY-----, and --- END RSA PRIVATE KEY ---).

   The rest of the entries in the JSON are typically required for the
   encryption method selected to secure the message. There is not a
   great deal of difference between the two specifications when it
   comes to the parameters that are needed for the encryption
   algorithm.

   Bottom line: The major difference between the Secure Messaging and
   JWE specification has to do with how the encryption parameters are
   specified as well as how many of them there can be. The Secure
   Messaging specification expresses only one encryption mechanism
   and outlines the algorithms and keys external to the message,
   which leads to a reduction in complexity. The JWE specification
   allows many more types of encryption schemes to be used, at the
   expense of added complexity.

JSON Web Signatures vs. Secure Messaging

   The JSON Web Signatures (JWS) specification defines a way to
   digitally sign JSON data structures. If your application needs to
   be able to verify the creator of a JSON data structure, you can
   use this specification to do so. A JWS digital signature looks
   like the following:

{
  "payload": "eyJpc ... VlfQ",
  "signatures":[{
    "protected":"eyJhbGciOiJSUzI1NiJ9",
    "header": {
      "kid":"2010-12-29"
    },
    "signature": "cC4hi ... 77Rw"
  }]
}

   For the purposes of comparison, a Secure Messaging message and
   signature looks like the following:

{
  "@context": [
    "https://w3id.org/security/v1",
    "http://json-ld.or/contexts/person"
  ]
  "@type": "Person",
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/",
  "signature":
  {
    "@type": "GraphSignature2012",
    "creator": "http://example.org/manu/keys/5",
    "created": "2013-08-04T17:39:53Z",
    "signatureValue": "OGQzN ... IyZTk="
  }
}

   There are a number of stark differences between the two
   specifications when it comes to digital signatures:

    1. The Secure Messaging specification does not need to base-64
       encode the payload being signed. This makes it easier for a
       developer to see (and work with) the data that was digitally
       signed. Debugging signed messages is also simplified as
       special tools to decode the payload are unnecessary.
    2. The Secure Messaging specification does not require any header
       parameters for the payload, which reduces the number of things
       that can go wrong when verifying digitally signed messages.
       One could argue that this also reduces flexibility. The
       counter-argument is that different signature schemes can
       always be switched in by just changing the @type of the
       signature.
    3. The signer's public key is available via a URL. This means
       that, in general, all Secure Messaging signatures can be
       verified by dereferencing the creator URL and utilizing the
       published key data to verify the signature.
    4. The Secure Messaging specification depends on a normalization
       algorithm that is applied to the message. This algorithm is
       non-trivial, typically implemented behind a JSON-LD library
       .normalize() method call. JWS does not require data
       normalization. The trade-off is simplicity at the expense of
       requiring your data to always be encapsulated in the message.
       For example, the Secure Messaging specification is capable of
       pointing to a digital signature expressed in RDFa on a website
       using a URL. An application can then dereference that URL,
       convert the data to JSON-LD, and verify the digital signature.
       This mechanism is useful, for example, when you want to
       publish items for sale along with their prices on a Web page
       in a machine-readable way. This sort of use case is not
       achievable with the JWS specification. All data is required to
       be in the message. In other words, Secure Messaging performs a
       signature on information that could exist on the Web where the
       JWS specification performs a signature on a string of text in
       a message.
    5. The JWS mechanism enables HMAC-based signatures while the
       Secure Messaging mechanism avoids the use of HMAC altogether,
       taking the position that shared secrets are typically a bad
       practice.

   Bottom line: The Secure Messaging specification does not need to
   encode its payloads, but does require a rather complex
   normalization algorithm. It supports discovery of signature key
   data so that signatures can be verified using standard Web
   protocols. The JWS specification is more flexible from an
   algorithmic standpoint and simpler from a signature verification
   standpoint. The downside is that the only data input format must
   be from the message itself and can't be from an external Linked
   Data source, like an HTML+RDFa web page listing items for sale.

Conclusion

   The Secure Messaging and JOSE designs, while attempting to achieve
   the same basic goals, deviate in the approaches taken to
   accomplish those goals. The Secure Messaging specification
   leverages more of the Web with its use of a Linked Data format and
   URLs for identifying and verifying identity and keys. It also
   attempts to encapsulate a single best practice that will work for
   the vast majority of Web applications in use today. The JOSE
   specifications are more flexible in the type of cryptographic
   algorithms that can be used which results in more low-level
   primitives used in the protocol, increasing complexity for
   developers that must create interoperable JOSE-based applications.

   From a specification size standpoint, the JOSE specs weigh in at
   225 pages, the Secure Messaging specification weighs in at around
   20 pages. This is rarely a good way to compare specifications, and
   doesn't always result in an apples to apples comparison. It does,
   however, give a general idea of the amount of text required to
   explain the details of each approach, and thus a ballpark idea of
   the complexity associated with each specification. Like all
   specifications, picking one depends on the use cases that an
   application is attempting to support. The goal with the Secure
   Messaging specification is that it will be good enough for 95% of
   Web developers out there, and for the remaining 5%, there is the
   JOSE stack.

References

   1. http://www.w3.org/community/webpayments/
   2. https://wiki.mozilla.org/WebAPI/WebPayment
   3. http://manu.sporny.org/2013/mozpay-analysis/
   4. http://tools.ietf.org/wg/jose/
   5. http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms
   6. http://tools.ietf.org/wg/jose/draft-ietf-jose-json-web-key/
   7. http://tools.ietf.org/html/draft-ietf-oauth-json-web-token
   8. http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption
   9. http://tools.ietf.org/wg/jose/draft-ietf-jose-json-web-signature/
  10. https://payswarm.com/specs/source/http-keys/
  11. http://www.youtube.com/watch?v=4x_xzT5eF5Q
  12. http://www.youtube.com/watch?v=vioCbTo3C-4
  13. http://json-ld.org/spec/latest/json-ld/#the-context
  14. https://payswarm.com/specs/source/vocabs/security#GraphSignature2012
  15. https://payswarm.com/specs/source/vocabs/security#EncryptedMessage
  16. https://payswarm.com/specs/source/vocabs/security#privateKeyPem
  17. http://msdn.microsoft.com/en-us/magazine/ee321570.aspx

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Meritora - Web payments commercial launch
http://blog.meritora.com/launch/
Received on Monday, 5 August 2013 00:16:09 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:03:32 UTC