Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7520

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

Pages: 120
Informational
Errata
Part 1 of 4 – Pages 1 to 11
None   None   Next

Top   ToC   RFC7520 - 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   ToC   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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   RFC7520 - 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 Section