Internet DRAFT - draft-bastian-jose-alg-ecdh-mac
draft-bastian-jose-alg-ecdh-mac
Javascript Object Signing and Encryption P. Bastian
Internet-Draft Bundesdruckerei GmbH
Intended status: Informational 17 January 2024
Expires: 20 July 2024
JOSE algorithms for ECDH-MAC-based signatures
draft-bastian-jose-alg-ecdh-mac-01
Abstract
This specification defines a JSON Web Algorithm for JOSE, that uses a
combination of key agreement and MAC to construct a signature-like
mechanism.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://paulbastian.github.io/paulbastian-jose-ecdh-mac-algorithms/
draft-bastian-jose-alg-ecdh-mac.html. Status information for this
document may be found at https://datatracker.ietf.org/doc/draft-
bastian-jose-alg-ecdh-mac/.
Discussion of this document takes place on the Javascript Object
Signing and Encryption Working Group mailing list
(mailto:jose@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/jose/. Subscribe at
https://www.ietf.org/mailman/listinfo/jose/.
Source for this draft and an issue tracker can be found at
https://github.com/paulbastian/paulbastian-jose-ecdh-mac-algorithms.
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."
Bastian Expires 20 July 2024 [Page 1]
Internet-Draft ECDH-MAC for JOSE January 2024
This Internet-Draft will expire on 20 July 2024.
Copyright Notice
Copyright (c) 2024 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 include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Cryptographic Algorithm . . . . . . . . . . . . . . . . . . . 3
5.1. Header parameter "alg" . . . . . . . . . . . . . . . . . 4
5.2. Header parameter "epk" . . . . . . . . . . . . . . . . . 5
5.3. Header parameter "x5c" . . . . . . . . . . . . . . . . . 5
5.4. Header parameter "kid" . . . . . . . . . . . . . . . . . 5
5.5. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 5
6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. Normative References . . . . . . . . . . . . . . . . . . . . 6
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
1. Introduction
JWS defines cryptographic algorithms to digitally sign or create
Message Authentication Codes (MAC) of the contents of the JWS
Protected Header and the JWS Payload in Section-3 [RFC7518]. JWS
also offers ephemeral-static Elliptic Curve Diffie-Hellman key
exchange in combination with a key derivation function ("ECDH-ES" and
its variations) as a mechanism for key management in Section-4.6
[RFC7518], however these are only used for symmetric encryption.
This specification describes a combination of an ECDH key exchange
with a MAC, that enables a feature set that is similar to digital
signatures with repudiation.
Bastian Expires 20 July 2024 [Page 2]
Internet-Draft ECDH-MAC for JOSE January 2024
This specification and all described algorithms should respect the
efforts for Fully Specified Algorithms
(https://www.ietf.org/archive/id/draft-jones-jose-fully-specified-
algorithms-00.html).
This algorithm is intended for use with digital credentials
ecosystems, including the Issuer-Holder-Verifier model described by
W3C VCDM or IETF SD-JWT-VC.
2. Conventions and Definitions
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 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Terminology
Generating Party: The Party that performs the key agreement first
and generates the MAC. Similar to a Signer.
Verifying Party: The Party that performs the key agreement second,
generates the MAC and compares it to a given value. Similar to a
Verifier.
4. Parameters
For the generation of an ECDH-based MAC the following parameters must
be chosen:
1. the domain parameters for the ECDH "curve"
2. the key derivation algorithm "kd"
3. the MAC algorithm "mac"
In general, these parameters are chosen by the Generating Party.
These parameters need to be communicated to the Verifying Party
before the generation of an ECDH-based MAC.
5. Cryptographic Algorithm
The generation of the ECDH-based MAC takes the private key of the
Generating Party and the public key of the Verifying Party as inputs.
The retrieval and communication of the Verifying Party's public key
is out of scope of this specification and subject to the implementing
protocols.
Bastian Expires 20 July 2024 [Page 3]
Internet-Draft ECDH-MAC for JOSE January 2024
The generation of ECDH-based MAC follows these steps:
1. Perform ECDH as defined as defined by "curve" - use the specified
elliptic curve to generate a key pair and set the epk - use the
Verifier's public key defined by kid to perform the key agreement
- optionally provide a certificate chain defined by x5c
2. Derive symmetric key as defined by "kd" - use the output from the
key agreement as an input for the key derivation algorithm -
derive the MAC key
3. Generate a MAC as defined by "mac" - use the output from the key
derivation algorithm as an input for the MAC algorithm - generate
the MAC
The verification of ECDH-based MAC follows these steps:
1. Perform ECDH as defined as defined by "curve" - use the specified
elliptic curve to generate an ephemeral key pair and set the kid
- provide the public key kid to the Generating Party - use the
Generating Party's public key defined by epk and perform the key
agreement - optionally validate the certificate chain defined by
x5c
2. Derive symmetric key as defined by "kd" - use the output from the
key agreement as an input for the key derivation algorithm -
derive the MAC key
3. Generate a MAC as defined by "mac" - use the output from the key
derivation algorithm as an input for the MAC algorithm - generate
the MAC - compare the generated MAC with the signature value
5.1. Header parameter "alg"
The following values MUST be used for the "alg" header parameter:
+--------------------+--------------------------------+----------------+
| Algorithm Name | Algorithm Explanation | Implementation |
| | | Requirements |
+--------------------+--------------------------------+----------------+
| ECDH-P256-CC-HS256 | ECDH using NIST P-256, | Optional |
| | ConcatKDF and | |
| | HMAC using SHA-256 | |
| ECDH-BP256-CC-HS256| ECDH using BrainpoolP256r1, | Optional |
| | ConcatKDF and | |
| | HMAC using SHA-256 | |
+--------------------+--------------------------------+----------------+
Bastian Expires 20 July 2024 [Page 4]
Internet-Draft ECDH-MAC for JOSE January 2024
Other algorithms SHOULD follow the naming ECDH-<elliptic curve domain
parameters>-<KD algorithm>-<MAC algorithm>.
5.2. Header parameter "epk"
The "epk" (ephemeral public key) value is created by the Generating
Party for the use in the key agreement algorithm. This header
parameter MUST be present and MUST contain the Generating Party's
public key represented as a JSON Web Key according to [RFC7517]. It
MUST contain only public key parameters and SHOULD contain only the
minimum JWK parameters necessary to represent the key. Other JWK
parameters included may be checked for consistency or may be ignored.
5.3. Header parameter "x5c"
The "x5c" (X.509 certificate chain) value is created by the
Generating Party for the trust management of the "epk". This header
parameter is OPTIONAL and if present MUST contain the X.509
certificate chain with the JWK from "epk" being the public key of the
leaf certificate. Alternatively, the Generating Party may use "x5t",
x5t#S256" or "x5u".
5.4. Header parameter "kid"
The "kid" (key identifier) value is created by the Generating Party
for the use in the key agreement algorithm. This header parameter
MUST be present and MUST contain the Verifying Party's public key ID
user by the Generating Party for the ECDH.
5.5. Example JWT
The JWT/JWS header:
{
"typ" : "JWT",
"alg" : "ECDH-P256-HS256",
"x5c" : <issuer certificate chain that signs the epk>,
"epk" : <JWK used for ECDH>,
"kid" : <key ID of Verifying Party>
}
The JWT/JWS payload:
Bastian Expires 20 July 2024 [Page 5]
Internet-Draft ECDH-MAC for JOSE January 2024
{
"iss" : "https://example.as.com",
"iat" : "1701870613",
"given_name" : "Erika",
"family_name" : "Mustermann"
}
The JWT/JWS signature:
base64-encoded MAC
6. Security Considerations
TODO Security
7. IANA Considerations
This document has no IANA actions.
8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015,
<https://www.rfc-editor.org/rfc/rfc7517>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/rfc/rfc7518>.
[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/rfc/rfc8174>.
Acknowledgments
TODO acknowledge.
Author's Address
Paul Bastian
Bundesdruckerei GmbH
Email: bastianpaul@googlemail.com
Bastian Expires 20 July 2024 [Page 6]