tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7520

 Errata 
Informational
Pages: 120
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: JOSE

Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE)

Part 1 of 4, p. 1 to 11
None       Next RFC Part

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                         M. Miller
Request for Comments: 7520                           Cisco Systems, Inc.
Category: Informational                                         May 2015
ISSN: 2070-1721


                  Examples of Protecting Content Using
               JSON Object Signing and Encryption (JOSE)

Abstract

   This document contains a set of examples using JSON Object Signing
   and Encryption (JOSE) technology to protect data.  These examples
   present a representative sampling of JSON Web Key (JWK) objects as
   well as various JSON Web Signature (JWS) and JSON Web Encryption
   (JWE) results given similar inputs.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for informational purposes.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Not all documents
   approved by the IESG are a candidate for any level of Internet
   Standard; see Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc7520.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Top       Page 2 
Table of Contents

   1. Introduction ....................................................5
      1.1. Conventions Used in This Document ..........................5
   2. Terminology .....................................................6
   3. JSON Web Key Examples ...........................................6
      3.1. EC Public Key ..............................................6
      3.2. EC Private Key .............................................7
      3.3. RSA Public Key .............................................8
      3.4. RSA Private Key ............................................8
      3.5. Symmetric Key (MAC Computation) ...........................10
      3.6. Symmetric Key (Encryption) ................................11
   4. JSON Web Signature Examples ....................................11
      4.1. RSA v1.5 Signature ........................................12
           4.1.1. Input Factors ......................................12
           4.1.2. Signing Operation ..................................12
           4.1.3. Output Results .....................................13
      4.2. RSA-PSS Signature .........................................15
           4.2.1. Input Factors ......................................15
           4.2.2. Signing Operation ..................................16
           4.2.3. Output Results .....................................17
      4.3. ECDSA Signature ...........................................19
           4.3.1. Input Factors ......................................19
           4.3.2. Signing Operation ..................................19
           4.3.3. Output Results .....................................20
      4.4. HMAC-SHA2 Integrity Protection ............................21
           4.4.1. Input Factors ......................................22
           4.4.2. Signing Operation ..................................22
           4.4.3. Output Results .....................................23
      4.5. Signature with Detached Content ...........................24
           4.5.1. Input Factors ......................................25
           4.5.2. Signing Operation ..................................25
           4.5.3. Output Results .....................................26
      4.6. Protecting Specific Header Fields .........................27
           4.6.1. Input Factors ......................................27
           4.6.2. Signing Operation ..................................27
           4.6.3. Output Results .....................................28
      4.7. Protecting Content Only ...................................29
           4.7.1. Input Factors ......................................30
           4.7.2. Signing Operation ..................................30
           4.7.3. Output Results .....................................31
      4.8. Multiple Signatures .......................................32
           4.8.1. Input Factors ......................................32
           4.8.2. First Signing Operation ............................33
           4.8.3. Second Signing Operation ...........................34
           4.8.4. Third Signing Operation ............................36
           4.8.5. Output Results .....................................37
   5. JSON Web Encryption Examples ...................................39

Top      ToC       Page 3 
      5.1. Key Encryption Using RSA v1.5 and AES-HMAC-SHA2 ...........39
           5.1.1. Input Factors ......................................39
           5.1.2. Generated Factors ..................................41
           5.1.3. Encrypting the Key .................................41
           5.1.4. Encrypting the Content .............................42
           5.1.5. Output Results .....................................43
      5.2. Key Encryption Using RSA-OAEP with AES-GCM ................45
           5.2.1. Input Factors ......................................46
           5.2.2. Generated Factors ..................................47
           5.2.3. Encrypting the Key .................................48
           5.2.4. Encrypting the Content .............................48
           5.2.5. Output Results .....................................49
      5.3. Key Wrap Using PBES2-AES-KeyWrap with AES-CBC-HMAC-SHA2 ...52
           5.3.1. Input Factors ......................................53
           5.3.2. Generated Factors ..................................54
           5.3.3. Encrypting the Key .................................54
           5.3.4. Encrypting the Content .............................55
           5.3.5. Output Results .....................................56
      5.4. Key Agreement with Key Wrapping Using ECDH-ES and
           AES-KeyWrap with AES-GCM ..................................59
           5.4.1. Input Factors ......................................59
           5.4.2. Generated Factors ..................................60
           5.4.3. Encrypting the Key .................................60
           5.4.4. Encrypting the Content .............................61
           5.4.5. Output Results .....................................63
      5.5. Key Agreement Using ECDH-ES with AES-CBC-HMAC-SHA2 ........65
           5.5.1. Input Factors ......................................66
           5.5.2. Generated Factors ..................................66
           5.5.3. Key Agreement ......................................67
           5.5.4. Encrypting the Content .............................67
           5.5.5. Output Results .....................................68
      5.6. Direct Encryption Using AES-GCM ...........................70
           5.6.1. Input Factors ......................................70
           5.6.2. Generated Factors ..................................70
           5.6.3. Encrypting the Content .............................71
           5.6.4. Output Results .....................................72
      5.7. Key Wrap Using AES-GCM KeyWrap with AES-CBC-HMAC-SHA2 .....73
           5.7.1. Input Factors ......................................73
           5.7.2. Generated Factors ..................................74
           5.7.3. Encrypting the Key .................................74
           5.7.4. Encrypting the Content .............................75
           5.7.5. Output Results .....................................77
      5.8. Key Wrap Using AES-KeyWrap with AES-GCM ...................79
           5.8.1. Input Factors ......................................79
           5.8.2. Generated Factors ..................................80
           5.8.3. Encrypting the Key .................................80
           5.8.4. Encrypting the Content .............................80
           5.8.5. Output Results .....................................82

