RFC 7520
Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE)
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.
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
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
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
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.
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).
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.
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.
{ "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
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.
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)
