Home | History | Annotate | Line # | Download | only in man7 
      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 default operation (operating mode):
     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 
     69 =head1 HISTORY
     70 
     71 This functionality was added in OpenSSL 3.2.
     72 
     73 The C<operation> (operating mode) was a required parameter prior to OpenSSL 3.5.
     74 As of OpenSSL 3.5, C<DHKEM> is the default operating mode, and no explicit value
     75 need be specified.
     76 
     77 =head1 COPYRIGHT
     78 
     79 Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.
     80 
     81 Licensed under the Apache License 2.0 (the "License").  You may not use
     82 this file except in compliance with the License.  You can obtain a copy
     83 in the file LICENSE in the source distribution or at
     84 L<https://www.openssl.org/source/license.html>.
     85 
     86 =cut
     87