Top      ToC       Page 4 
      5.9. Compressed Content ........................................84
           5.9.1. Input Factors ......................................84
           5.9.2. Generated Factors ..................................84
           5.9.3. Encrypting the Key .................................85
           5.9.4. Encrypting the Content .............................85
           5.9.5. Output Results .....................................86
      5.10. Including Additional Authenticated Data ..................88
           5.10.1. Input Factors .....................................88
           5.10.2. Generated Factors .................................89
           5.10.3. Encrypting the Key ................................90
           5.10.4. Encrypting the Content ............................90
           5.10.5. Output Results ....................................91
      5.11. Protecting Specific Header Fields ........................93
           5.11.1. Input Factors .....................................93
           5.11.2. Generated Factors .................................94
           5.11.3. Encrypting the Key ................................94
           5.11.4. Encrypting the Content ............................94
           5.11.5. Output Results ....................................95
      5.12. Protecting Content Only ..................................97
           5.12.1. Input Factors .....................................97
           5.12.2. Generated Factors .................................98
           5.12.3. Encrypting the Key ................................98
           5.12.4. Encrypting the Content ............................98
           5.12.5. Output Results ....................................99
      5.13. Encrypting to Multiple Recipients .......................101
           5.13.1. Input Factors ....................................101
           5.13.2. Generated Factors ................................101
           5.13.3. Encrypting the Key to the First Recipient ........102
           5.13.4. Encrypting the Key to the Second Recipient .......103
           5.13.5. Encrypting the Key to the Third Recipient ........105
           5.13.6. Encrypting the Content ...........................106
           5.13.7. Output Results ...................................108
   6. Nesting Signatures and Encryption .............................110
      6.1. Signing Input Factors ....................................110
      6.2. Signing Operation ........................................112
      6.3. Signing Output ...........................................112
      6.4. Encryption Input Factors .................................113
      6.5. Encryption Generated Factors .............................113
      6.6. Encrypting the Key .......................................114
      6.7. Encrypting the Content ...................................114
      6.8. Encryption Output ........................................115
   7. Security Considerations .......................................119
   8. References ....................................................119
      8.1. Normative References .....................................119
      8.2. Informative References ...................................120
   Acknowledgements .................................................120
   Author's Address .................................................120

Top      ToC       Page 5 
1.  Introduction

   The JSON Object Signing and Encryption (JOSE) technologies -- JSON
   Web Signature [JWS], JSON Web Encryption [JWE], JSON Web Key [JWK],
   and JSON Web Algorithms [JWA] -- can be used collectively to encrypt
   and/or sign content using a variety of algorithms.  While the full
   set of permutations is extremely large, and might be daunting to
   some, it is expected that most applications will only use a small set
   of algorithms to meet their needs.

   This document provides a number of examples of signing or encrypting
   content using JOSE.  While not exhaustive, it does compile a
   representative sampling of JOSE features.  As much as possible, the
   same signature payload or encryption plaintext content is used to
   illustrate differences in various signing and encryption results.

   This document also provides a number of example JWK objects.  These
   examples illustrate the distinguishing properties of various key
   types and emphasize important characteristics.  Most of the JWK
   examples are then used in the signature or encryption examples that
   follow.

   All of the examples contained herein are available in a machine-
   readable format at <https://github.com/ietf-jose/cookbook>.

