forked from aws/aws-lc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathkdf.h
177 lines (158 loc) · 8.9 KB
/
kdf.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
/* Copyright (c) 2022, Google Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
* SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
* OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
* CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
#ifndef OPENSSL_HEADER_KDF_H
#define OPENSSL_HEADER_KDF_H
#include <openssl/base.h>
#if defined(__cplusplus)
extern "C" {
#endif
// CRYPTO_tls1_prf calculates |out_len| bytes of the TLS PRF, using |digest|,
// and writes them to |out|. It returns one on success and zero on error.
// TLS 1.2: https://datatracker.ietf.org/doc/html/rfc5246#section-5
// TLS 1.{0,1}: https://datatracker.ietf.org/doc/html/rfc4346#section-5
OPENSSL_EXPORT int CRYPTO_tls1_prf(const EVP_MD *digest,
uint8_t *out, size_t out_len,
const uint8_t *secret, size_t secret_len,
const char *label, size_t label_len,
const uint8_t *seed1, size_t seed1_len,
const uint8_t *seed2, size_t seed2_len);
// SSKDF_digest computes the One-step key derivation using the
// provided digest algorithm as the backing PRF. This algorithm
// may be referred to as "Single-Step KDF" or "NIST Concatenation KDF" by other
// implementors. |info_len| may be zero length.
//
// Returns a 1 on success, otherwise returns 0.
//
// This implementation adheres to the algorithm specified in Section 4 of the
// NIST Special Publication 800-56C Revision 2 published on August 2020. The
// parameters relevant to the specification are as follows:
// * Auxillary Function H is Option 1
// * |out_len|, |secret_len|, and |info_len| are specified in bytes
// * |out_len|, |secret_len|, |info_len| each must be <= 2^30
// * |out_len| and |secret_len| > 0
// * |out_len|, |secret_len| are analogous to |L| and |Z| respectively in the
// specification.
// * |info| and |info_len| refer to |FixedInfo| in the specification.
//
// Specification is available at https://doi.org/10.6028/NIST.SP.800-56Cr2
OPENSSL_EXPORT int SSKDF_digest(uint8_t *out_key, size_t out_len,
const EVP_MD *digest,
const uint8_t *secret, size_t secret_len,
const uint8_t *info, size_t info_len);
// SSKDF_hmac computes the One-step key derivation using the
// provided digest algorithm with HMAC as the backing PRF. This algorithm
// may be referred to as "Single-Step KDF" or "NIST Concatenation KDF" by other
// implementors. |salt| is optional and may be |NULL| or zero-length. In
// addition |info_len| may be zero length.
//
// Returns a 1 on success, otherwise returns 0.
//
// This implementation adheres to the algorithm specified in Section 4 of the
// NIST Special Publication 800-56C Revision 2 published on August 2020. The
// parameters relevant to the specification are as follows:
// * Auxillary Function H is Option 2
// * |out_len|, |secret_len|, |info_len|, and |salt_len| are specified in bytes
// * |out_len|, |secret_len|, |info_len| each must be <= 2^30
// * |out_len| and |secret_len| > 0
// * |out_len|, |secret_len| are analogous to |L| and |Z| respectively in the
// specification.
// * |info| and |info_len| refer to |FixedInfo| in the specification.
// * |salt| and |salt_len| refer to |salt| in the specification.
// * |salt| or |salt_len| being |NULL| or |0| respectively will result in a
// default salt being used which will be an all-zero byte string whose length
// is equal to the length of the specified |digest| input block length in
// bytes.
OPENSSL_EXPORT int SSKDF_hmac(uint8_t *out_key, size_t out_len,
const EVP_MD *digest,
const uint8_t *secret, size_t secret_len,
const uint8_t *info, size_t info_len,
const uint8_t *salt, size_t salt_len);
// KBKDF_ctr_hmac derives keying material using the KDF counter mode algorithm,
// using the provided key derivation key |secret| and fixed info |info|.
// |info| or |info_len| may be zero-length. This algorithm
// may be referred to as a "Key-Based Key Derivation Function in Counter Mode".
//
// This implementation adheres to the algorithm specified in Section 4.1 of the
// NIST Special Publication 800-108 Revision 1 Update 1 published on August
// 2022. The parameters relevant to the specification are as follows:
// * |out_len|, |secret_len|, and |info_len| are specified in bytes
// * |out_len| is analogous to |L| in the specification.
// * |r| is the length of the binary representation of the counter |i|
// referred to by the specification. |r| is 32 bits in this implementation.
// * The 32-bit counter is big-endian in this implementation.
// * The 32-bit counter location is placed before |info|.
// * |K_IN| is analogous to |secret| and |secret_len|.
// * |PRF| refers to HMAC in this implementation.
//
// Specification is available at https://doi.org/10.6028/NIST.SP.800-108r1-upd1
OPENSSL_EXPORT int KBKDF_ctr_hmac(uint8_t *out_key, size_t out_len,
const EVP_MD *digest, const uint8_t *secret,
size_t secret_len, const uint8_t *info,
size_t info_len);
// KDF support for EVP.
// HKDF-specific functions.
//
// The following functions are provided for OpenSSL compatibility. Prefer the
// HKDF functions in <openssl/hkdf.h>. In each, |ctx| must be created with
// |EVP_PKEY_CTX_new_id| with |EVP_PKEY_HKDF| and then initialized with
// |EVP_PKEY_derive_init|.
// EVP_PKEY_HKDEF_MODE_* define "modes" for use with |EVP_PKEY_CTX_hkdf_mode|.
// The mispelling of "HKDF" as "HKDEF" is intentional for OpenSSL compatibility.
#define EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND 0
#define EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY 1
#define EVP_PKEY_HKDEF_MODE_EXPAND_ONLY 2
// EVP_PKEY_CTX_hkdf_mode configures which HKDF operation to run. It returns one
// on success and zero on error. |mode| must be one of |EVP_PKEY_HKDEF_MODE_*|.
// By default, the mode is |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND|.
//
// If |mode| is |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND| or
// |EVP_PKEY_HKDEF_MODE_EXPAND_ONLY|, the output is variable-length.
// |EVP_PKEY_derive| uses the size of the output buffer as the output length for
// HKDF-Expand.
//
// WARNING: Although this API calls it a "mode", HKDF-Extract and HKDF-Expand
// are distinct operations with distinct inputs and distinct kinds of keys.
// Callers should not pass input secrets for one operation into the other.
OPENSSL_EXPORT int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *ctx, int mode);
// EVP_PKEY_CTX_set_hkdf_md sets |md| as the digest to use with HKDF. It returns
// one on success and zero on error.
OPENSSL_EXPORT int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *ctx,
const EVP_MD *md);
// EVP_PKEY_CTX_set1_hkdf_key configures HKDF to use |key_len| bytes from |key|
// as the "key", described below. It returns one on success and zero on error.
//
// Which input is the key depends on the "mode" (see |EVP_PKEY_CTX_hkdf_mode|).
// If |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND| or
// |EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY|, this function specifies the input keying
// material (IKM) for HKDF-Extract. If |EVP_PKEY_HKDEF_MODE_EXPAND_ONLY|, it
// instead specifies the pseudorandom key (PRK) for HKDF-Expand.
OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *ctx,
const uint8_t *key,
size_t key_len);
// EVP_PKEY_CTX_set1_hkdf_salt configures HKDF to use |salt_len| bytes from
// |salt| as the salt parameter to HKDF-Extract. It returns one on success and
// zero on error. If performing HKDF-Expand only, this parameter is ignored.
OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *ctx,
const uint8_t *salt,
size_t salt_len);
// EVP_PKEY_CTX_add1_hkdf_info appends |info_len| bytes from |info| to the info
// parameter used with HKDF-Expand. It returns one on success and zero on error.
// If performing HKDF-Extract only, this parameter is ignored.
OPENSSL_EXPORT int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *ctx,
const uint8_t *info,
size_t info_len);
#if defined(__cplusplus)
} // extern C
#endif
#endif // OPENSSL_HEADER_KDF_H