| 78c44b05 |
1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | EVP_KEM-EC |
| 6 | - EVP_KEM EC keytype and algorithm support |
| 7 | |
| 8 | =head1 DESCRIPTION |
| 9 | |
| 10 | The B<EC> keytype and its parameters are described in L<EVP_PKEY-EC(7)>. |
| 11 | See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more info. |
| 12 | |
| 13 | =head2 EC KEM parameters |
| 14 | |
| 15 | =over 4 |
| 16 | |
| 17 | =item "operation" (B<OSSL_KEM_PARAM_OPERATION>)<UTF8 string> |
| 18 | |
| 19 | The OpenSSL EC Key Encapsulation Mechanisms only supports the |
| 20 | following operation: |
| 21 | |
| 22 | =over 4 |
| 23 | |
| 24 | =item "DHKEM" (B<OSSL_KEM_PARAM_OPERATION_DHKEM>) |
| 25 | |
| 26 | The encapsulate function generates an ephemeral keypair. It produces keymaterial |
| 27 | by doing an ECDH key exchange using the ephemeral private key and a supplied |
| 28 | recipient public key. A HKDF operation using the keymaterial and a kem context |
| 29 | then produces a shared secret. The shared secret and the ephemeral public key |
| 30 | are returned. |
| 31 | The decapsulate function uses the recipient private key and the |
| 32 | ephemeral public key to produce the same keymaterial, which can then be used to |
| 33 | produce the same shared secret. |
| 34 | See L<https://www.rfc-editor.org/rfc/rfc9180.html#name-dh-based-kem-dhkem> |
| 35 | |
| 36 | =back |
| 37 | |
| 38 | This can be set using either EVP_PKEY_CTX_set_kem_op() or |
| 39 | EVP_PKEY_CTX_set_params(). |
| 40 | |
| 41 | =item "ikme" (B<OSSL_KEM_PARAM_IKME>) <octet string> |
| 42 | |
| 43 | Used to specify the key material used for generation of the ephemeral key. |
| 44 | This value should not be reused for other purposes. |
| 45 | It can only be used for the curves "P-256", "P-384" and "P-521" and should |
| 46 | have a length of at least the size of the encoded private key |
| 47 | (i.e. 32, 48 and 66 for the listed curves). |
| 48 | If this value is not set, then a random ikm is used. |
| 49 | |
| 50 | =back |
| 51 | |
| 52 | =head1 CONFORMING TO |
| 53 | |
| 54 | =over 4 |
| 55 | |
| 56 | =item RFC9180 |
| 57 | |
| 58 | =back |
| 59 | |
| 60 | =head1 SEE ALSO |
| 61 | |
| 62 | L<EVP_PKEY_CTX_set_kem_op(3)>, |
| 63 | L<EVP_PKEY_encapsulate(3)>, |
| 64 | L<EVP_PKEY_decapsulate(3)> |
| 65 | L<EVP_KEYMGMT(3)>, |
| 66 | L<EVP_PKEY(3)>, |
| 67 | L<provider-keymgmt(7)> |
| 68 | |
| f5060f9b |
69 | =head1 HISTORY |
| 70 | |
| 71 | This functionality was added in OpenSSL 3.2. |
| 72 | |
| 78c44b05 |
73 | =head1 COPYRIGHT |
| 74 | |
| 75 | Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. |
| 76 | |
| 77 | Licensed under the Apache License 2.0 (the "License"). You may not use |
| 78 | this file except in compliance with the License. You can obtain a copy |
| 79 | in the file LICENSE in the source distribution or at |
| 80 | L<https://www.openssl.org/source/license.html>. |
| 81 | |
| 82 | =cut |
projects / thirdparty / openssl.git / blame