2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
4 * Licensed under the OpenSSL license (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
10 /* APIs and data structures for HPKE (RFC9180) */
15 # include <openssl/types.h>
18 # define OSSL_HPKE_MODE_BASE 0 /* Base mode */
19 # define OSSL_HPKE_MODE_PSK 1 /* Pre-shared key mode */
20 # define OSSL_HPKE_MODE_AUTH 2 /* Authenticated mode */
21 # define OSSL_HPKE_MODE_PSKAUTH 3 /* PSK+authenticated mode */
24 * Max for ikm, psk, pskid, info and exporter contexts.
25 * RFC9180, section 7.2.1 RECOMMENDS 64 octets but we have test vectors from
26 * Appendix A.6.1 with a 66 octet IKM so we'll allow that.
28 # define OSSL_HPKE_MAX_PARMLEN 66
29 # define OSSL_HPKE_MAX_INFOLEN 1024
32 * The (16bit) HPKE algorithm ID IANA codepoints
33 * If/when new IANA codepoints are added there are tables in
34 * crypto/hpke/hpke_util.c that must also be updated.
36 # define OSSL_HPKE_KEM_ID_RESERVED 0x0000 /* not used */
37 # define OSSL_HPKE_KEM_ID_P256 0x0010 /* NIST P-256 */
38 # define OSSL_HPKE_KEM_ID_P384 0x0011 /* NIST P-384 */
39 # define OSSL_HPKE_KEM_ID_P521 0x0012 /* NIST P-521 */
40 # define OSSL_HPKE_KEM_ID_X25519 0x0020 /* Curve25519 */
41 # define OSSL_HPKE_KEM_ID_X448 0x0021 /* Curve448 */
43 # define OSSL_HPKE_KDF_ID_RESERVED 0x0000 /* not used */
44 # define OSSL_HPKE_KDF_ID_HKDF_SHA256 0x0001 /* HKDF-SHA256 */
45 # define OSSL_HPKE_KDF_ID_HKDF_SHA384 0x0002 /* HKDF-SHA384 */
46 # define OSSL_HPKE_KDF_ID_HKDF_SHA512 0x0003 /* HKDF-SHA512 */
48 # define OSSL_HPKE_AEAD_ID_RESERVED 0x0000 /* not used */
49 # define OSSL_HPKE_AEAD_ID_AES_GCM_128 0x0001 /* AES-GCM-128 */
50 # define OSSL_HPKE_AEAD_ID_AES_GCM_256 0x0002 /* AES-GCM-256 */
51 # define OSSL_HPKE_AEAD_ID_CHACHA_POLY1305 0x0003 /* Chacha20-Poly1305 */
52 # define OSSL_HPKE_AEAD_ID_EXPORTONLY 0xFFFF /* export-only fake ID */
54 /* strings for suite components */
55 # define OSSL_HPKE_KEMSTR_P256 "P-256" /* KEM id 0x10 */
56 # define OSSL_HPKE_KEMSTR_P384 "P-384" /* KEM id 0x11 */
57 # define OSSL_HPKE_KEMSTR_P521 "P-521" /* KEM id 0x12 */
58 # define OSSL_HPKE_KEMSTR_X25519 "X25519" /* KEM id 0x20 */
59 # define OSSL_HPKE_KEMSTR_X448 "X448" /* KEM id 0x21 */
60 # define OSSL_HPKE_KDFSTR_256 "hkdf-sha256" /* KDF id 1 */
61 # define OSSL_HPKE_KDFSTR_384 "hkdf-sha384" /* KDF id 2 */
62 # define OSSL_HPKE_KDFSTR_512 "hkdf-sha512" /* KDF id 3 */
63 # define OSSL_HPKE_AEADSTR_AES128GCM "aes-128-gcm" /* AEAD id 1 */
64 # define OSSL_HPKE_AEADSTR_AES256GCM "aes-256-gcm" /* AEAD id 2 */
65 # define OSSL_HPKE_AEADSTR_CP "chacha20-poly1305" /* AEAD id 3 */
66 # define OSSL_HPKE_AEADSTR_EXP "exporter" /* AEAD id 0xff */
69 uint16_t kem_id
; /* Key Encapsulation Method id */
70 uint16_t kdf_id
; /* Key Derivation Function id */
71 uint16_t aead_id
; /* AEAD alg id */
75 * Suite constants, use this like:
76 * OSSL_HPKE_SUITE myvar = OSSL_HPKE_SUITE_DEFAULT;
78 # define OSSL_HPKE_SUITE_DEFAULT \
80 OSSL_HPKE_KEM_ID_X25519, \
81 OSSL_HPKE_KDF_ID_HKDF_SHA256, \
82 OSSL_HPKE_AEAD_ID_AES_GCM_128 \
85 typedef struct ossl_hpke_ctx_st OSSL_HPKE_CTX
;
87 OSSL_HPKE_CTX
*OSSL_HPKE_CTX_new(int mode
, OSSL_HPKE_SUITE suite
,
88 OSSL_LIB_CTX
*libctx
, const char *propq
);
89 void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX
*ctx
);
91 int OSSL_HPKE_encap(OSSL_HPKE_CTX
*ctx
,
92 unsigned char *enc
, size_t *enclen
,
93 const unsigned char *pub
, size_t publen
,
94 const unsigned char *info
, size_t infolen
);
95 int OSSL_HPKE_seal(OSSL_HPKE_CTX
*ctx
,
96 unsigned char *ct
, size_t *ctlen
,
97 const unsigned char *aad
, size_t aadlen
,
98 const unsigned char *pt
, size_t ptlen
);
100 int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite
,
101 unsigned char *pub
, size_t *publen
, EVP_PKEY
**priv
,
102 const unsigned char *ikm
, size_t ikmlen
,
103 OSSL_LIB_CTX
*libctx
, const char *propq
);
104 int OSSL_HPKE_decap(OSSL_HPKE_CTX
*ctx
,
105 const unsigned char *enc
, size_t enclen
,
107 const unsigned char *info
, size_t infolen
);
108 int OSSL_HPKE_open(OSSL_HPKE_CTX
*ctx
,
109 unsigned char *pt
, size_t *ptlen
,
110 const unsigned char *aad
, size_t aadlen
,
111 const unsigned char *ct
, size_t ctlen
);
113 int OSSL_HPKE_export(OSSL_HPKE_CTX
*ctx
,
114 unsigned char *secret
,
116 const unsigned char *label
,
119 int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX
*ctx
, EVP_PKEY
*priv
);
120 int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX
*ctx
,
121 const unsigned char *pub
,
123 int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX
*ctx
,
125 const unsigned char *psk
, size_t psklen
);
127 int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX
*ctx
,
128 const unsigned char *ikme
, size_t ikmelen
);
130 int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX
*ctx
, uint64_t seq
);
131 int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX
*ctx
, uint64_t *seq
);
133 int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite
);
134 int OSSL_HPKE_get_grease_value(OSSL_LIB_CTX
*libctx
, const char *propq
,
135 const OSSL_HPKE_SUITE
*suite_in
,
136 OSSL_HPKE_SUITE
*suite
,
137 unsigned char *enc
, size_t *enclen
,
138 unsigned char *ct
, size_t ctlen
);
139 int OSSL_HPKE_str2suite(const char *str
, OSSL_HPKE_SUITE
*suite
);
140 size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite
, size_t clearlen
);
141 size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite
);
142 size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite
);