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