1.1.  Conventions Used in This Document

   This document separates data that are expected to be input to an
   implementation of JOSE from data that are expected to be generated by
   an implementation of JOSE.  Each example, wherever possible, provides
   enough information both to replicate the results of this document and
   to validate the results by running its inverse operation (e.g.,
   signature results can be validated by performing the JWS verify).
   However, some algorithms inherently use random data; therefore,
   computations employing them cannot be exactly replicated.  Such cases
   are explicitly stated in the relevant sections.

   All instances of binary octet strings are represented using base64url
   [RFC4648] encoding.

   Wherever possible and unless otherwise noted, the examples include
   the JWS or JWE Compact Serialization, general JWS or JWE JSON
   Serialization, and flattened JWS or JWE JSON Serialization.

   All of the examples in this document have whitespace added to improve
   formatting and readability.  Except for JWE Plaintext or JWS Payload
   content, whitespace is not part of the cryptographic operations nor
   the exchange results.

Top      ToC       Page 6 
   Unless otherwise noted, the JWE Plaintext or JWS Payload content does
   include " " (U+0020 SPACE) characters.  Line breaks (U+000A LINE
   FEED) replace some " " (U+0020 SPACE) characters to improve
   readability but are not present in the JWE Plaintext or JWS Payload.

2.  Terminology

   This document inherits terminology regarding JSON Web Signature (JWS)
   technology from [JWS], terminology regarding JSON Web Encryption
   (JWE) technology from [JWE], terminology regarding JSON Web Key (JWK)
   technology from [JWK], and terminology regarding algorithms from
   [JWA].

3.  JSON Web Key Examples

   The following sections demonstrate how to represent various JWK and
   JWK Set objects.

3.1.  EC Public Key

   This example illustrates an Elliptic Curve (EC) public key.  This
   example is the public key corresponding to the private key in
   Figure 2.

   Note that whitespace is added for readability as described in
   Section 1.1.

   {
     "kty": "EC",
     "kid": "bilbo.baggins@hobbiton.example",
     "use": "sig",
     "crv": "P-521",
     "x": "AHKZLLOsCOzz5cY97ewNUajB957y-C-U88c3v13nmGZx6sYl_oJXu9
         A5RkTKqjqvjyekWF-7ytDyRXYgCF5cj0Kt",
     "y": "AdymlHvOiLxXkEhayXQnNCvDX4h9htZaCJN34kfmC6pV5OhQHiraVy
         SsUdaQkAgDPrwQrJmbnX9cwlGfP-HqHZR1"
   }

                 Figure 1: Elliptic Curve P-521 Public Key

   The field "kty" value of "EC" identifies this as an Elliptic Curve
   key.  The field "crv" identifies the curve, which is curve P-521 for
   this example.  The values of the fields "x" and "y" are the
   base64url-encoded X and Y coordinates (respectively).

Top      ToC       Page 7 
   The values of the fields "x" and "y" decoded are the octets necessary
   to represent each full coordinate to the order of the curve.  For a
   key over curve P-521, the values of the fields "x" and "y" are
   exactly 66 octets in length when decoded, padded with leading zero
   (0x00) octets to reach the expected length.

3.2.  EC Private Key

   This example illustrates an Elliptic Curve private key.  This example
   is the private key corresponding to the public key in Figure 1.

   Note that whitespace is added for readability as described in
   Section 1.1.

   {
     "kty": "EC",
     "kid": "bilbo.baggins@hobbiton.example",
     "use": "sig",
     "crv": "P-521",
     "x": "AHKZLLOsCOzz5cY97ewNUajB957y-C-U88c3v13nmGZx6sYl_oJXu9
         A5RkTKqjqvjyekWF-7ytDyRXYgCF5cj0Kt",
     "y": "AdymlHvOiLxXkEhayXQnNCvDX4h9htZaCJN34kfmC6pV5OhQHiraVy
         SsUdaQkAgDPrwQrJmbnX9cwlGfP-HqHZR1",
     "d": "AAhRON2r9cqXX1hg-RoI6R1tX5p2rUAYdmpHZoC1XNM56KtscrX6zb
         KipQrCW9CGZH3T4ubpnoTKLDYJ_fF3_rJt"
   }

                Figure 2: Elliptic Curve P-521 Private Key

   The field "kty" value of "EC" identifies this as an Elliptic Curve
   key.  The field "crv" identifies the curve, which is curve P-521
   (also known as SECG curve secp521r1) for this example.  The values of
   the fields "x" and "y" are the base64url-encoded X and Y coordinates
   (respectively).  The field "d" value is the base64url-encoded private
   key.

   The values of the fields "d", "x", and "y" decoded are the octets
   necessary to represent the private key or each full coordinate
   (respectively) to the order of the curve.  For a key over curve
   P-521, the values of the "d", "x", and "y" fields are each exactly 66
   octets in length when decoded, padded with leading zero (0x00) octets
   to reach the expected length.

