1.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.23 2023/09/13 13:32:01 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 4.\" Parts were split out into RSA_pkey_ctx_ctrl(3). 5.\" 6.\" This file is a derived work. 7.\" The changes are covered by the following Copyright and license: 8.\" 9.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 24.\" and Antoine Salon <asalon@vmware.com>. 25.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2018 The OpenSSL Project. 26.\" All rights reserved. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions 30.\" are met: 31.\" 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in 37.\" the documentation and/or other materials provided with the 38.\" distribution. 39.\" 40.\" 3. All advertising materials mentioning features or use of this 41.\" software must display the following acknowledgment: 42.\" "This product includes software developed by the OpenSSL Project 43.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 44.\" 45.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 46.\" endorse or promote products derived from this software without 47.\" prior written permission. For written permission, please contact 48.\" openssl-core@openssl.org. 49.\" 50.\" 5. Products derived from this software may not be called "OpenSSL" 51.\" nor may "OpenSSL" appear in their names without prior written 52.\" permission of the OpenSSL Project. 53.\" 54.\" 6. Redistributions of any form whatsoever must retain the following 55.\" acknowledgment: 56.\" "This product includes software developed by the OpenSSL Project 57.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 58.\" 59.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 60.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 61.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 62.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 63.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 64.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 65.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 66.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 67.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 68.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 69.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 70.\" OF THE POSSIBILITY OF SUCH DAMAGE. 71.\" 72.Dd $Mdocdate: September 13 2023 $ 73.Dt EVP_PKEY_CTX_CTRL 3 74.Os 75.Sh NAME 76.Nm EVP_PKEY_CTX_ctrl , 77.Nm EVP_PKEY_CTX_ctrl_str , 78.Nm EVP_PKEY_CTX_set_signature_md , 79.Nm EVP_PKEY_CTX_get_signature_md , 80.Nm EVP_PKEY_CTX_set_dsa_paramgen_bits , 81.Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len , 82.Nm EVP_PKEY_CTX_set_dh_paramgen_generator , 83.Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid , 84.Nm EVP_PKEY_CTX_set_ec_param_enc , 85.Nm EVP_PKEY_CTX_set_ecdh_cofactor_mode , 86.Nm EVP_PKEY_CTX_get_ecdh_cofactor_mode , 87.Nm EVP_PKEY_CTX_set_ecdh_kdf_type , 88.Nm EVP_PKEY_CTX_get_ecdh_kdf_type , 89.Nm EVP_PKEY_CTX_set_ecdh_kdf_md , 90.Nm EVP_PKEY_CTX_get_ecdh_kdf_md , 91.Nm EVP_PKEY_CTX_set_ecdh_kdf_outlen , 92.Nm EVP_PKEY_CTX_get_ecdh_kdf_outlen , 93.Nm EVP_PKEY_CTX_set0_ecdh_kdf_ukm , 94.Nm EVP_PKEY_CTX_get0_ecdh_kdf_ukm , 95.Nm EVP_PKEY_CTX_set1_id , 96.Nm EVP_PKEY_CTX_get1_id , 97.Nm EVP_PKEY_CTX_get1_id_len 98.Nd algorithm specific control operations 99.Sh SYNOPSIS 100.In openssl/evp.h 101.Ft int 102.Fo EVP_PKEY_CTX_ctrl 103.Fa "EVP_PKEY_CTX *ctx" 104.Fa "int keytype" 105.Fa "int optype" 106.Fa "int cmd" 107.Fa "int p1" 108.Fa "void *p2" 109.Fc 110.Ft int 111.Fo EVP_PKEY_CTX_ctrl_str 112.Fa "EVP_PKEY_CTX *ctx" 113.Fa "const char *type" 114.Fa "const char *value" 115.Fc 116.Ft int 117.Fo EVP_PKEY_CTX_set_signature_md 118.Fa "EVP_PKEY_CTX *ctx" 119.Fa "const EVP_MD *md" 120.Fc 121.Ft int 122.Fo EVP_PKEY_CTX_get_signature_md 123.Fa "EVP_PKEY_CTX *ctx" 124.Fa "const EVP_MD **pmd" 125.Fc 126.In openssl/dsa.h 127.Ft int 128.Fo EVP_PKEY_CTX_set_dsa_paramgen_bits 129.Fa "EVP_PKEY_CTX *ctx" 130.Fa "int nbits" 131.Fc 132.In openssl/dh.h 133.Ft int 134.Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len 135.Fa "EVP_PKEY_CTX *ctx" 136.Fa "int len" 137.Fc 138.Ft int 139.Fo EVP_PKEY_CTX_set_dh_paramgen_generator 140.Fa "EVP_PKEY_CTX *ctx" 141.Fa "int gen" 142.Fc 143.In openssl/ec.h 144.Ft int 145.Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid 146.Fa "EVP_PKEY_CTX *ctx" 147.Fa "int nid" 148.Fc 149.Fa int 150.Fo EVP_PKEY_CTX_set_ec_param_enc 151.Fa "EVP_PKEY_CTX *ctx" 152.Fa "int param_enc" 153.Fc 154.Ft int 155.Fo EVP_PKEY_CTX_set_ecdh_cofactor_mode 156.Fa "EVP_PKEY_CTX *ctx" 157.Fa "int cofactor_mode" 158.Fc 159.Ft int 160.Fo EVP_PKEY_CTX_get_ecdh_cofactor_mode 161.Fa "EVP_PKEY_CTX *ctx" 162.Fc 163.Ft int 164.Fo EVP_PKEY_CTX_set_ecdh_kdf_type 165.Fa "EVP_PKEY_CTX *ctx" 166.Fa "int kdf" 167.Fc 168.Ft int 169.Fo EVP_PKEY_CTX_get_ecdh_kdf_type 170.Fa "EVP_PKEY_CTX *ctx" 171.Fc 172.Ft int 173.Fo EVP_PKEY_CTX_set_ecdh_kdf_md 174.Fa "EVP_PKEY_CTX *ctx" 175.Fa "const EVP_MD *md" 176.Fc 177.Ft int 178.Fo EVP_PKEY_CTX_get_ecdh_kdf_md 179.Fa "EVP_PKEY_CTX *ctx" 180.Fa "const EVP_MD **pmd" 181.Fc 182.Ft int 183.Fo EVP_PKEY_CTX_set_ecdh_kdf_outlen 184.Fa "EVP_PKEY_CTX *ctx" 185.Fa "int len" 186.Fc 187.Ft int 188.Fo EVP_PKEY_CTX_get_ecdh_kdf_outlen 189.Fa "EVP_PKEY_CTX *ctx" 190.Fa "int *plen" 191.Fc 192.Ft int 193.Fo EVP_PKEY_CTX_set0_ecdh_kdf_ukm 194.Fa "EVP_PKEY_CTX *ctx" 195.Fa "unsigned char *ukm" 196.Fa "int len" 197.Fc 198.Ft int 199.Fo EVP_PKEY_CTX_get0_ecdh_kdf_ukm 200.Fa "EVP_PKEY_CTX *ctx" 201.Fa "unsigned char **pukm" 202.Fc 203.Ft int 204.Fo EVP_PKEY_CTX_set1_id 205.Fa "EVP_PKEY_CTX *ctx" 206.Fa "void *id" 207.Fa "size_t id_len" 208.Fc 209.Ft int 210.Fo EVP_PKEY_CTX_get1_id 211.Fa "EVP_PKEY_CTX *ctx" 212.Fa "void *id" 213.Fc 214.Ft int 215.Fo EVP_PKEY_CTX_get1_id_len 216.Fa "EVP_PKEY_CTX *ctx" 217.Fa "size_t *pid_len" 218.Fc 219.Sh DESCRIPTION 220The function 221.Fn EVP_PKEY_CTX_ctrl 222sends a control operation to the context 223.Fa ctx . 224The key type used must match 225.Fa keytype 226if it is not -1. 227The parameter 228.Fa optype 229is a mask indicating which operations the control can be applied to. 230The control command is indicated in 231.Fa cmd 232and any additional arguments in 233.Fa p1 234and 235.Fa p2 . 236.Pp 237Applications will not normally call 238.Fn EVP_PKEY_CTX_ctrl 239directly but will instead call one of the algorithm specific macros 240described below and in 241.Xr RSA_pkey_ctx_ctrl 3 . 242.Pp 243The function 244.Fn EVP_PKEY_CTX_ctrl_str 245allows an application to send an algorithm specific control operation to 246a context 247.Fa ctx 248in string form. 249This is intended to be used for options specified on the command line or 250in text files. 251The commands supported are documented in the 252.Xr openssl 1 253utility command line pages for the option 254.Fl pkeyopt 255which is supported by the 256.Cm pkeyutl , 257.Cm genpkey , 258and 259.Cm req 260commands. 261.Pp 262All the remaining "functions" are implemented as macros. 263.Pp 264The 265.Fn EVP_PKEY_CTX_set_signature_md 266and 267.Fn EVP_PKEY_CTX_get_signature_md 268macros set and get the message digest type used in a signature. 269They can be used with the RSA, DSA, and ECDSA algorithms. 270If the key is of the type 271.Dv EVP_PKEY_RSA_PSS 272and has usage restrictions, an error occurs if an attempt is made 273to set the digest to anything other than the restricted value. 274.Pp 275These two macros expand to 276.Fn EVP_PKEY_CTX_ctrl 277with an 278.Fa optype 279of 280.Dv EVP_PKEY_OP_TYPE_SIG 281and the following command arguments: 282.Pp 283.Bl -column -compact EVP_PKEY_CTRL_GET_MD EVP_PKEY_CTX_get_signature_md() 284.It Fa cmd No constant Ta corresponding macro 285.It Dv EVP_PKEY_CTRL_MD Ta Fn EVP_PKEY_CTX_set_signature_md 286.It Dv EVP_PKEY_CTRL_GET_MD Ta Fn EVP_PKEY_CTX_get_signature_md 287.El 288.Ss DSA parameters 289The macro 290.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits 291sets the number of bits used for DSA parameter generation to 292.Fa nbits . 293If not specified, 1024 is used. 294.Ss DH parameters 295The macro 296.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len 297sets the length of the DH prime parameter 298.Fa len 299for DH parameter generation. 300It only accepts lengths greater than or equal to 256. 301If this macro is not called, then 1024 is used. 302.Pp 303The 304.Fn EVP_PKEY_CTX_set_dh_paramgen_generator 305macro sets DH generator to 306.Fa gen 307for DH parameter generation. 308If not specified, 2 is used. 309.Ss EC parameters 310The 311.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid 312macro sets the EC curve for EC parameter generation to 313.Fa nid . 314For EC parameter generation, this macro must be called or an error occurs 315because there is no default curve. 316.Pp 317The 318.Fn EVP_PKEY_CTX_set_ec_param_enc 319macro sets the EC parameter encoding to 320.Fa param_enc 321when generating EC parameters or an EC key. 322The encoding can be set to 0 for explicit parameters or to 323.Dv OPENSSL_EC_NAMED_CURVE 324to use named curve form. 325.Ss ECDH parameters 326The 327.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode 328macro sets the cofactor mode to 329.Fa cofactor_mode 330for ECDH key derivation. 331Possible values are 1 to enable cofactor key derivation, 0 to disable 332it, or -1 to clear the stored cofactor mode and fall back to the 333private key cofactor mode. 334.Pp 335The 336.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode 337macro returns the cofactor mode for 338.Fa ctx 339used for ECDH key derivation. 340Possible return values are 1 when cofactor key derivation is enabled 341or 0 otherwise. 342.Ss ECDH key derivation function parameters 343The 344.Fn EVP_PKEY_CTX_set_ecdh_kdf_type 345macro sets the key derivation function type to 346.Fa kdf 347for ECDH key derivation. 348Possible values are 349.Dv EVP_PKEY_ECDH_KDF_NONE 350or 351.Dv EVP_PKEY_ECDH_KDF_X9_63 352which uses the key derivation specified in X9.63. 353When using key derivation, the 354.Fa kdf_md 355and 356.Fa kdf_outlen 357parameters must also be specified. 358.Pp 359The 360.Fn EVP_PKEY_CTX_get_ecdh_kdf_type 361macro returns the key derivation function type for 362.Fa ctx 363used for ECDH key derivation. 364Possible return values are 365.Dv EVP_PKEY_ECDH_KDF_NONE 366or 367.Dv EVP_PKEY_ECDH_KDF_X9_63 . 368.Pp 369The 370.Fn EVP_PKEY_CTX_set_ecdh_kdf_md 371macro sets the key derivation function message digest to 372.Fa md 373for ECDH key derivation. 374Note that X9.63 specifies that this digest should be SHA1, 375but OpenSSL tolerates other digests. 376.Pp 377The 378.Fn EVP_PKEY_CTX_get_ecdh_kdf_md 379macro gets the key derivation function message digest for 380.Fa ctx 381used for ECDH key derivation. 382.Pp 383The 384.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen 385macro sets the key derivation function output length to 386.Fa len 387for ECDH key derivation. 388.Pp 389The 390.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen 391macro gets the key derivation function output length for 392.Fa ctx 393used for ECDH key derivation. 394.Pp 395The 396.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm 397macro sets the user key material to 398.Fa ukm 399for ECDH key derivation. 400This parameter is optional and corresponds to the shared info 401in X9.63 terms. 402The library takes ownership of the user key material, so the caller 403should not free the original memory pointed to by 404.Fa ukm . 405.Pp 406The 407.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm 408macro gets the user key material for 409.Fa ctx . 410The return value is the user key material length. 411The resulting pointer is owned by the library and should not be 412freed by the caller. 413.Ss Other parameters 414The 415.Fn EVP_PKEY_CTX_set1_id , 416.Fn EVP_PKEY_CTX_get1_id , 417and 418.Fn EVP_PKEY_CTX_get1_id_len 419macros manipulate a special identifier field used for some specific 420signature algorithms such as SM2. 421The 422.Fn EVP_PKEY_set1_id 423macro sets the ID to a copy of 424.Fa id 425with the length 426.Fa id_len . 427The caller can safely free the original memory pointed to by 428.Fa id . 429The 430.Fn EVP_PKEY_CTX_get1_id_len 431macro returns the length of the ID set via a previous call to 432.Fn EVP_PKEY_set1_id . 433That length is typically used to allocate memory for a subsequent call to 434.Fn EVP_PKEY_CTX_get1_id , 435which copies the previously set ID into 436.Pf * Fa id . 437The caller is responsible for allocating sufficient memory for 438.Fa id 439before calling 440.Fn EVP_PKEY_CTX_get1_id . 441.Sh RETURN VALUES 442.Fn EVP_PKEY_CTX_ctrl 443and its macros return a positive value for success and 0 or a negative 444value for failure. 445In particular, a return value of -2 indicates the operation is not 446supported by the public key algorithm. 447.Sh SEE ALSO 448.Xr DH_new 3 , 449.Xr EVP_DigestInit 3 , 450.Xr EVP_PKEY_CTX_new 3 , 451.Xr EVP_PKEY_decrypt 3 , 452.Xr EVP_PKEY_derive 3 , 453.Xr EVP_PKEY_encrypt 3 , 454.Xr EVP_PKEY_get_default_digest_nid 3 , 455.Xr EVP_PKEY_keygen 3 , 456.Xr EVP_PKEY_meth_set_ctrl 3 , 457.Xr EVP_PKEY_sign 3 , 458.Xr EVP_PKEY_verify 3 , 459.Xr EVP_PKEY_verify_recover 3 , 460.Xr RSA_pkey_ctx_ctrl 3 461.Sh HISTORY 462The functions 463.Fn EVP_PKEY_CTX_ctrl , 464.Fn EVP_PKEY_CTX_ctrl_str , 465.Fn EVP_PKEY_CTX_set_signature_md , 466.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits , 467.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len , 468.Fn EVP_PKEY_CTX_set_dh_paramgen_generator , 469and 470.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid 471first appeared in OpenSSL 1.0.0 and have been available since 472.Ox 4.9 . 473.Pp 474The functions 475.Fn EVP_PKEY_CTX_get_signature_md , 476.Fn EVP_PKEY_CTX_set_ec_param_enc , 477.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode , 478.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode , 479.Fn EVP_PKEY_CTX_set_ecdh_kdf_type , 480.Fn EVP_PKEY_CTX_get_ecdh_kdf_type , 481.Fn EVP_PKEY_CTX_set_ecdh_kdf_md , 482.Fn EVP_PKEY_CTX_get_ecdh_kdf_md , 483.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen , 484.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen , 485.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm , 486and 487.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm 488first appeared in OpenSSL 1.0.2 and have been available since 489.Ox 6.6 . 490.Pp 491The functions 492.Fn EVP_PKEY_CTX_set1_id , 493.Fn EVP_PKEY_CTX_get1_id , 494and 495.Fn EVP_PKEY_CTX_get1_id_len 496first appeared in OpenSSL 1.1.1 and have been available since 497.Ox 6.6 . 498