]>
Commit | Line | Data |
---|---|---|
b8086652 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KEYEXCH-DH | |
6 | - DH Key Exchange algorithm support | |
7 | ||
8 | =head1 DESCRIPTION | |
9 | ||
10 | Key exchange support for the B<DH> key type. | |
11 | ||
12 | =head2 DH key exchange parameters | |
13 | ||
14 | =over 4 | |
15 | ||
16 | =item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> | |
17 | ||
76396ebb TM |
18 | Sets the padding mode for the associated key exchange ctx. |
19 | Setting a value of 1 will turn padding on. | |
20 | Setting a value of 0 will turn padding off. | |
21 | If padding is off then the derived shared secret may be smaller than the | |
22 | largest possible secret size. | |
23 | If padding is on then the derived shared secret will have its first bytes | |
24 | filled with zeros where necessary to make the shared secret the same size as | |
25 | the largest possible secret size. | |
26 | The padding mode parameter is ignored (and padding implicitly enabled) when | |
27 | the KDF type is set to "X942KDF-ASN1" (B<OSSL_KDF_NAME_X942KDF_ASN1>). | |
28 | ||
29 | =item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string> | |
30 | ||
31 | See L<provider-keyexch(7)/Common Key Exchange parameters>. | |
32 | ||
33 | =item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string> | |
34 | ||
35 | See L<provider-keyexch(7)/Common Key Exchange parameters>. | |
36 | ||
37 | =item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string> | |
38 | ||
39 | See L<provider-keyexch(7)/Common Key Exchange parameters>. | |
40 | ||
41 | =item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer> | |
42 | ||
b8086652 SL |
43 | See L<provider-keyexch(7)/Common Key Exchange parameters>. |
44 | ||
c9f18e59 | 45 | =item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string> |
76e48c9d | 46 | |
76396ebb | 47 | See L<provider-keyexch(7)/Common Key Exchange parameters>. |
76e48c9d | 48 | |
76396ebb | 49 | =item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <octet string ptr> |
76e48c9d | 50 | |
76396ebb | 51 | See L<provider-kdf(7)/KDF Parameters>. |
76e48c9d | 52 | |
b8086652 SL |
53 | =back |
54 | ||
55 | =head1 EXAMPLES | |
56 | ||
57 | The examples assume a host and peer both generate keys using the same | |
58 | named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>. | |
59 | Both the host and peer transfer their public key to each other. | |
60 | ||
61 | To convert the peer's generated key pair to a public key in DER format in order | |
62 | to transfer to the host: | |
63 | ||
64 | EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ | |
65 | unsigned char *peer_pub_der = NULL; | |
66 | int peer_pub_der_len; | |
67 | ||
68 | peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); | |
69 | ... | |
70 | OPENSSL_free(peer_pub_der); | |
71 | ||
72 | To convert the received peer's public key from DER format on the host: | |
73 | ||
74 | const unsigned char *pd = peer_pub_der; | |
75 | EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); | |
76 | ... | |
77 | EVP_PKEY_free(peer_pub_key); | |
78 | ||
79 | To derive a shared secret on the host using the host's key and the peer's public | |
80 | key: | |
a841d450 | 81 | |
b8086652 SL |
82 | /* It is assumed that the host_key and peer_pub_key are set up */ |
83 | void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) | |
84 | { | |
85 | unsigned int pad = 1; | |
86 | OSSL_PARAM params[2]; | |
87 | unsigned char *secret = NULL; | |
88 | size_t secret_len = 0; | |
89 | EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); | |
90 | ||
91 | EVP_PKEY_derive_init(dctx); | |
92 | ||
93 | /* Optionally set the padding */ | |
94 | params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); | |
95 | params[1] = OSSL_PARAM_construct_end(); | |
96 | EVP_PKEY_CTX_set_params(dctx, params); | |
97 | ||
98 | EVP_PKEY_derive_set_peer(dctx, peer_pub_key); | |
99 | ||
100 | /* Get the size by passing NULL as the buffer */ | |
101 | EVP_PKEY_derive(dctx, NULL, &secret_len); | |
102 | secret = OPENSSL_zalloc(secret_len); | |
103 | ||
104 | EVP_PKEY_derive(dctx, secret, &secret_len); | |
105 | ... | |
106 | OPENSSL_clear_free(secret, secret_len); | |
107 | EVP_PKEY_CTX_free(dctx); | |
108 | } | |
109 | ||
110 | Very similar code can be used by the peer to derive the same shared secret | |
111 | using the host's public key and the peer's generated key pair. | |
112 | ||
113 | =head1 SEE ALSO | |
114 | ||
115 | L<EVP_PKEY-DH(7)>, | |
116 | L<EVP_PKEY-FFC(7)>, | |
117 | L<EVP_PKEY(3)>, | |
118 | L<provider-keyexch(7)>, | |
119 | L<provider-keymgmt(7)>, | |
120 | L<OSSL_PROVIDER-default(7)>, | |
121 | L<OSSL_PROVIDER-FIPS(7)>, | |
122 | ||
123 | =head1 COPYRIGHT | |
124 | ||
fecb3aae | 125 | Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. |
b8086652 SL |
126 | |
127 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
128 | this file except in compliance with the License. You can obtain a copy | |
129 | in the file LICENSE in the source distribution or at | |
130 | L<https://www.openssl.org/source/license.html>. | |
131 | ||
132 | =cut |