Top      ToC       Page 8 
3.3.  RSA Public Key

   This example illustrates an RSA public key.  This example is the
   public key corresponding to the private key in Figure 4.

   Note that whitespace is added for readability as described in
   Section 1.1.

   {
     "kty": "RSA",
     "kid": "bilbo.baggins@hobbiton.example",
     "use": "sig",
     "n": "n4EPtAOCc9AlkeQHPzHStgAbgs7bTZLwUBZdR8_KuKPEHLd4rHVTeT
         -O-XV2jRojdNhxJWTDvNd7nqQ0VEiZQHz_AJmSCpMaJMRBSFKrKb2wqV
         wGU_NsYOYL-QtiWN2lbzcEe6XC0dApr5ydQLrHqkHHig3RBordaZ6Aj-
         oBHqFEHYpPe7Tpe-OfVfHd1E6cS6M1FZcD1NNLYD5lFHpPI9bTwJlsde
         3uhGqC0ZCuEHg8lhzwOHrtIQbS0FVbb9k3-tVTU4fg_3L_vniUFAKwuC
         LqKnS2BYwdq_mzSnbLY7h_qixoR7jig3__kRhuaxwUkRz5iaiQkqgc5g
         HdrNP5zw",
     "e": "AQAB"
   }

                     Figure 3: RSA 2048-Bit Public Key

   The field "kty" value of "RSA" identifies this as an RSA key.  The
   fields "n" and "e" values are the modulus and (public) exponent
   (respectively) using the minimum octets necessary.

   For a 2048-bit key, the field "n" value is 256 octets in length when
   decoded.

3.4.  RSA Private Key

   This example illustrates an RSA private key.  This example is the
   private key corresponding to the public key in Figure 3.

   Note that whitespace is added for readability as described in
   Section 1.1.

