Network Working Group N. Madden
Internet-Draft ForgeRock
Intended status: Standards Track May 10, 2019
Expires: November 11, 2019
Public Key Authenticated Encryption for JOSE: ECDH-1PU
draft-madden-jose-ecdh-1pu-01
Abstract
This document describes the ECDH-1PU public key authenticated
encryption algorithm for JWE. The algorithm is similar to the
existing ECDH-ES encryption algorithm, but adds an additional ECDH
key agreement between static keys of the sender and recipient. This
additional step allows the recipient to be assured of sender
authenticity without requiring a nested signed-then-encrypted message
structure. The mode is also a useful building block for constructing
interactive handshake protocols on top of JOSE.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 11, 2019.
Copyright Notice
Copyright (c) 2019 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
(https://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
Madden Expires November 11, 2019 [Page 1]
Internet-Draft JOSE ECDH-1PU May 2019
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 . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3
2. Key Agreement with Elliptic Curve Diffie-Hellman One-Pass
Unified Model (ECDH-1PU) . . . . . . . . . . . . . . . . . . 3
2.1. Header Parameters used for ECDH Key Agreement . . . . . . 4
2.1.1. "skid" Header Parameter . . . . . . . . . . . . . . . 5
2.2. Key Derivation for ECDH-1PU Key Agreement . . . . . . . . 5
3. Two-way interactive handshake . . . . . . . . . . . . . . . . 6
4. IANA considerations . . . . . . . . . . . . . . . . . . . . . 7
4.1. JSON Web Signature and Encryption Algorithms Registration 7
4.1.1. ECDH-1PU . . . . . . . . . . . . . . . . . . . . . . 8
4.2. JSON Web Signature and Encryption Header Parameters
Registration . . . . . . . . . . . . . . . . . . . . . . 8
4.2.1. skid . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Normative References . . . . . . . . . . . . . . . . . . 9
6.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Example ECDH-1PU Key Agreement Computation with
A256GCM . . . . . . . . . . . . . . . . . . . . . . 10
Appendix B. Example Interactive Handshake . . . . . . . . . . . 13
B.1. Initial message from Alice to Bob . . . . . . . . . . . . 14
B.2. Response message from Bob to Alice . . . . . . . . . . . 18
Appendix C. Document History . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction
JSON Object Signing and Encryption (JOSE) defines a number of
encryption (JWE) [RFC7516] and digital signature (JWS) [RFC7515]
algorithms. When symmetric cryptography is used, JWE provides
authenticated encryption that ensures both confidentiality and sender
authentication. However, for public key cryptography the existing
JWE encryption algorithms provide only confidentiality and some level
of ciphertext integrity. When sender authentication is required,
users must resort to nested signed-then-encrypted structures, which
increases the overhead and size of resulting messages. This document
describes an alternative encryption algorithm called ECDH-1PU that
provides public key authenticated encryption, allowing the benefits
of authenticated encryption to be enjoyed for public key JWE as it
currently is for symmetric cryptography.
Madden Expires November 11, 2019 [Page 2]
Internet-Draft JOSE ECDH-1PU May 2019
ECDH-1PU is based on the One-Pass Unified Model for Elliptic Curve
Diffie-Hellman key agreement described in [NIST.800-56A].
The advantages of public key authenticated encryption with ECDH-1PU
compared to using nested signed-then-encrypted documents include the
following:
o The resulting message size is more compact as an additional layer
of headers and base64url-encoding is avoided. A 500-byte payload
when encrypted and authenticated with ECDH-1PU (with P-256 keys
and "A256GCM" Content Encryption Method) results in a 1087-byte
JWE in Compact Encoding. An equivalent nested signed-then-
encrypted JOSE message using the same keys and encryption method
is 1489 bytes (37% larger).
o The same primitives are used for both confidentiality and
authenticity, providing savings in code size for constrained
environments.
o The generic composition of signatures and public key encryption
involves a number of subtle details that are essential to security
[PKAE]. Providing a dedicated algorithm for public key
authenticated encryption reduces complexity for users of JOSE
libraries.
o ECDH-1PU provides only authenticity and not the stronger security
properties of non-repudiation or third-party verifiability. This
can be an advantage in applications where privacy, anonymity, or
plausible deniability are goals.
1.1. Requirements Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC8174] when, and only when, they appear in all capitals, as
shown here.
2. Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified
Model (ECDH-1PU)
This section defines the specifics of key agreement with Elliptic
Curve Diffie-Hellman One-Pass Unified Model, in combination with the
one-step KDF, as defined in Section 5.8.2.1 of [NIST.800-56A] using
the Concatenation Format of Section 5.8.2.1.1. This is identical to
the ConcatKDF function used by the existing JWE ECDH-ES algorithm
defined in Section 4.6 of [RFC7518]. As for ECDH-ES, the key
agreement result can be used in one of two ways:
Madden Expires November 11, 2019 [Page 3]
Internet-Draft JOSE ECDH-1PU May 2019
1. directly as the Content Encryption Key (CEK) for the "enc"
algorithm, in the Direct Key Agreement mode, or
2. as a symmetric key used to wrap the CEK with the "A128KW",
"A192KW", or "A256KW" algorithms, in the Key Agreement with Key
Wrapping mode.
A new ephemeral public key value MUST be generated for each key
agreement operation.
In Direct Key Agreement mode, the output of the KDF MUST be a key of
the same length as that used by the "enc" algorithm. In this case,
the empty octet sequence is used as the JWE Encrypted Key value. The
"alg" (algorithm) Header Parameter value "ECDH-1PU" is used in Direct
Key Agreement mode.
In Key Agreement with Key Wrapping mode, the output of the KDF MUST
be a key of the length needed for the specified key wrapping
algorithm. In this case, the JWE Encrypted Key is the CEK wrapped
with the agreed-upon key.
The following "alg" (algorithm) Header Parameter values are used to
indicate the JWE Encrypted Key is the result of encrypting the CEK
using the result of the key agreement algorithm as the key encryption
key for the corresponding key wrapping algorithm:
+-----------------+-------------------------------------------------+
| "alg" Param | Key Management Algorithm |
| Value | |
+-----------------+-------------------------------------------------+
| ECDH-1PU+A128KW | ECDH-1PU using one-pass KDF and CEK wrapped |
| | with "A128KW" |
| ECDH-1PU+A192KW | ECDH-1PU using one-pass KDF and CEK wrapped |
| | with "A192KW" |
| ECDH-1PU+A256KW | ECDH-1PU using one-pass KDF and CEK wrapped |
| | with "A256KW" |
+-----------------+-------------------------------------------------+
2.1. Header Parameters used for ECDH Key Agreement
The "epk" (ephemeral public key), "apu" (Agreement PartyUInfo), and
"apv" (Agreement PartyVInfo) header parameters are used in ECDH-1PU
exactly as defined in Section 4.6.1 of [RFC7518].
When no other values are supplied, it is RECOMMENDED that the
producer software initializes the "apu" header to the base64url-
encoding of the SHA-256 hash of the concatenation of the sender's
static public key and the ephemeral public key, and the "apv" header
Madden Expires November 11, 2019 [Page 4]
Internet-Draft JOSE ECDH-1PU May 2019
to the base64url-encoding of the SHA-256 hash of the recipient's
static public key. This ensures that all keys involved in the key
agreement are cryptographically bound to the derived keys.
2.1.1. "skid" Header Parameter
A new Header Parameter "skid" (Sender Key ID) is registered as a hint
as to which of the sender's keys was used to authenticate the JWE.
The structure of the "skid" value is unspecified. Its value MUST be
a case-sensitive string. Use of this Header Parameter is OPTIONAL.
When used with a JWK, the "skid" value is used to match a JWK "kid"
parameter value.
2.2. Key Derivation for ECDH-1PU Key Agreement
The key derivation process derives the agreed-upon key from the
shared secret Z established through the ECDH algorithm, per
Section 6.2.1.2 of [NIST.800-56A]. For the NIST prime order curves
"P-256", "P-384", and "P-521", the ECC CDH primitive for cofactor
Diffie-Hellman defined in Section 5.7.1.2 of [NIST.800-56A] is used
(taking note that the cofactor for all these curves is 1). For
curves "X25519" and "X448" the appropriate ECDH primitive from
Section 5 of [RFC7748] is used.
Key derivation is performed using the one-step KDF, as defined in
Section 5.8.1 and Section 5.8.2.1 of [NIST.800-56A] using the
Concatenation Format of Section 5.8.2.1.1, where the Auxilary
Function H is SHA-256. The KDF parameters are set as follows:
Z This is set to the representation of the shared secret Z as an
octet sequence. As per Section 6.2.1.2 of [NIST.800-56A] Z is the
concatenation of Ze and Zs, where Ze is the shared secret derived
from applying the ECDH primitive to the sender's ephemeral private
key and the recipient's static public key. Zs is the shared
secret derived from applying the ECDH primitive to the sender's
static private key and the recipient's static public key.
keydatalen This is set to the number of bits in the desired output
key. For "ECDH-1PU", this is the length of the key used by the
"enc" algorithm. For "ECDH-1PU+A128KW", "ECDH-1PU+A192KW", and
"ECDH-1PU+A256KW", this is 128, 192, and 256, respectively.
AlgorithmID The AlgorithmID values is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big-endian 32-bit counter that
indicates the length (in octets) of Data. In the Direct Key
Agreement case, Data is set to the octets of the ASCII
representation of the "enc" Header Parameter value. In the Key
Madden Expires November 11, 2019 [Page 5]
Internet-Draft JOSE ECDH-1PU May 2019
Agreement with Key Wrapping case, Data is set to the octets of the
ASCII representation of the "alg" (algorithm) Header Parameter
value.
PartyUInfo The PartyUInfo value is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big-endian 32-bit counter that
indicates the length (in octets) of Data. If an "apu" (agreement
PartyUInfo) Header Parameter is present, Data is set to the result
of base64url decoding the "apu" value and Datalen is set to the
number of octets in Data. Otherwise, Datalen is set to 0 and Data
is set to the empty octet sequence.
PartyVInfo The PartyVInfo value is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big-endian 32-bit counter that
indicates the length (in octets) of Data. If an "apv" (agreement
PartyVInfo) Header Parameter is present, Data is set to the result
of base64url decoding the "apv" value and Datalen is set to the
number of octets in Data. Otherwise, Datalen is set to 0 and Data
is set to the empty octet sequence.
SuppPubInfo This is set to the keydatalen represented as a 32-bit
big-endian integer.
SuppPrivInfo This is set to the empty octet sequence.
Applications need to specifiy how the "apu" and "apv" Header
Parameters are used for that application. The "apu" and "apv" values
MUST be distinct, when used. Applications wishing to conform to
[NIST.800-56A] need to provide values that meet the requirements of
that doucument, e.g., by using values that identify the producer and
consumer.
See Appendix A for an example key agreement computation using this
method.
3. Two-way interactive handshake
A party that has received a JWE encrypted with ECDH-1PU MAY reply to
that message by creating a new JWE using ECDH-1PU, but using the
ephemeral public key ("epk") from the first message as if it was the
originating party's static public key. In this case, key agreement
proceeds exactly as for Section 2, but with the originator's
ephemeral public key used as the recipient (Party V) static public
key. The "alg" (algorithm) Header Parameter in the response MUST be
identical to the "alg" Header Parameter of the original message. The
Madden Expires November 11, 2019 [Page 6]
Internet-Draft JOSE ECDH-1PU May 2019
"enc" (encryption method) Header Parameter in the response MUST also
be identical to the "enc" Header Parameter of the original message.
The value of the "apu" (Agreement PartyUInfo) Header Parameter value
from the original message SHOULD be reflected as the "apv" (Agreement
PartyVInfo) Header Parameter value in the new message. Applications
need to specify how the new "apu" Header Parameter should be
constructed.
If a "kid" claim was included in the ephemeral public key of the
original message, then a "kid" Header Parameter with the same value
MUST be included in the reply JWE.
See Appendix B for an example handshake using this method.
After the initial message and a reply have been exchanged, the two
parties may communicate using the derived key from the second message
as the encryption key for any number of additional messages.
Applications MUST specify the algorithm to be used. The JWE
algorithm and encryption method used MUST use the same size key as
the derived key. For example, if the derived key is 256-bits, then
appropriate algorithms include alg=dir and enc=A256GCM, or alg=A256KW
with any JWE content encryption method.
If Direct encryption is used, the "enc" (encryption method) of all
subsequent messages MUST be identical to the "enc" Header Parameter
of the handshake messages. If the same derived key is to be used for
messages in both directions between the two parties, the application
MUST specify how unique nonces/IVs are to be generated by each party
to avoid collisions. It is RECOMMENDED that either a Key Wrap
algorithm is used, or else the derived key is used as input to a key
derivation function to derive separate keys for each direction.
4. IANA considerations
This section registers identifiers under the IANA JSON Web Signature
and Encryption Algorithms Registry established by [RFC7518] and the
IANA JSON Web Signature and Encryption Header Parameters registry
established by [RFC7515].
4.1. JSON Web Signature and Encryption Algorithms Registration
This section registers JWE algorithms as per the registry established
in [RFC7518].
Madden Expires November 11, 2019 [Page 7]
Internet-Draft JOSE ECDH-1PU May 2019
4.1.1. ECDH-1PU
Algorithm Name: "ECDH-1PU"
Algorithm Description: ECDH One-Pass Unified Model using one-pass
KDF
Algorithm Usage Location(s): "alg"
JOSE Implementation Requirements: Optional
Change Controller: IESG
Specification Document(s): Section 2
Algorithm Analysis Document(s): [NIST.800-56A] (Section 7.3),
[PKAE]
4.2. JSON Web Signature and Encryption Header Parameters Registration
This section registers new Header Parameters as per the registry
established in [RFC7515].
4.2.1. skid
Header Parameter Name: "skid"
Header Parameter Description: Sender Key ID
Header Parameter Usage Location(s): JWE
Change Controller: IESG
Specification Document(s): Section 2.1.1
5. Security Considerations
The security considerations of [RFC7516] and [RFC7518] relevant to
ECDH-ES also apply to this specification.
The security considerations of [NIST.800-56A] apply here.
When performing an ECDH key agreement between a static private key
and any untrusted public key, care should be taken to ensure that the
public key is a valid point on the same curve as the private key.
Failure to do so may result in compromise of the static private key.
For the NIST curves P-256, P-384, and P-521, appropriate validation
routines are given in Section 5.6.2.3.3 of [NIST.800-56A]. For the
curves used by X25519 and X448, consult the security considerations
of [RFC7748].
The ECDH-1PU algorithm is vulnerable to Key Compromise Impersonation
(KCI) attacks. If the long-term static private key of a party is
compromised, then the attacker can not only impersonate that party to
other parties, but also impersonate any other party when
communicating with the compromised party. The second and any
subsequent messages in the two-way interactive handshake described in
Section 3 are not vulnerable to KCI. If resistance to KCI is desired
Madden Expires November 11, 2019 [Page 8]
Internet-Draft JOSE ECDH-1PU May 2019
in a single message, then it is RECOMMENDED to use a nested JWS
signature over the content.
When Key Agreement with Key Wrapping is used, with the same Content
Encryption Key (CEK) reused for multiple recipients, any of those
recipients can produce a new message that appears to come from the
original sender. The new message will be indistinguishable from a
genuine message from the original sender to any of the other
participants. The sender SHOULD use a unique CEK for each recipient
of a message.
The security properties of the one-pass unified model are given in
Section 7.3 of [NIST.800-56A]. The ECDH-1PU scheme is also related
(but not identical) to the "K" one-way handshake pattern of the Noise
Protocol Framework. The two-way interactive handshake described in
Section 3 is also related to the "KK" two-way interactive handshake
pattern. The security properties of these handshake patterns are
given in Section 7.7 of [Noise], although it should be stressed that
many details differ between Noise and the current specification.
6. References
6.1. Normative References
[NIST.800-56A]
Barker, E., Chen, L., Roginsky, A., Vassilev, A., and R.
Davis, "Recommendation for Pair-Wise Key Establishment
Using Discrete Logarithm Cryptography Revision 3.", NIST
Special Publication 800-56A, April 2018.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015,
<https://www.rfc-editor.org/info/rfc7516>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>.
[RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves
for Security", RFC 7748, DOI 10.17487/RFC7748, January
2016, <https://www.rfc-editor.org/info/rfc7748>.
Madden Expires November 11, 2019 [Page 9]
Internet-Draft JOSE ECDH-1PU May 2019
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
6.2. Informative References
[Noise] Perrin, T., "The Noise Protocol Framework, Revision 34",
July 2018.
[PKAE] An, J., "Authenticated Encryption in the Public-Key
Setting: Security Notions and Analyses", IACR ePrint
2001/079, 2001.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>.
[RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH)
and Signatures in JSON Object Signing and Encryption
(JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017,
<https://www.rfc-editor.org/info/rfc8037>.
Appendix A. Example ECDH-1PU Key Agreement Computation with A256GCM
This example uses ECDH-1PU in Direct Key Agreement mode ("alg" value
"ECDH-1PU") to produce an agreed-upon key for AES GCM with a 256-bit
key ("enc" value "A256GCM"). The example re-uses the keys and
parameters of the example computation in Appendix C of [RFC7518],
with the addition of an extra static key-pair for Alice.
When used in this way, ECDH-1PU has similar security properties to
the "K" one-way handshake pattern of [Noise], although it is quite
different in details.
In this example, a producer Alice is encrypting content to a consumer
Bob. Alice's static key-pair (in JWK format) used for the key
agreement in this example (including the private part) is:
{"kty":"EC",
"crv":"P-256",
"x":"WKn-ZIGevcwGIyyrzFoZNBdaq9_TsqzGl96oc0CWuis",
"y":"y77t-RvAHRKTsSGdIYUfweuOvwrvDD-Q3Hv5J0fSKbE",
"d":"Hndv7ZZjs_ke8o9zXYo3iq-Yr8SewI5vrqd0pAvEPqg"}
Bob's static key-pair (in JWK format) is:
Madden Expires November 11, 2019 [Page 10]
Internet-Draft JOSE ECDH-1PU May 2019
{"kty":"EC",
"crv":"P-256",
"x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ",
"y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck",
"d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"}
The producer (Alice) generates an ephemeral key for the key agreement
computation. Alice's ephemeral key (in JWK format) is:
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps",
"d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo"}
Header Parameter values used in this example are as follows. The
"apu" (agreement PartyUInfo) Header Parameter value is the base64url
encoding of the UTF-8 string "Alice" and the "apv" (agreement
PartyVInfo) Header Parameter value is the base64url encoding of the
UTF-8 string "Bob". The "epk" (ephemeral public key) Header
Parameter is used to communicate the producer's (Alice's) ephemeral
public key value to the consumer (Bob).
{"alg":"ECDH-1PU",
"enc":"A256GCM",
"apu":"QWxpY2U",
"apv":"Qm9i",
"epk":
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps"
}
}
The resulting one-pass KDF [NIST.800-56A] parameter values are:
Ze This is set to the output of the ECDH key agreement between
Alice's ephemeral private key and Bob's static public key. In
this example, Ze is the following octet sequence (in hexadecimal
notation):
9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c
fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4
Zs This is set to the output of the ECDH key agreement between
Alice's static private key and Bob's static public key. In this
Madden Expires November 11, 2019 [Page 11]
Internet-Draft JOSE ECDH-1PU May 2019
example, Zs is the following octet sequence (in hexadecimal
notation):
e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d
41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d
Z This is set to the concatenation of Ze followed by Zs. In this
example, Z is the following octet sequence (in hexadecimal
notation):
9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c
fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4
e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d
41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d
keydatalen This value is 256 - the number of bits in the desired
output key (because "A256GCM" uses a 256-bit key).
AlgorithmID This is set to the octets representing the 32-bit big-
endian value 7 - 00 00 00 07 in hexadecimal notation - the number
of octets in the AlgorithmID content "A256GCM", followed by the
octets representing the ASCII string "A256GCM" - 41 32 35 36 47 43
4d (in hex). The complete value is therefore: 00 00 00 07 41 32
35 36 47 43 4d
PartyUInfo This is set to the octets representing the 32-bit big-
endian value 5, followed by the octets representing the UTF-8
string "Alice". In hexadecimal notation: 00 00 00 05 41 6c 69 63
65
PartyVInfo This is set to the octets representing the 32-bit big-
endian value 3, followed by the octets representing the UTF-8
string "Bob". In hexadecimal notation: 00 00 00 03 42 6f 62
SuppPubInfo This is set to the octets representing the 32-bit big-
endian value 256 - the keydatalen value. In hexadecimal notation:
00 00 01 00
SuppPrivInfo This is set to the empty octet sequence.
Concatenating the parameters AlgorithmID through SuppPrivInfo results
in a FixedInfo value in Concatenation Format (as per
Section 5.8.2.1.1 of [NIST.800-56A]) of (in hexidecimal notation):
00 00 00 07 41 32 35 36 47 43 4d 00 00 00 05 41
6c 69 63 65 00 00 00 03 42 6f 62 00 00 01 00
Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo
value results in a one-pass KDF round 1 hash input of (hexadecimal):
Madden Expires November 11, 2019 [Page 12]
Internet-Draft JOSE ECDH-1PU May 2019
00 00 00 01 9e 56 d9 1d 81 71 35 d3 72 83 42 83
bf 84 26 9c fb 31 6e a3 da 80 6a 48 f6 da a7 79
8c fe 90 c4 e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c
68 8b 3e 7d 41 10 a1 b4 ba dc 3c c5 4e f7 b8 12
41 ef d5 0d 00 00 00 07 41 32 35 36 47 43 4d 00
00 00 05 41 6c 69 63 65 00 00 00 03 42 6f 62 00
00 01 00
The resulting derived key, which is the full 256 bits of the round 1
hash output is:
6c af 13 72 3d 14 85 0a d4 b4 2c d6 dd e9 35 bf
fd 2f ff 00 a9 ba 70 de 05 c2 03 a5 e1 72 2c a7
The base64url-encoded representation of this derived key is:
bK8Tcj0UhQrUtCzW3ek1v_0v_wCpunDeBcIDpeFyLKc
Appendix B. Example Interactive Handshake
This example use ECDH-1PU in Direct Key Agreement mode using the X448
curve from [RFC8037] to perform a two-way interactive handshake.
When used in this way, ECDH-1PU has similar security properties to
the "KK" interactive handshake pattern of [Noise]. Messages are
encrypted using the "A256GCM" encryption method ("enc" Header
Parameter value).
In this example, a producer Alice is encrypting content to a consumer
Bob. Alice's static key-pair (in JWK format) including the private
key part is (with linebreaks added for display purposes only):
{"kty":"OKP",
"kid":"alice-static",
"crv": "X448",
"x":"qaggoGo7qFwBrBtxv4hwI09UaiQmCrF1KdHvaXrzjzzInqDD0Cfx9GlGFi2367
RATs-hBoB2IHw",
"d":"hJW9knOYfyCIkZnW922U81uDNNfAwcVeNcpbaQIKyh0iW5LSpDLSmBdPSyvOh7
J4u9hArU2uoX0"}
Bob's static key-pair (in JWK format) including the private key part
is (with linebreaks added for display purposes only):
Madden Expires November 11, 2019 [Page 13]
Internet-Draft JOSE ECDH-1PU May 2019
{"kty":"OKP",
"kid":"bob-static",
"crv":"X448",
"x":"4jvO2Ef15DErhV5_5OzoaZDQ2tVb_jHB09eNruOkCTETatzOZ2EGgJCkXNElWR
sLnbns3TtYYSY",
"d":"HGKc9R7_Zso3BCnrhzA9GzOzHKHOkMYvb_n54aJ1qkO1qYYTEUS0OQmBZTq1NK
R5_kmiX5e5r-I"}
B.1. Initial message from Alice to Bob
Alice generates an ephemeral key-pair for her handshake with Bob.
Alice's ephemeral key-pair in JWK format is (with linebreaks added
for display purposes only):
{"kty":"OKP",
"kid":"alice-ephemeral",
"crv":"X448",
"x":"6DRxSemaGVx1iVEPRyOAcTKS2zJsi0oZ9bR-IhZUJtezxjSXroVoDTf-RVYBjS
XdwkLOIGKSI74",
"d":"8epzr7H0N7ZIIOZeNckLL3iAHfSmIDeb-cMSgI8PJzyQfjZB0tHoGFtkQG7cAK
xP0Fi6Bbfbe7I"}
The following JWE Protected Header is used for the message (with line
breaks and whitespace added for display purposes):
{"typ":"JWT",
"epk":{
"kty":"OKP",
"crv":"X448",
"x":"6DRxSemaGVx1iVEPRyOAcTKS2zJsi0oZ9bR-IhZUJtezxjSXroVoDTf-RVYB
jSXdwkLOIGKSI74"},
"apv":"Qm9i",
"apu":"QWxpY2U",
"kid":"bob-static",
"enc":"A256GCM",
"alg":"ECDH-1PU"}
After removing all whitespace, the octets of ASCII(BASE64URL(UTF8(JWE
Protected Header))) are as follows (in hexadecimal notation):
Madden Expires November 11, 2019 [Page 14]
Internet-Draft JOSE ECDH-1PU May 2019
65 79 4a 30 65 58 41 69 4f 69 4a 4b 56 31 51 69
4c 43 4a 6c 63 47 73 69 4f 6e 73 69 61 33 52 35
49 6a 6f 69 54 30 74 51 49 69 77 69 59 33 4a 32
49 6a 6f 69 57 44 51 30 4f 43 49 73 49 6e 67 69
4f 69 49 32 52 46 4a 34 55 32 56 74 59 55 64 57
65 44 46 70 56 6b 56 51 55 6e 6c 50 51 57 4e 55
53 31 4d 79 65 6b 70 7a 61 54 42 76 57 6a 6c 69
55 69 31 4a 61 46 70 56 53 6e 52 6c 65 6e 68 71
55 31 68 79 62 31 5a 76 52 46 52 6d 4c 56 4a 57
57 55 4a 71 55 31 68 6b 64 32 74 4d 54 30 6c 48
53 31 4e 4a 4e 7a 51 69 66 53 77 69 59 58 42 32
49 6a 6f 69 55 57 30 35 61 53 49 73 49 6d 46 77
64 53 49 36 49 6c 46 58 65 48 42 5a 4d 6c 55 69
4c 43 4a 72 61 57 51 69 4f 69 4a 69 62 32 49 74
63 33 52 68 64 47 6c 6a 49 69 77 69 5a 57 35 6a
49 6a 6f 69 51 54 49 31 4e 6b 64 44 54 53 49 73
49 6d 46 73 5a 79 49 36 49 6b 56 44 52 45 67 74
4d 56 42 56 49 6e 30
The resulting one-pass KDF [NIST.800-56A] parameter values are:
Ze This is set to the output of the X448 key agreement between
Alice's ephemeral private key and Bob's static public key. In
this example, Ze is the following octet sequence (in hexadecimal
notation):
4c b2 b9 11 cd 1c 0a 69 d2 89 4f 39 3b 94 34 29
61 02 40 f4 19 fc 09 2e bc 06 eb a2 c8 27 17 33
d2 7d ea 64 c8 b6 4d 66 de c1 db ce 6d de a1 b3
a5 d3 12 c7 9a 0c e1 47
Zs This is set to the output of the X448 key agreement between
Alice's static private key and Bob's static public key. In this
example, Zs is the following octet sequence (in hexadecimal
notation):
d8 8e aa 18 61 a4 8e a4 69 7b e0 99 c6 bc 3b 73
4f 0e 13 6d ed e7 75 d3 f3 a2 f4 86 b7 47 ba f0
e0 39 b1 b6 c1 62 84 07 86 52 0c ff 0c 69 58 db
ff a5 06 0c 08 5e 77 38
Z This is set to the concatenation of Ze followed by Zs. In this
example, Z is the following octet sequence (in hexadecimal
notation):
Madden Expires November 11, 2019 [Page 15]
Internet-Draft JOSE ECDH-1PU May 2019
4c b2 b9 11 cd 1c 0a 69 d2 89 4f 39 3b 94 34 29
61 02 40 f4 19 fc 09 2e bc 06 eb a2 c8 27 17 33
d2 7d ea 64 c8 b6 4d 66 de c1 db ce 6d de a1 b3
a5 d3 12 c7 9a 0c e1 47 d8 8e aa 18 61 a4 8e a4
69 7b e0 99 c6 bc 3b 73 4f 0e 13 6d ed e7 75 d3
f3 a2 f4 86 b7 47 ba f0 e0 39 b1 b6 c1 62 84 07
86 52 0c ff 0c 69 58 db ff a5 06 0c 08 5e 77 38
keydatalen This value is 256, because "A256GCM" uses a 256-bit key.
AlgorithmID This is set to the octets representing the 32-bit big-
endian value 7 followed by the octets representing the ASCII
string "A256GCM". In hexadecimal notation: 00 00 00 07 41 32 35
36 47 43 4d
PartyUInfo This is set to the octets representing the 32-bit big-
endian value 5 followed by the octets representing the UTF-8
string "Alice". In hexadecimal notation: 00 00 00 05 41 6c 69 63
65
PartyVInfo This is set to the octets representing the 32-bit big-
endian value 3 followed by the octets representing the UTF-8
string "Bob". In hexadecimal notation: 00 00 00 03 42 6f 62
SuppPubInfo This is set to the octets representing the 32-bit big
endian value 256 - the keydatalen value. In hexadecimal: 00 00 01
00
SuppPrivInfo This is set to the empty octet sequence.
Concatenating the parameters AlgorithmID through SuppPubInfo results
in a FixedInfo value of (in hex):
00 00 00 07 41 32 35 36 47 43 4d 00 00 00 05 41
6c 69 63 65 00 00 00 03 42 6f 62 00 00 01 00
Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo
value results in the KDF round 1 hash input of:
00 00 00 01 4c b2 b9 11 cd 1c 0a 69 d2 89 4f 39
3b 94 34 29 61 02 40 f4 19 fc 09 2e bc 06 eb a2
c8 27 17 33 d2 7d ea 64 c8 b6 4d 66 de c1 db ce
6d de a1 b3 a5 d3 12 c7 9a 0c e1 47 d8 8e aa 18
61 a4 8e a4 69 7b e0 99 c6 bc 3b 73 4f 0e 13 6d
ed e7 75 d3 f3 a2 f4 86 b7 47 ba f0 e0 39 b1 b6
c1 62 84 07 86 52 0c ff 0c 69 58 db ff a5 06 0c
08 5e 77 38 00 00 00 07 41 32 35 36 47 43 4d 00
00 00 05 41 6c 69 63 65 00 00 00 03 42 6f 62 00
00 01 00
The resulting derived key, which is the full 256-bits of the round 1
hash output is:
Madden Expires November 11, 2019 [Page 16]
Internet-Draft JOSE ECDH-1PU May 2019
3e 22 44 01 ab cf 8b 1a 93 63 bd 2b 6c 8e 85 c4
e0 c7 b9 8c ad 3b 51 aa 3f 04 a4 9d 0c 29 da 0c
Alice then generates a random 96-bit Initialization Vector (IV) for
A256GCM. In hexadecimal format:
3b c5 10 62 97 3c 45 8d 5a 6f 2d 8d
Alice uses the derived key and the IV to encrypt and authenticate the
following plaintext JWT Claims Set [RFC7519], with the octets of the
encoded JWE Protected Header as the Additional Authenticated Data.
{"msg":"Hello Mike","aud":"Bob","iss":"Alice"}
In hexadecimal notation, the UTF-8 bytes of this plaintext are:
7b 22 6d 73 67 22 3a 22 48 65 6c 6c 6f 20 4d 69
6b 65 22 2c 22 61 75 64 22 3a 22 42 6f 62 22 2c
22 69 73 73 22 3a 22 41 6c 69 63 65 22 7d
The resulting Authentication Tag value is:
4b 39 e8 a7 70 ec eb e3 46 f4 af 77 af 22 4f 42
The JWE Ciphertext is:
b5 bd c4 83 44 54 be 02 04 f6 b5 d5 cd 9c 0d f6
95 57 ab d9 4b ba d4 4f f4 70 0e 57 55 a2 c0 fc
21 ca 63 56 38 93 7b fb 06 3e 60 f4 a4 cb
Alice assembles the complete message in JWE Compact Serialization
format and sends it to Bob (with line breaks added for display
purposes only):
eyJ0eXAiOiJKV1QiLCJlcGsiOnsia3R5IjoiT0tQIiwiY3J
2IjoiWDQ0OCIsIngiOiI2RFJ4U2VtYUdWeDFpVkVQUnlPQW
NUS1MyekpzaTBvWjliUi1JaFpVSnRlenhqU1hyb1ZvRFRmL
VJWWUJqU1hkd2tMT0lHS1NJNzQifSwiYXB2IjoiUW05aSIs
ImFwdSI6IlFXeHBZMlUiLCJraWQiOiJib2Itc3RhdGljIiw
iZW5jIjoiQTI1NkdDTSIsImFsZyI6IkVDREgtMVBVIn0..O
8UQYpc8RY1aby2N.tb3Eg0RUvgIE9rXVzZwN9pVXq9lLutR
P9HAOV1WiwPwhymNWOJN7-wY-YPSkyw.Sznop3Ds6-NG9K9
3ryJPQg
The message is 383 octets in size.
Madden Expires November 11, 2019 [Page 17]
Internet-Draft JOSE ECDH-1PU May 2019
B.2. Response message from Bob to Alice
Bob receives the message from Alice and decrypts it, using Alice's
(known) static public key to authenticate that the message did indeed
come from Alice. Bob wishes to establish an interactive secure
channel with Alice, so replies to her message using the ephemeral key
from her initial message as Alice's public key.
Bob generates a fresh ephemeral key-pair of his own. In this
example, Bob's ephemeral key-pair (in JWK format) is as follows,
including the private key parts (with linebreaks added for display
purposes only):
{"kty":"OKP",
"kid":"bob-ephemeral",
"crv":"X448",
"x":"_a4lG0EVO62pyVyuGjCIzHYII7vjEBqf02CcNMCHUjWvRMKbkZB-XQ0uzhByXl
jx0bNgpAvmf84",
"d":"bNy3py2jvaYOnnzkxV3nOYazDEWTeEOEtTGK7eH-Cjp_m4uCOS-AYqmcUDJCyG
uFj340p3ld0NA"}
Bob generates the following JWE Protected Header for his reply to
Alice (with line breaks and whitespace added for display only):
{"typ":"JWT",
"epk":{
"kty":"OKP",
"crv":"X448",
"x":"_a4lG0EVO62pyVyuGjCIzHYII7vjEBqf02CcNMCHUjWvRMKbkZB-XQ0uzhBy
Xljx0bNgpAvmf84"},
"apv":"QWxpY2U",
"apu":"Qm9i",
"kid":"alice-ephemeral",
"enc":"A256GCM",
"alg":"ECDH-1PU"}
After removing all whitespace, the octets of ASCII(BASE64URL(UTF8(JWE
Protected Header))) are as follows (in hexadecimal notation):
Madden Expires November 11, 2019 [Page 18]
Internet-Draft JOSE ECDH-1PU May 2019
65 79 4a 30 65 58 41 69 4f 69 4a 4b 56 31 51 69
4c 43 4a 6c 63 47 73 69 4f 6e 73 69 61 33 52 35
49 6a 6f 69 54 30 74 51 49 69 77 69 59 33 4a 32
49 6a 6f 69 57 44 51 30 4f 43 49 73 49 6e 67 69
4f 69 4a 66 59 54 52 73 52 7a 42 46 56 6b 38 32
4d 6e 42 35 56 6e 6c 31 52 32 70 44 53 58 70 49
57 55 6c 4a 4e 33 5a 71 52 55 4a 78 5a 6a 41 79
51 32 4e 4f 54 55 4e 49 56 57 70 58 64 6c 4a 4e
53 32 4a 72 57 6b 49 74 57 46 45 77 64 58 70 6f
51 6e 6c 59 62 47 70 34 4d 47 4a 4f 5a 33 42 42
64 6d 31 6d 4f 44 51 69 66 53 77 69 59 58 42 32
49 6a 6f 69 55 56 64 34 63 46 6b 79 56 53 49 73
49 6d 46 77 64 53 49 36 49 6c 46 74 4f 57 6b 69
4c 43 4a 72 61 57 51 69 4f 69 4a 68 62 47 6c 6a
5a 53 31 6c 63 47 68 6c 62 57 56 79 59 57 77 69
4c 43 4a 6c 62 6d 4d 69 4f 69 4a 42 4d 6a 55 32
52 30 4e 4e 49 69 77 69 59 57 78 6e 49 6a 6f 69
52 55 4e 45 53 43 30 78 55 46 55 69 66 51 3d 3d
The resulting KDF parameter values are:
Ze This is set to the output of the X448 key agreement between Bob's
ephemeral private key and Alice's ephemeral public key (from the
first message). Note that this is an ephemeral-ephemeral key
agreement. In hexadecimal notation:
66 83 28 4e 27 bf 2c e9 02 e1 e1 5d 51 de 25 d7
86 21 c7 ee 68 21 0e 55 3f c9 3e 9f cd c3 7f f1
92 b9 c5 35 c2 a2 bc ee bd 03 48 79 82 f9 fb f9
5b d2 c6 88 c8 5c 05 71
Zs This is set to the output of the X448 key agreement between Bob's
static private key and Alice's ephemeral public key from the first
message. In hexadecimal notation:
4c b2 b9 11 cd 1c 0a 69 d2 89 4f 39 3b 94 34 29
61 02 40 f4 19 fc 09 2e bc 06 eb a2 c8 27 17 33
d2 7d ea 64 c8 b6 4d 66 de c1 db ce 6d de a1 b3
a5 d3 12 c7 9a 0c e1 47
Z Z is the concatenation of Ze and Zs:
Madden Expires November 11, 2019 [Page 19]
Internet-Draft JOSE ECDH-1PU May 2019
66 83 28 4e 27 bf 2c e9 02 e1 e1 5d 51 de 25 d7
86 21 c7 ee 68 21 0e 55 3f c9 3e 9f cd c3 7f f1
92 b9 c5 35 c2 a2 bc ee bd 03 48 79 82 f9 fb f9
5b d2 c6 88 c8 5c 05 71 4c b2 b9 11 cd 1c 0a 69
d2 89 4f 39 3b 94 34 29 61 02 40 f4 19 fc 09 2e
bc 06 eb a2 c8 27 17 33 d2 7d ea 64 c8 b6 4d 66
de c1 db ce 6d de a1 b3 a5 d3 12 c7 9a 0c e1 47
keydatalen This is the value 256.
AlgorithmID This is set to the octets representing the 32-bit big-
endian value 7 followed by the octets representing the ASCII
string "A256GCM". In hexadecimal notation: 00 00 00 07 41 32 35
36 47 43 4d
PartyUInfo This is set to the octets representing the 32-bit big-
endian value 3 followed by the octets representing the UTF-8
string "Bob". In hexadecimal notation: 00 00 00 03 42 6f 62
PartyVInfo Bob echoes back Alice's PartyUInfo as the new PartyVInfo:
00 00 00 05 41 6c 69 63 65
SuppPubInfo This is set to the octets representing the 32-bit big
endian value 256 - the keydatalen value. In hexadecimal: 00 00 01
00
SuppPrivInfo This is set to the empty octet sequence.
Concatenating the parameters AlgorithmID through SuppPubInfo results
in a FixedInfo value of (in hex):
00 00 00 07 41 32 35 36 47 43 4d 00 00 00 03 42
6f 62 00 00 00 05 41 6c 69 63 65 00 00 01 00
Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo
value results in the KDF round 1 hash input of:
00 00 00 01 66 83 28 4e 27 bf 2c e9 02 e1 e1 5d
51 de 25 d7 86 21 c7 ee 68 21 0e 55 3f c9 3e 9f
cd c3 7f f1 92 b9 c5 35 c2 a2 bc ee bd 03 48 79
82 f9 fb f9 5b d2 c6 88 c8 5c 05 71 4c b2 b9 11
cd 1c 0a 69 d2 89 4f 39 3b 94 34 29 61 02 40 f4
19 fc 09 2e bc 06 eb a2 c8 27 17 33 d2 7d ea 64
c8 b6 4d 66 de c1 db ce 6d de a1 b3 a5 d3 12 c7
9a 0c e1 47 00 00 00 07 41 32 35 36 47 43 4d 00
00 00 03 42 6f 62 00 00 00 05 41 6c 69 63 65 00
00 01 00
The resulting derived key, which is the full 256-bits of the round 1
hash output is:
7c 22 e5 61 29 89 74 7f 4e d3 b1 94 30 e1 7d 3c
98 14 5c 77 15 5c 71 6a 9d 5d f8 5b ea dd 79 02
Madden Expires November 11, 2019 [Page 20]
Internet-Draft JOSE ECDH-1PU May 2019
Bob then generates a random 96-bit IV for A256GCM. In hexadecimal
format:
cd 9f b1 e1 48 cc d8 44 2e 5a a7 49
Bob uses the derived key and the IV to encrypt and authenticate the
following plaintext JWT Claims Set, with the octets of the encoded
JWE Protected Header as the Additional Authenticated Data.
{"msg":"Hello Joe","aud":"Alice","iss":"Bob"}
In hexadecimal notation, the UTF-8 bytes of this plaintext are:
7b 22 6d 73 67 22 3a 22 48 65 6c 6c 6f 20 4a 6f
65 22 2c 22 61 75 64 22 3a 22 41 6c 69 63 65 22
2c 22 69 73 73 22 3a 22 42 6f 62 22 7d
The resulting Authentication Tag value is:
89 4c a4 f1 a7 7a d0 7b f0 d4 7c da 65 8b d3 95
The JWE Ciphertext is:
02 0d 16 b0 17 d4 8e 04 d2 f4 04 17 09 17 6a 6c
15 57 39 57 c8 ad 16 0c b4 b8 f1 c1 50 18 7d a1
ef cc b2 d1 da 6b 92 b0 32 bb a1 8b 64
Bob assembles the complete message in JWE Compact Serialization
format and sends it to Alice (with line breaks added for display
purposes only):
eyJ0eXAiOiJKV1QiLCJlcGsiOnsia3R5IjoiT0tQIiwiY3J
2IjoiWDQ0OCIsIngiOiJfYTRsRzBFVk82MnB5Vnl1R2pDSX
pIWUlJN3ZqRUJxZjAyQ2NOTUNIVWpXdlJNS2JrWkItWFEwd
XpoQnlYbGp4MGJOZ3BBdm1mODQifSwiYXB2IjoiUVd4cFky
VSIsImFwdSI6IlFtOWkiLCJraWQiOiJhbGljZS1lcGhlbWV
yYWwiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiRUNESC0xUF
UifQ..zZ-x4UjM2EQuWqdJ.Ag0WsBfUjgTS9AQXCRdqbBVX
OVfIrRYMtLjxwVAYfaHvzLLR2muSsDK7oYtk.iUyk8ad60H
vw1HzaZYvTlQ
Appendix C. Document History
-01 Added examples in Appendix A and Appendix B. Added "skid"
Header Parameter and registration. Fleshed out Security
Considerations.
Madden Expires November 11, 2019 [Page 21]
Internet-Draft JOSE ECDH-1PU May 2019
Author's Address
Neil Madden
ForgeRock
Broad Quay House
Prince Street
Bristol BS1 4DJ
United Kingdom
Email: neil.madden@forgerock.com
Madden Expires November 11, 2019 [Page 22]