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