]>
Commit | Line | Data |
---|---|---|
ad062480 | 1 | /* |
b6461792 | 2 | * Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved. |
ad062480 | 3 | * |
e5313f20 | 4 | * Licensed under the Apache License 2.0 (the "License"). You may not use |
ad062480 SF |
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 | |
8 | */ | |
9 | ||
10 | /* APIs and data structures for HPKE (RFC9180) */ | |
11 | #ifndef OSSL_HPKE_H | |
12 | # define OSSL_HPKE_H | |
13 | # pragma once | |
14 | ||
15 | # include <openssl/types.h> | |
16 | ||
17 | /* HPKE modes */ | |
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 */ | |
22 | ||
23 | /* | |
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. | |
27 | */ | |
28 | # define OSSL_HPKE_MAX_PARMLEN 66 | |
a1c03068 | 29 | # define OSSL_HPKE_MIN_PSKLEN 32 |
ad062480 SF |
30 | # define OSSL_HPKE_MAX_INFOLEN 1024 |
31 | ||
32 | /* | |
33 | * The (16bit) HPKE algorithm ID IANA codepoints | |
34 | * If/when new IANA codepoints are added there are tables in | |
35 | * crypto/hpke/hpke_util.c that must also be updated. | |
36 | */ | |
37 | # define OSSL_HPKE_KEM_ID_RESERVED 0x0000 /* not used */ | |
38 | # define OSSL_HPKE_KEM_ID_P256 0x0010 /* NIST P-256 */ | |
39 | # define OSSL_HPKE_KEM_ID_P384 0x0011 /* NIST P-384 */ | |
40 | # define OSSL_HPKE_KEM_ID_P521 0x0012 /* NIST P-521 */ | |
41 | # define OSSL_HPKE_KEM_ID_X25519 0x0020 /* Curve25519 */ | |
42 | # define OSSL_HPKE_KEM_ID_X448 0x0021 /* Curve448 */ | |
43 | ||
44 | # define OSSL_HPKE_KDF_ID_RESERVED 0x0000 /* not used */ | |
45 | # define OSSL_HPKE_KDF_ID_HKDF_SHA256 0x0001 /* HKDF-SHA256 */ | |
46 | # define OSSL_HPKE_KDF_ID_HKDF_SHA384 0x0002 /* HKDF-SHA384 */ | |
47 | # define OSSL_HPKE_KDF_ID_HKDF_SHA512 0x0003 /* HKDF-SHA512 */ | |
48 | ||
49 | # define OSSL_HPKE_AEAD_ID_RESERVED 0x0000 /* not used */ | |
50 | # define OSSL_HPKE_AEAD_ID_AES_GCM_128 0x0001 /* AES-GCM-128 */ | |
51 | # define OSSL_HPKE_AEAD_ID_AES_GCM_256 0x0002 /* AES-GCM-256 */ | |
52 | # define OSSL_HPKE_AEAD_ID_CHACHA_POLY1305 0x0003 /* Chacha20-Poly1305 */ | |
53 | # define OSSL_HPKE_AEAD_ID_EXPORTONLY 0xFFFF /* export-only fake ID */ | |
54 | ||
55 | /* strings for suite components */ | |
56 | # define OSSL_HPKE_KEMSTR_P256 "P-256" /* KEM id 0x10 */ | |
57 | # define OSSL_HPKE_KEMSTR_P384 "P-384" /* KEM id 0x11 */ | |
58 | # define OSSL_HPKE_KEMSTR_P521 "P-521" /* KEM id 0x12 */ | |
59 | # define OSSL_HPKE_KEMSTR_X25519 "X25519" /* KEM id 0x20 */ | |
60 | # define OSSL_HPKE_KEMSTR_X448 "X448" /* KEM id 0x21 */ | |
61 | # define OSSL_HPKE_KDFSTR_256 "hkdf-sha256" /* KDF id 1 */ | |
62 | # define OSSL_HPKE_KDFSTR_384 "hkdf-sha384" /* KDF id 2 */ | |
63 | # define OSSL_HPKE_KDFSTR_512 "hkdf-sha512" /* KDF id 3 */ | |
64 | # define OSSL_HPKE_AEADSTR_AES128GCM "aes-128-gcm" /* AEAD id 1 */ | |
65 | # define OSSL_HPKE_AEADSTR_AES256GCM "aes-256-gcm" /* AEAD id 2 */ | |
66 | # define OSSL_HPKE_AEADSTR_CP "chacha20-poly1305" /* AEAD id 3 */ | |
67 | # define OSSL_HPKE_AEADSTR_EXP "exporter" /* AEAD id 0xff */ | |
68 | ||
cae72eef SF |
69 | /* |
70 | * Roles for use in creating an OSSL_HPKE_CTX, most | |
f7241edd | 71 | * important use of this is to control nonce reuse. |
cae72eef SF |
72 | */ |
73 | # define OSSL_HPKE_ROLE_SENDER 0 | |
74 | # define OSSL_HPKE_ROLE_RECEIVER 1 | |
75 | ||
ed5c0dfd TM |
76 | # ifdef __cplusplus |
77 | extern "C" { | |
78 | # endif | |
79 | ||
ad062480 SF |
80 | typedef struct { |
81 | uint16_t kem_id; /* Key Encapsulation Method id */ | |
82 | uint16_t kdf_id; /* Key Derivation Function id */ | |
83 | uint16_t aead_id; /* AEAD alg id */ | |
84 | } OSSL_HPKE_SUITE; | |
85 | ||
86 | /** | |
87 | * Suite constants, use this like: | |
88 | * OSSL_HPKE_SUITE myvar = OSSL_HPKE_SUITE_DEFAULT; | |
89 | */ | |
4032cd9a YL |
90 | # ifndef OPENSSL_NO_ECX |
91 | # define OSSL_HPKE_SUITE_DEFAULT \ | |
ad062480 SF |
92 | {\ |
93 | OSSL_HPKE_KEM_ID_X25519, \ | |
94 | OSSL_HPKE_KDF_ID_HKDF_SHA256, \ | |
95 | OSSL_HPKE_AEAD_ID_AES_GCM_128 \ | |
96 | } | |
4032cd9a YL |
97 | # else |
98 | # define OSSL_HPKE_SUITE_DEFAULT \ | |
99 | {\ | |
100 | OSSL_HPKE_KEM_ID_P256, \ | |
101 | OSSL_HPKE_KDF_ID_HKDF_SHA256, \ | |
102 | OSSL_HPKE_AEAD_ID_AES_GCM_128 \ | |
103 | } | |
104 | #endif | |
ad062480 SF |
105 | |
106 | typedef struct ossl_hpke_ctx_st OSSL_HPKE_CTX; | |
107 | ||
cae72eef | 108 | OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role, |
ad062480 SF |
109 | OSSL_LIB_CTX *libctx, const char *propq); |
110 | void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx); | |
111 | ||
112 | int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx, | |
113 | unsigned char *enc, size_t *enclen, | |
114 | const unsigned char *pub, size_t publen, | |
115 | const unsigned char *info, size_t infolen); | |
116 | int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx, | |
117 | unsigned char *ct, size_t *ctlen, | |
118 | const unsigned char *aad, size_t aadlen, | |
119 | const unsigned char *pt, size_t ptlen); | |
120 | ||
121 | int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite, | |
122 | unsigned char *pub, size_t *publen, EVP_PKEY **priv, | |
123 | const unsigned char *ikm, size_t ikmlen, | |
124 | OSSL_LIB_CTX *libctx, const char *propq); | |
125 | int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx, | |
126 | const unsigned char *enc, size_t enclen, | |
127 | EVP_PKEY *recippriv, | |
128 | const unsigned char *info, size_t infolen); | |
129 | int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx, | |
130 | unsigned char *pt, size_t *ptlen, | |
131 | const unsigned char *aad, size_t aadlen, | |
132 | const unsigned char *ct, size_t ctlen); | |
133 | ||
134 | int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx, | |
135 | unsigned char *secret, | |
136 | size_t secretlen, | |
137 | const unsigned char *label, | |
138 | size_t labellen); | |
139 | ||
140 | int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv); | |
141 | int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx, | |
142 | const unsigned char *pub, | |
143 | size_t publen); | |
144 | int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx, | |
145 | const char *pskid, | |
146 | const unsigned char *psk, size_t psklen); | |
147 | ||
148 | int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx, | |
149 | const unsigned char *ikme, size_t ikmelen); | |
150 | ||
151 | int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq); | |
152 | int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq); | |
153 | ||
154 | int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite); | |
8b7b9aac | 155 | int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in, |
ad062480 SF |
156 | OSSL_HPKE_SUITE *suite, |
157 | unsigned char *enc, size_t *enclen, | |
8b7b9aac | 158 | unsigned char *ct, size_t ctlen, |
159 | OSSL_LIB_CTX *libctx, const char *propq); | |
ad062480 SF |
160 | int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite); |
161 | size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen); | |
162 | size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite); | |
163 | size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite); | |
164 | ||
ed5c0dfd TM |
165 | # ifdef __cplusplus |
166 | } | |
167 | # endif | |
168 | ||
ad062480 | 169 | #endif |