diff options
author | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2019-11-01 12:02:59 +0000 |
---|---|---|
committer | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2019-11-01 12:02:59 +0000 |
commit | 5fb4d9a9d0e83a99568ff678f70317b2b9b1ba9c (patch) | |
tree | 9138ecb9826324b8ff676e7329fb39e130cd2310 | |
parent | 92409b6efb0af18257374c0ddbe268b7629e6db6 (diff) |
The EVP_PKEY_CTX_ctrl(3) manual page requires additions for RSA-PSS
but it is growing to excessive size, so split out RSA_pkey_ctx_ctrl(3).
-rw-r--r-- | lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 | 271 | ||||
-rw-r--r-- | lib/libcrypto/man/Makefile | 3 | ||||
-rw-r--r-- | lib/libcrypto/man/RSA_new.3 | 5 | ||||
-rw-r--r-- | lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 | 346 |
4 files changed, 358 insertions, 267 deletions
diff --git a/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 index b9332a7ec1b..2bb6a3fd3b2 100644 --- a/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 +++ b/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 @@ -1,6 +1,7 @@ -.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.20 2019/10/31 14:29:41 schwarze Exp $ +.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.21 2019/11/01 12:02:58 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" Parts were split out into RSA_pkey_ctx_ctrl(3). .\" .\" This file was written by Dr. Stephen Henson <steve@openssl.org> .\" and Antoine Salon <asalon@vmware.com>. @@ -51,7 +52,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: October 31 2019 $ +.Dd $Mdocdate: November 1 2019 $ .Dt EVP_PKEY_CTX_CTRL 3 .Os .Sh NAME @@ -59,19 +60,6 @@ .Nm EVP_PKEY_CTX_ctrl_str , .Nm EVP_PKEY_CTX_set_signature_md , .Nm EVP_PKEY_CTX_get_signature_md , -.Nm RSA_pkey_ctx_ctrl , -.Nm EVP_PKEY_CTX_set_rsa_padding , -.Nm EVP_PKEY_CTX_get_rsa_padding , -.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen , -.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen , -.Nm EVP_PKEY_CTX_set_rsa_keygen_bits , -.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp , -.Nm EVP_PKEY_CTX_set_rsa_mgf1_md , -.Nm EVP_PKEY_CTX_get_rsa_mgf1_md , -.Nm EVP_PKEY_CTX_set_rsa_oaep_md , -.Nm EVP_PKEY_CTX_get_rsa_oaep_md , -.Nm EVP_PKEY_CTX_set0_rsa_oaep_label , -.Nm EVP_PKEY_CTX_get0_rsa_oaep_label , .Nm EVP_PKEY_CTX_set_dsa_paramgen_bits , .Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len , .Nm EVP_PKEY_CTX_set_dh_paramgen_generator , @@ -118,76 +106,6 @@ .Fa "EVP_PKEY_CTX *ctx" .Fa "const EVP_MD **pmd" .Fc -.In openssl/rsa.h -.Ft int -.Fo RSA_pkey_ctx_ctrl -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int optype" -.Fa "int cmd" -.Fa "int p1" -.Fa "void *p2" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_padding -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int pad" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_get_rsa_padding -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int *ppad" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int len" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_get_rsa_pss_saltlen -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int *plen" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_keygen_bits -.Fa "EVP_PKEY_CTX *ctx" -.Fa "int mbits" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp -.Fa "EVP_PKEY_CTX *ctx" -.Fa "BIGNUM *pubexp" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_mgf1_md -.Fa "EVP_PKEY_CTX *ctx" -.Fa "const EVP_MD *md" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_get_rsa_mgf1_md -.Fa "EVP_PKEY_CTX *ctx" -.Fa "const EVP_MD **pmd" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set_rsa_oaep_md -.Fa "EVP_PKEY_CTX *ctx" -.Fa "const EVP_MD *md" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_get_rsa_oaep_md -.Fa "EVP_PKEY_CTX *ctx" -.Fa "const EVP_MD **pmd" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_set0_rsa_oaep_label -.Fa "EVP_PKEY_CTX *ctx" -.Fa "unsigned char *label" -.Fa "int len" -.Fc -.Ft int -.Fo EVP_PKEY_CTX_get0_rsa_oaep_label -.Fa "EVP_PKEY_CTX *ctx" -.Fa "unsigned char **plabel" -.Fc .In openssl/dsa.h .Ft int .Fo EVP_PKEY_CTX_set_dsa_paramgen_bits @@ -302,7 +220,8 @@ and Applications will not normally call .Fn EVP_PKEY_CTX_ctrl directly but will instead call one of the algorithm specific macros -below. +described below and in +.Xr RSA_pkey_ctx_ctrl 3 . .Pp The function .Fn EVP_PKEY_CTX_ctrl_str @@ -331,156 +250,6 @@ and .Fn EVP_PKEY_CTX_get_signature_md macros set and get the message digest type used in a signature. They can be used with the RSA, DSA, and ECDSA algorithms. -.Ss RSA parameters -The -.Fn RSA_pkey_ctx_ctrl -function is a shallow wrapper around -.Fn EVP_PKEY_CTX_ctrl -which only succeeds if -.Fa ctx -matches either -.Dv EVP_PKEY_RSA -or -.Dv EVP_PKEY_RSA_PSS . -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_padding -macro sets the RSA padding mode for -.Fa ctx . -The -.Fa pad -parameter can take the value -.Dv RSA_PKCS1_PADDING -for PKCS#1 padding, -.Dv RSA_NO_PADDING -for no padding, -.Dv RSA_PKCS1_OAEP_PADDING -for OAEP padding (encrypt and decrypt only), -.Dv RSA_X931_PADDING -for X9.31 padding (signature operations only) and -.Dv RSA_PKCS1_PSS_PADDING -(sign and verify only). -.Pp -Two RSA padding modes behave differently if -.Fn EVP_PKEY_CTX_set_signature_md -is used. -If this macro is called for PKCS#1 padding, the plaintext buffer is an -actual digest value and is encapsulated in a -.Vt DigestInfo -structure according to PKCS#1 when signing and this structure is -expected (and stripped off) when verifying. -If this control is not used with RSA and PKCS#1 padding then the -supplied data is used directly and not encapsulated. -In the case of X9.31 padding for RSA the algorithm identifier byte is -added or checked and removed if this control is called. -If it is not called then the first byte of the plaintext buffer is -expected to be the algorithm identifier byte. -.Pp -The -.Fn EVP_PKEY_CTX_get_rsa_padding -macro retrieves the RSA padding mode for -.Fa ctx . -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen -macro sets the RSA PSS salt length to -.Fa len . -As its name implies, it is only supported for PSS padding. -Two special values are supported: -1 sets the salt length to the digest -length. -When signing -2 sets the salt length to the maximum permissible value. -When verifying -2 causes the salt length to be automatically determined -based on the PSS block structure. -If this macro is not called a salt length value of -2 is used by -default. -.Pp -The -.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen -macro retrieves the RSA PSS salt length for -.Fa ctx . -The padding mode must have been set to -.Dv RSA_PKCS1_PSS_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_keygen_bits -macro sets the RSA key length for RSA key generation to -.Fa mbits . -The smallest supported value is 512 bits. -If not specified, 1024 bits is used. -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp -macro sets the public exponent value for RSA key generation to -.Fa pubexp . -Currently, it should be an odd integer. -The -.Fa pubexp -pointer is used internally by this function, so it should not be modified -or freed after the call. -If this macro is not called, then 65537 is used. -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_mgf1_md -macro sets the MGF1 digest for RSA padding schemes to -.Fa md . -Unless explicitly specified, the signing digest is used. -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING -or -.Dv RSA_PKCS1_PSS_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_get_rsa_mgf1_md -macro retrieves the MGF1 digest for -.Fa ctx . -Unless explicitly specified, the signing digest is used. -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING -or -.Dv RSA_PKCS1_PSS_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_set_rsa_oaep_md -macro sets the message digest type used in RSA OAEP to -.Fa md . -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_get_rsa_oaep_md -macro gets the message digest type used in RSA OAEP to -.Pf * Fa md . -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_set0_rsa_oaep_label -macro sets the RSA OAEP label to -.Fa label -and its length to -.Fa len . -If -.Fa label -is -.Dv NULL -or -.Fa len -is 0, the label is cleared. -The library takes ownership of the label so the caller should not -free the original memory pointed to by -.Fa label . -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING . -.Pp -The -.Fn EVP_PKEY_CTX_get0_rsa_oaep_label -macro gets the RSA OAEP label to -.Pf * Fa plabel . -The return value is the label length. -The padding mode must have been set to -.Dv RSA_PKCS1_OAEP_PADDING . -The resulting pointer is owned by the library and should not be -freed by the caller. .Ss DSA parameters The macro .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits @@ -652,16 +421,13 @@ supported by the public key algorithm. .Xr EVP_PKEY_meth_set_ctrl 3 , .Xr EVP_PKEY_sign 3 , .Xr EVP_PKEY_verify 3 , -.Xr EVP_PKEY_verify_recover 3 +.Xr EVP_PKEY_verify_recover 3 , +.Xr RSA_pkey_ctx_ctrl 3 .Sh HISTORY The functions .Fn EVP_PKEY_CTX_ctrl , .Fn EVP_PKEY_CTX_ctrl_str , .Fn EVP_PKEY_CTX_set_signature_md , -.Fn EVP_PKEY_CTX_set_rsa_padding , -.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen , -.Fn EVP_PKEY_CTX_set_rsa_keygen_bits , -.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp , .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits , .Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len , .Fn EVP_PKEY_CTX_set_dh_paramgen_generator , @@ -671,15 +437,6 @@ first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . .Pp The functions -.Fn EVP_PKEY_CTX_get_rsa_padding , -.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen , -.Fn EVP_PKEY_CTX_set_rsa_mgf1_md , -and -.Fn EVP_PKEY_CTX_get_rsa_mgf1_md -first appeared in OpenSSL 1.0.1 and have been available since -.Ox 5.3 . -.Pp -The functions .Fn EVP_PKEY_CTX_get_signature_md , .Fn EVP_PKEY_CTX_set_ec_param_enc , .Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode , @@ -703,17 +460,3 @@ and .Fn EVP_PKEY_CTX_get1_id_len first appeared in OpenSSL 1.1.1 and have been available since .Ox 6.6 . -.Pp -The functions -.Fn EVP_PKEY_CTX_set_rsa_oaep_md , -.Fn EVP_PKEY_CTX_get_rsa_oaep_md , -.Fn EVP_PKEY_CTX_set0_rsa_oaep_label , -and -.Fn EVP_PKEY_CTX_get0_rsa_oaep_label -first appeared in OpenSSL 1.0.2 and have been available since -.Ox 6.7 . -.Pp -The function -.Fn RSA_pkey_ctx_ctrl -first appeared in OpenSSL 1.1.1 and has been available since -.Ox 6.7 . diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 840be62d72f..5f1a24eb38c 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.158 2019/08/28 10:37:42 schwarze Exp $ +# $OpenBSD: Makefile,v 1.159 2019/11/01 12:02:58 schwarze Exp $ .include <bsd.own.mk> @@ -220,6 +220,7 @@ MAN= \ RSA_meth_new.3 \ RSA_new.3 \ RSA_padding_add_PKCS1_type_1.3 \ + RSA_pkey_ctx_ctrl.3 \ RSA_print.3 \ RSA_private_encrypt.3 \ RSA_public_encrypt.3 \ diff --git a/lib/libcrypto/man/RSA_new.3 b/lib/libcrypto/man/RSA_new.3 index b0009b85819..9efcbd0b9f9 100644 --- a/lib/libcrypto/man/RSA_new.3 +++ b/lib/libcrypto/man/RSA_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: RSA_new.3,v 1.15 2019/08/23 15:18:13 schwarze Exp $ +.\" $OpenBSD: RSA_new.3,v 1.16 2019/11/01 12:02:58 schwarze Exp $ .\" full merge up to: .\" OpenSSL doc/man3/RSA_new.pod e9b77246 Jan 20 19:58:49 2017 +0100 .\" OpenSSL doc/crypto/rsa.pod 35d2e327 Jun 3 16:19:49 2016 -0400 (final) @@ -67,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 23 2019 $ +.Dd $Mdocdate: November 1 2019 $ .Dt RSA_NEW 3 .Os .Sh NAME @@ -225,6 +225,7 @@ returns 1 for success or 0 for failure. .Xr RSA_get_ex_new_index 3 , .Xr RSA_meth_new 3 , .Xr RSA_padding_add_PKCS1_type_1 3 , +.Xr RSA_pkey_ctx_ctrl 3 , .Xr RSA_print 3 , .Xr RSA_private_encrypt 3 , .Xr RSA_PSS_PARAMS_new 3 , diff --git a/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 b/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 new file mode 100644 index 00000000000..866c63ad810 --- /dev/null +++ b/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 @@ -0,0 +1,346 @@ +.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.1 2019/11/01 12:02:58 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/EVP_PKEY_CTX_ctrl 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: +.\" OpenSSL man3/EVP_PKEY_CTX_ctrl df75c2b f Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson <steve@openssl.org> +.\" and Antoine Salon <asalon@vmware.com>. +.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2018 The OpenSSL Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: November 1 2019 $ +.Dt RSA_PKEY_CTX_CTRL 3 +.Os +.Sh NAME +.Nm RSA_pkey_ctx_ctrl , +.Nm EVP_PKEY_CTX_set_rsa_padding , +.Nm EVP_PKEY_CTX_get_rsa_padding , +.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen , +.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen , +.Nm EVP_PKEY_CTX_set_rsa_keygen_bits , +.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp , +.Nm EVP_PKEY_CTX_set_rsa_mgf1_md , +.Nm EVP_PKEY_CTX_get_rsa_mgf1_md , +.Nm EVP_PKEY_CTX_set_rsa_oaep_md , +.Nm EVP_PKEY_CTX_get_rsa_oaep_md , +.Nm EVP_PKEY_CTX_set0_rsa_oaep_label , +.Nm EVP_PKEY_CTX_get0_rsa_oaep_label +.Nd RSA private key control operations +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_pkey_ctx_ctrl +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int optype" +.Fa "int cmd" +.Fa "int p1" +.Fa "void *p2" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_padding +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int pad" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_padding +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *ppad" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_pss_saltlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *plen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_keygen_bits +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int mbits" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp +.Fa "EVP_PKEY_CTX *ctx" +.Fa "BIGNUM *pubexp" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_mgf1_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_mgf1_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_oaep_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_oaep_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set0_rsa_oaep_label +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *label" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get0_rsa_oaep_label +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char **plabel" +.Fc +.Sh DESCRIPTION +The function +.Fn RSA_pkey_ctx_ctrl +is a shallow wrapper around +.Xr EVP_PKEY_CTX_ctrl 3 +which only succeeds if +.Fa ctx +matches either +.Dv EVP_PKEY_RSA +or +.Dv EVP_PKEY_RSA_PSS . +.Pp +All the remaining "functions" are implemented as macros. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_padding +macro sets the RSA padding mode for +.Fa ctx . +The +.Fa pad +parameter can take the value +.Dv RSA_PKCS1_PADDING +for PKCS#1 padding, +.Dv RSA_NO_PADDING +for no padding, +.Dv RSA_PKCS1_OAEP_PADDING +for OAEP padding (encrypt and decrypt only), +.Dv RSA_X931_PADDING +for X9.31 padding (signature operations only) and +.Dv RSA_PKCS1_PSS_PADDING +(sign and verify only). +.Pp +Two RSA padding modes behave differently if +.Fn EVP_PKEY_CTX_set_signature_md +is used. +If this macro is called for PKCS#1 padding, the plaintext buffer is an +actual digest value and is encapsulated in a +.Vt DigestInfo +structure according to PKCS#1 when signing and this structure is +expected (and stripped off) when verifying. +If this control is not used with RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. +In the case of X9.31 padding for RSA the algorithm identifier byte is +added or checked and removed if this control is called. +If it is not called then the first byte of the plaintext buffer is +expected to be the algorithm identifier byte. +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_padding +macro retrieves the RSA padding mode for +.Fa ctx . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen +macro sets the RSA PSS salt length to +.Fa len . +As its name implies, it is only supported for PSS padding. +Two special values are supported: -1 sets the salt length to the digest +length. +When signing -2 sets the salt length to the maximum permissible value. +When verifying -2 causes the salt length to be automatically determined +based on the PSS block structure. +If this macro is not called a salt length value of -2 is used by +default. +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen +macro retrieves the RSA PSS salt length for +.Fa ctx . +The padding mode must have been set to +.Dv RSA_PKCS1_PSS_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_keygen_bits +macro sets the RSA key length for RSA key generation to +.Fa mbits . +The smallest supported value is 512 bits. +If not specified, 1024 bits is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp +macro sets the public exponent value for RSA key generation to +.Fa pubexp . +Currently, it should be an odd integer. +The +.Fa pubexp +pointer is used internally by this function, so it should not be modified +or freed after the call. +If this macro is not called, then 65537 is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_mgf1_md +macro sets the MGF1 digest for RSA padding schemes to +.Fa md . +Unless explicitly specified, the signing digest is used. +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING +or +.Dv RSA_PKCS1_PSS_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_mgf1_md +macro retrieves the MGF1 digest for +.Fa ctx . +Unless explicitly specified, the signing digest is used. +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING +or +.Dv RSA_PKCS1_PSS_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_oaep_md +macro sets the message digest type used in RSA OAEP to +.Fa md . +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_oaep_md +macro gets the message digest type used in RSA OAEP to +.Pf * Fa md . +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_set0_rsa_oaep_label +macro sets the RSA OAEP label to +.Fa label +and its length to +.Fa len . +If +.Fa label +is +.Dv NULL +or +.Fa len +is 0, the label is cleared. +The library takes ownership of the label so the caller should not +free the original memory pointed to by +.Fa label . +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_get0_rsa_oaep_label +macro gets the RSA OAEP label to +.Pf * Fa plabel . +The return value is the label length. +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING . +The resulting pointer is owned by the library and should not be +freed by the caller. +.Sh RETURN VALUES +These functions return a positive value for success or 0 or a negative +value for failure. +In particular, a return value of -2 indicates the operation is not +supported by the public key algorithm. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_get_default_digest_nid 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_meth_set_ctrl 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +The functions +.Fn EVP_PKEY_CTX_set_rsa_padding , +.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen , +.Fn EVP_PKEY_CTX_set_rsa_keygen_bits , +and +.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +The functions +.Fn EVP_PKEY_CTX_get_rsa_padding , +.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen , +.Fn EVP_PKEY_CTX_set_rsa_mgf1_md , +and +.Fn EVP_PKEY_CTX_get_rsa_mgf1_md +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . +.Pp +The functions +.Fn EVP_PKEY_CTX_set_rsa_oaep_md , +.Fn EVP_PKEY_CTX_get_rsa_oaep_md , +.Fn EVP_PKEY_CTX_set0_rsa_oaep_label , +and +.Fn EVP_PKEY_CTX_get0_rsa_oaep_label +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.7 . +.Pp +The function +.Fn RSA_pkey_ctx_ctrl +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 6.7 . |