1.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.4 2019/11/01 19:37:21 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod 99d63d46 Oct 26 13:56:48 2016 -0400 4.\" OpenSSL man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod 5.\" 87103969 Oct 1 14:11:57 2018 -0700 6.\" selective merge up to: 7.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod df75c2b f Dec 9 01:02:36 2018 +0100 8.\" 9.\" This file was written by Dr. Stephen Henson <steve@openssl.org> 10.\" and Antoine Salon <asalon@vmware.com>. 11.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2017, 2018 The OpenSSL Project. 12.\" All rights reserved. 13.\" 14.\" Redistribution and use in source and binary forms, with or without 15.\" modification, are permitted provided that the following conditions 16.\" are met: 17.\" 18.\" 1. Redistributions of source code must retain the above copyright 19.\" notice, this list of conditions and the following disclaimer. 20.\" 21.\" 2. Redistributions in binary form must reproduce the above copyright 22.\" notice, this list of conditions and the following disclaimer in 23.\" the documentation and/or other materials provided with the 24.\" distribution. 25.\" 26.\" 3. All advertising materials mentioning features or use of this 27.\" software must display the following acknowledgment: 28.\" "This product includes software developed by the OpenSSL Project 29.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 30.\" 31.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 32.\" endorse or promote products derived from this software without 33.\" prior written permission. For written permission, please contact 34.\" openssl-core@openssl.org. 35.\" 36.\" 5. Products derived from this software may not be called "OpenSSL" 37.\" nor may "OpenSSL" appear in their names without prior written 38.\" permission of the OpenSSL Project. 39.\" 40.\" 6. Redistributions of any form whatsoever must retain the following 41.\" acknowledgment: 42.\" "This product includes software developed by the OpenSSL Project 43.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 44.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 46.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 49.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 50.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 51.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 52.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 54.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 55.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 56.\" OF THE POSSIBILITY OF SUCH DAMAGE. 57.\" 58.Dd $Mdocdate: November 1 2019 $ 59.Dt RSA_PKEY_CTX_CTRL 3 60.Os 61.Sh NAME 62.Nm RSA_pkey_ctx_ctrl , 63.Nm EVP_PKEY_CTX_set_rsa_padding , 64.Nm EVP_PKEY_CTX_get_rsa_padding , 65.Nm EVP_PKEY_CTX_set_rsa_keygen_bits , 66.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp , 67.Nm EVP_PKEY_CTX_set_rsa_mgf1_md , 68.Nm EVP_PKEY_CTX_get_rsa_mgf1_md , 69.Nm EVP_PKEY_CTX_set_rsa_oaep_md , 70.Nm EVP_PKEY_CTX_get_rsa_oaep_md , 71.Nm EVP_PKEY_CTX_set0_rsa_oaep_label , 72.Nm EVP_PKEY_CTX_get0_rsa_oaep_label , 73.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen , 74.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen , 75.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_md , 76.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md , 77.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen 78.Nd RSA private key control operations 79.Sh SYNOPSIS 80.In openssl/rsa.h 81.Ft int 82.Fo RSA_pkey_ctx_ctrl 83.Fa "EVP_PKEY_CTX *ctx" 84.Fa "int optype" 85.Fa "int cmd" 86.Fa "int p1" 87.Fa "void *p2" 88.Fc 89.Ft int 90.Fo EVP_PKEY_CTX_set_rsa_padding 91.Fa "EVP_PKEY_CTX *ctx" 92.Fa "int pad" 93.Fc 94.Ft int 95.Fo EVP_PKEY_CTX_get_rsa_padding 96.Fa "EVP_PKEY_CTX *ctx" 97.Fa "int *ppad" 98.Fc 99.Ft int 100.Fo EVP_PKEY_CTX_set_rsa_keygen_bits 101.Fa "EVP_PKEY_CTX *ctx" 102.Fa "int mbits" 103.Fc 104.Ft int 105.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp 106.Fa "EVP_PKEY_CTX *ctx" 107.Fa "BIGNUM *pubexp" 108.Fc 109.Ft int 110.Fo EVP_PKEY_CTX_set_rsa_mgf1_md 111.Fa "EVP_PKEY_CTX *ctx" 112.Fa "const EVP_MD *md" 113.Fc 114.Ft int 115.Fo EVP_PKEY_CTX_get_rsa_mgf1_md 116.Fa "EVP_PKEY_CTX *ctx" 117.Fa "const EVP_MD **pmd" 118.Fc 119.Ft int 120.Fo EVP_PKEY_CTX_set_rsa_oaep_md 121.Fa "EVP_PKEY_CTX *ctx" 122.Fa "const EVP_MD *md" 123.Fc 124.Ft int 125.Fo EVP_PKEY_CTX_get_rsa_oaep_md 126.Fa "EVP_PKEY_CTX *ctx" 127.Fa "const EVP_MD **pmd" 128.Fc 129.Ft int 130.Fo EVP_PKEY_CTX_set0_rsa_oaep_label 131.Fa "EVP_PKEY_CTX *ctx" 132.Fa "unsigned char *label" 133.Fa "int len" 134.Fc 135.Ft int 136.Fo EVP_PKEY_CTX_get0_rsa_oaep_label 137.Fa "EVP_PKEY_CTX *ctx" 138.Fa "unsigned char **plabel" 139.Fc 140.Ft int 141.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen 142.Fa "EVP_PKEY_CTX *ctx" 143.Fa "int len" 144.Fc 145.Ft int 146.Fo EVP_PKEY_CTX_get_rsa_pss_saltlen 147.Fa "EVP_PKEY_CTX *ctx" 148.Fa "int *plen" 149.Fc 150.Ft int 151.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_md 152.Fa "EVP_PKEY_CTX *pctx" 153.Fa "const EVP_MD *md" 154.Fc 155.Ft int 156.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md 157.Fa "EVP_PKEY_CTX *pctx" 158.Fa "const EVP_MD *md" 159.Fc 160.Ft int 161.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen 162.Fa "EVP_PKEY_CTX *pctx" 163.Fa "int saltlen" 164.Fc 165.Sh DESCRIPTION 166The function 167.Fn RSA_pkey_ctx_ctrl 168is a shallow wrapper around 169.Xr EVP_PKEY_CTX_ctrl 3 170which only succeeds if 171.Fa ctx 172matches either 173.Dv EVP_PKEY_RSA 174or 175.Dv EVP_PKEY_RSA_PSS . 176.Pp 177All the remaining "functions" are implemented as macros. 178.Pp 179The 180.Fn EVP_PKEY_CTX_set_rsa_padding 181macro sets the RSA padding mode for 182.Fa ctx . 183The 184.Fa pad 185parameter can take the value 186.Dv RSA_PKCS1_PADDING 187for PKCS#1 padding, 188.Dv RSA_NO_PADDING 189for no padding, 190.Dv RSA_PKCS1_OAEP_PADDING 191for OAEP padding (encrypt and decrypt only), 192.Dv RSA_X931_PADDING 193for X9.31 padding (signature operations only) and 194.Dv RSA_PKCS1_PSS_PADDING 195(sign and verify only). 196Only the last one can be used with keys of the type 197.Dv EVP_PKEY_RSA_PSS . 198.Pp 199Two RSA padding modes behave differently if 200.Xr EVP_PKEY_CTX_set_signature_md 3 201is used. 202If this macro is called for PKCS#1 padding, the plaintext buffer is an 203actual digest value and is encapsulated in a 204.Vt DigestInfo 205structure according to PKCS#1 when signing and this structure is 206expected (and stripped off) when verifying. 207If this control is not used with RSA and PKCS#1 padding then the 208supplied data is used directly and not encapsulated. 209In the case of X9.31 padding for RSA the algorithm identifier byte is 210added or checked and removed if this control is called. 211If it is not called then the first byte of the plaintext buffer is 212expected to be the algorithm identifier byte. 213.Pp 214The 215.Fn EVP_PKEY_CTX_get_rsa_padding 216macro retrieves the RSA padding mode for 217.Fa ctx . 218.Pp 219The 220.Fn EVP_PKEY_CTX_set_rsa_keygen_bits 221macro sets the RSA key length for RSA or RSA-PSS key generation to 222.Fa mbits . 223The smallest supported value is 512 bits. 224If not specified, 1024 bits is used. 225.Pp 226The 227.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp 228macro sets the public exponent value for RSA or RSA-PSS key generation to 229.Fa pubexp . 230Currently, it should be an odd integer. 231The 232.Fa pubexp 233pointer is used internally by this function, so it should not be modified 234or freed after the call. 235If this macro is not called, then 65537 is used. 236.Pp 237The 238.Fn EVP_PKEY_CTX_set_rsa_mgf1_md 239macro sets the MGF1 digest for RSA padding schemes to 240.Fa md . 241Unless explicitly specified, the signing digest is used. 242The padding mode must have been set to 243.Dv RSA_PKCS1_OAEP_PADDING 244or 245.Dv RSA_PKCS1_PSS_PADDING . 246If the key is of the type 247.Dv EVP_PKEY_RSA_PSS 248and has usage restrictions, an error occurs if an attempt is made 249to set the digest to anything other than the restricted value. 250.Pp 251The 252.Fn EVP_PKEY_CTX_get_rsa_mgf1_md 253macro retrieves the MGF1 digest for 254.Fa ctx . 255Unless explicitly specified, the signing digest is used. 256The padding mode must have been set to 257.Dv RSA_PKCS1_OAEP_PADDING 258or 259.Dv RSA_PKCS1_PSS_PADDING . 260.Ss Optimal asymmetric encryption padding 261The following macros require that the padding mode was set to 262.Dv RSA_PKCS1_OAEP_PADDING . 263.Pp 264The 265.Fn EVP_PKEY_CTX_set_rsa_oaep_md 266macro sets the message digest type used in RSA OAEP to 267.Fa md . 268.Pp 269The 270.Fn EVP_PKEY_CTX_get_rsa_oaep_md 271macro gets the message digest type used in RSA OAEP to 272.Pf * Fa pmd . 273.Pp 274The 275.Fn EVP_PKEY_CTX_set0_rsa_oaep_label 276macro sets the RSA OAEP label to 277.Fa label 278and its length to 279.Fa len . 280If 281.Fa label 282is 283.Dv NULL 284or 285.Fa len 286is 0, the label is cleared. 287The library takes ownership of the label so the caller should not 288free the original memory pointed to by 289.Fa label . 290.Pp 291The 292.Fn EVP_PKEY_CTX_get0_rsa_oaep_label 293macro gets the RSA OAEP label to 294.Pf * Fa plabel . 295The return value is the label length. 296The resulting pointer is owned by the library and should not be 297freed by the caller. 298.Ss Probabilistic signature scheme 299The following macros require that the padding mode was set to 300.Dv RSA_PKCS1_PSS_PADDING . 301.Pp 302The 303.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen 304macro sets the RSA PSS salt length to 305.Fa len . 306Three special values are supported: 307.Dv RSA_PSS_SALTLEN_DIGEST 308sets the salt length to the digest length. 309.Dv RSA_PSS_SALTLEN_MAX 310sets the salt length to the maximum permissible value. 311When signing, 312.Dv RSA_PSS_SALTLEN_AUTO 313sets the salt length to the maximum permissible value. 314When verifying, 315.Dv RSA_PSS_SALTLEN_AUTO 316causes the salt length to be automatically determined based on the 317PSS block structure. 318If this macro is not called, a salt length value of 319.Dv RSA_PSS_SALTLEN_AUTO 320is used by default. 321.Pp 322If the key has usage restrictions and an attempt is made to set the 323salt length below the minimum value, an error occurs. 324Also, if the key has usage restrictions, 325.Dv RSA_PSS_SALTLEN_AUTO 326is not supported for verification. 327.Pp 328The 329.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen 330macro retrieves the RSA PSS salt length for 331.Fa ctx . 332.Pp 333Optional parameter restrictions can be specified when generating a PSS 334key. 335If any restrictions are set using the macros described below, 336then all parameters are restricted. 337For example, setting a minimum salt length also restricts the digest and 338MGF1 algorithms. 339If any restrictions are in place, then they are reflected in the 340corresponding parameters of the public key when (for example) a 341certificate request is signed. 342.Pp 343.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_md 344restricts the digest algorithm the generated key can use to 345.Fa md . 346.Pp 347.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md 348restricts the MGF1 algorithm the generated key can use to 349.Fa md . 350.Pp 351.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen 352restricts the minimum salt length to 353.Fa saltlen . 354.Sh RETURN VALUES 355These functions return a positive value for success or 0 or a negative 356value for failure. 357In particular, a return value of -2 indicates the operation is not 358supported by the public key algorithm. 359.Sh SEE ALSO 360.Xr EVP_DigestInit 3 , 361.Xr EVP_PKEY_CTX_ctrl 3 , 362.Xr EVP_PKEY_CTX_new 3 , 363.Xr EVP_PKEY_decrypt 3 , 364.Xr EVP_PKEY_derive 3 , 365.Xr EVP_PKEY_encrypt 3 , 366.Xr EVP_PKEY_get_default_digest_nid 3 , 367.Xr EVP_PKEY_keygen 3 , 368.Xr EVP_PKEY_meth_set_ctrl 3 , 369.Xr EVP_PKEY_sign 3 , 370.Xr EVP_PKEY_verify 3 , 371.Xr EVP_PKEY_verify_recover 3 372.Sh HISTORY 373The functions 374.Fn EVP_PKEY_CTX_set_rsa_padding , 375.Fn EVP_PKEY_CTX_set_rsa_keygen_bits , 376.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp , 377and 378.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen 379first appeared in OpenSSL 1.0.0 and have been available since 380.Ox 4.9 . 381.Pp 382The functions 383.Fn EVP_PKEY_CTX_get_rsa_padding , 384.Fn EVP_PKEY_CTX_set_rsa_mgf1_md , 385.Fn EVP_PKEY_CTX_get_rsa_mgf1_md , 386and 387.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen 388first appeared in OpenSSL 1.0.1 and have been available since 389.Ox 5.3 . 390.Pp 391The functions 392.Fn EVP_PKEY_CTX_set_rsa_oaep_md , 393.Fn EVP_PKEY_CTX_get_rsa_oaep_md , 394.Fn EVP_PKEY_CTX_set0_rsa_oaep_label , 395and 396.Fn EVP_PKEY_CTX_get0_rsa_oaep_label 397first appeared in OpenSSL 1.0.2 and have been available since 398.Ox 6.7 . 399.Pp 400The function 401.Fn RSA_pkey_ctx_ctrl 402first appeared in OpenSSL 1.1.1 and has been available since 403.Ox 6.7 . 404