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