Top      ToC       Page 9 
   {
     "kty": "RSA",
     "kid": "bilbo.baggins@hobbiton.example",
     "use": "sig",
     "n": "n4EPtAOCc9AlkeQHPzHStgAbgs7bTZLwUBZdR8_KuKPEHLd4rHVTeT
         -O-XV2jRojdNhxJWTDvNd7nqQ0VEiZQHz_AJmSCpMaJMRBSFKrKb2wqV
         wGU_NsYOYL-QtiWN2lbzcEe6XC0dApr5ydQLrHqkHHig3RBordaZ6Aj-
         oBHqFEHYpPe7Tpe-OfVfHd1E6cS6M1FZcD1NNLYD5lFHpPI9bTwJlsde
         3uhGqC0ZCuEHg8lhzwOHrtIQbS0FVbb9k3-tVTU4fg_3L_vniUFAKwuC
         LqKnS2BYwdq_mzSnbLY7h_qixoR7jig3__kRhuaxwUkRz5iaiQkqgc5g
         HdrNP5zw",
     "e": "AQAB",
     "d": "bWUC9B-EFRIo8kpGfh0ZuyGPvMNKvYWNtB_ikiH9k20eT-O1q_I78e
         iZkpXxXQ0UTEs2LsNRS-8uJbvQ-A1irkwMSMkK1J3XTGgdrhCku9gRld
         Y7sNA_AKZGh-Q661_42rINLRCe8W-nZ34ui_qOfkLnK9QWDDqpaIsA-b
         MwWWSDFu2MUBYwkHTMEzLYGqOe04noqeq1hExBTHBOBdkMXiuFhUq1BU
         6l-DqEiWxqg82sXt2h-LMnT3046AOYJoRioz75tSUQfGCshWTBnP5uDj
         d18kKhyv07lhfSJdrPdM5Plyl21hsFf4L_mHCuoFau7gdsPfHPxxjVOc
         OpBrQzwQ",
     "p": "3Slxg_DwTXJcb6095RoXygQCAZ5RnAvZlno1yhHtnUex_fp7AZ_9nR
         aO7HX_-SFfGQeutao2TDjDAWU4Vupk8rw9JR0AzZ0N2fvuIAmr_WCsmG
         peNqQnev1T7IyEsnh8UMt-n5CafhkikzhEsrmndH6LxOrvRJlsPp6Zv8
         bUq0k",
     "q": "uKE2dh-cTf6ERF4k4e_jy78GfPYUIaUyoSSJuBzp3Cubk3OCqs6grT
         8bR_cu0Dm1MZwWmtdqDyI95HrUeq3MP15vMMON8lHTeZu2lmKvwqW7an
         V5UzhM1iZ7z4yMkuUwFWoBvyY898EXvRD-hdqRxHlSqAZ192zB3pVFJ0
         s7pFc",
     "dp": "B8PVvXkvJrj2L-GYQ7v3y9r6Kw5g9SahXBwsWUzp19TVlgI-YV85q
         1NIb1rxQtD-IsXXR3-TanevuRPRt5OBOdiMGQp8pbt26gljYfKU_E9xn
         -RULHz0-ed9E9gXLKD4VGngpz-PfQ_q29pk5xWHoJp009Qf1HvChixRX
         59ehik",
     "dq": "CLDmDGduhylc9o7r84rEUVn7pzQ6PF83Y-iBZx5NT-TpnOZKF1pEr
         AMVeKzFEl41DlHHqqBLSM0W1sOFbwTxYWZDm6sI6og5iTbwQGIC3gnJK
         bi_7k_vJgGHwHxgPaX2PnvP-zyEkDERuf-ry4c_Z11Cq9AqC2yeL6kdK
         T1cYF8",
     "qi": "3PiqvXQN0zwMeE-sBvZgi289XP9XCQF3VWqPzMKnIgQp7_Tugo6-N
         ZBKCQsMf3HaEGBjTVJs_jcK8-TRXvaKe-7ZMaQj8VfBdYkssbu0NKDDh
         jJ-GtiseaDVWt7dcH0cfwxgFUHpQh7FoCrjFJ6h6ZEpMF6xmujs4qMpP
         z8aaI4"
   }

                    Figure 4: RSA 2048-Bit Private Key

Top      ToC       Page 10 
   The field "kty" value of "RSA" identifies this as an RSA key.  The
   fields "n" and "e" values are the base64url-encoded modulus and
   (public) exponent (respectively) using the minimum number of octets
   necessary.  The field "d" value is the base64url-encoded private
   exponent using the minimum number of octets necessary.  The fields
   "p", "q", "dp", "dq", and "qi" are the base64url-encoded additional
   private information using the minimum number of octets necessary.

   For a 2048-bit key, the field "n" is 256 octets in length when
   decoded, and the field "d" is not longer than 256 octets in length
   when decoded.

3.5.  Symmetric Key (MAC Computation)

   This example illustrates a symmetric key used for computing Message
   Authentication Codes (MACs).

   Note that whitespace is added for readability as described in
   Section 1.1.

   {
     "kty": "oct",
     "kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037",
     "use": "sig",
     "alg": "HS256",
     "k": "hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg"
   }

                   Figure 5: HMAC SHA-256 Symmetric Key

   The field "kty" value of "oct" identifies this as a symmetric key.
   The field "k" value is the symmetric key.

   When used for the signing algorithm "HS256" (HMAC-SHA256), the field
   "k" value is 32 octets (or more) in length when decoded, padded with
   leading zero (0x00) octets to reach the minimum expected length.

Top      ToC       Page 11 
3.6.  Symmetric Key (Encryption)

   This example illustrates a symmetric key used for encryption.

   Note that whitespace is added for readability as described in
   Section 1.1.

   {
     "kty": "oct",
     "kid": "1e571774-2e08-40da-8308-e8d68773842d",
     "use": "enc",
     "alg": "A256GCM",
     "k": "AAPapAv4LbFbiVawEjagUBluYqN5rhna-8nuldDvOx8"
   }

              Figure 6: AES 256-Bit Symmetric Encryption Key

   The field "kty" value of "oct" identifies this as a symmetric key.
   The field "k" value is the symmetric key.

   For the content encryption algorithm "A256GCM", the field "k" value
   is exactly 32 octets in length when decoded, padded with leading zero
   (0x00) octets to reach the expected length.



(page 11 continued on part 2)

Next RFC Part