Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RSA_PKEY_CTX_CTRL(3)   FreeBSD Library Functions Manual	  RSA_PKEY_CTX_CTRL(3)

NAME
     RSA_pkey_ctx_ctrl,	EVP_PKEY_CTX_set_rsa_padding,
     EVP_PKEY_CTX_get_rsa_padding, EVP_PKEY_CTX_set_rsa_keygen_bits,
     EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_rsa_mgf1_md,
     EVP_PKEY_CTX_get_rsa_mgf1_md, EVP_PKEY_CTX_set_rsa_oaep_md,
     EVP_PKEY_CTX_get_rsa_oaep_md, EVP_PKEY_CTX_set0_rsa_oaep_label,
     EVP_PKEY_CTX_get0_rsa_oaep_label, EVP_PKEY_CTX_set_rsa_pss_saltlen,
     EVP_PKEY_CTX_get_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_pss_keygen_md,
     EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md,
     EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen --	RSA private key	control	opera-
     tions

SYNOPSIS
     #include <openssl/rsa.h>

     int
     RSA_pkey_ctx_ctrl(EVP_PKEY_CTX *ctx, int optype, int cmd, int p1,
	 void *p2);

     int
     EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);

     int
     EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *ppad);

     int
     EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);

     int
     EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);

     int
     EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);

     int
     EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);

     int
     EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);

     int
     EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);

     int
     EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label,
	 int len);

     int
     EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx,
	 unsigned char **plabel);

     int
     EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);

     int
     EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *plen);

     int
     EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);

     int
     EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
	 const EVP_MD *md);

     int
     EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx, int saltlen);

DESCRIPTION
     The function RSA_pkey_ctx_ctrl() is a shallow wrapper around
     EVP_PKEY_CTX_ctrl(3) which	only succeeds if ctx matches either
     EVP_PKEY_RSA or EVP_PKEY_RSA_PSS.

     All the remaining "functions" are implemented as macros.

     The EVP_PKEY_CTX_set_rsa_padding()	macro sets the RSA padding mode	for
     ctx.  The pad parameter can take the value	RSA_PKCS1_PADDING for PKCS#1
     padding, RSA_NO_PADDING for no padding, RSA_PKCS1_OAEP_PADDING for	OAEP
     padding (encrypt and decrypt only), RSA_X931_PADDING for X9.31 padding
     (signature	operations only) and RSA_PKCS1_PSS_PADDING (sign and verify
     only).  Only the last one can be used with	keys of	the type
     EVP_PKEY_RSA_PSS.

     Two RSA padding modes behave differently if
     EVP_PKEY_CTX_set_signature_md(3) is used.	If this	macro is called	for
     PKCS#1 padding, the plaintext buffer is an	actual digest value and	is en-
     capsulated	in a 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	plain-
     text buffer is expected to	be the algorithm identifier byte.

     The EVP_PKEY_CTX_get_rsa_padding()	macro retrieves	the RSA	padding	mode
     for ctx.

     The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for
     RSA or RSA-PSS key	generation to mbits.  The smallest supported value is
     512 bits.	If not specified, 1024 bits is used.

     The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent
     value for RSA or RSA-PSS key generation to	pubexp.	 Currently, it should
     be	an odd integer.	 The pubexp pointer is used internally by this func-
     tion, so it should	not be modified	or freed after the call.  If this
     macro is not called, then 65537 is	used.

     The EVP_PKEY_CTX_set_rsa_mgf1_md()	macro sets the MGF1 digest for RSA
     padding schemes to	md.  Unless explicitly specified, the signing digest
     is	used.  The padding mode	must have been set to RSA_PKCS1_OAEP_PADDING
     or	RSA_PKCS1_PSS_PADDING.	If the key is of the type EVP_PKEY_RSA_PSS and
     has usage restrictions, an	error occurs if	an attempt is made to set the
     digest to anything	other than the restricted value.

     The EVP_PKEY_CTX_get_rsa_mgf1_md()	macro retrieves	the MGF1 digest	for
     ctx.  Unless explicitly specified,	the signing digest is used.  The pad-
     ding mode must have been set to RSA_PKCS1_OAEP_PADDING or
     RSA_PKCS1_PSS_PADDING.

   Optimal asymmetric encryption padding
     The following macros require that the padding mode	was set	to
     RSA_PKCS1_OAEP_PADDING.

     The EVP_PKEY_CTX_set_rsa_oaep_md()	macro sets the message digest type
     used in RSA OAEP to md.

     The EVP_PKEY_CTX_get_rsa_oaep_md()	macro gets the message digest type
     used in RSA OAEP to *pmd.

     The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to
     label and its length to len.  If label is NULL or 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	label.

     The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to
     *plabel.  The return value	is the label length.  The resulting pointer is
     owned by the library and should not be freed by the caller.

   Probabilistic signature scheme
     The following macros require that the padding mode	was set	to
     RSA_PKCS1_PSS_PADDING.

     The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt	length
     to	len.  Three special values are supported: RSA_PSS_SALTLEN_DIGEST sets
     the salt length to	the digest length.  RSA_PSS_SALTLEN_MAX	sets the salt
     length to the maximum permissible value.  When signing,
     RSA_PSS_SALTLEN_AUTO sets the salt	length to the maximum permissible
     value.  When verifying, RSA_PSS_SALTLEN_AUTO 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 RSA_PSS_SALTLEN_AUTO	is used	by de-
     fault.

     If	the key	has usage restrictions and an attempt is made to set the salt
     length below the minimum value, an	error occurs.  Also, if	the key	has
     usage restrictions, RSA_PSS_SALTLEN_AUTO is not supported for verifica-
     tion.

     The EVP_PKEY_CTX_get_rsa_pss_saltlen() macro retrieves the	RSA PSS	salt
     length for	ctx.

     Optional parameter	restrictions can be specified when generating a	PSS
     key.  If any restrictions are set using the macros	described below, then
     all parameters are	restricted.  For example, setting a minimum salt
     length also restricts the digest and MGF1 algorithms.  If any restric-
     tions are in place, then they are reflected in the	corresponding parame-
     ters of the public	key when (for example) a certificate request is
     signed.

     EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the	digest algorithm the
     generated key can use to md.

     EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm
     the generated key can use to md.

     EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt
     length to saltlen.

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 op-
     eration is	not supported by the public key	algorithm.

SEE ALSO
     EVP_DigestInit(3),	EVP_PKEY_CTX_ctrl(3), EVP_PKEY_CTX_new(3),
     EVP_PKEY_decrypt(3), EVP_PKEY_derive(3), EVP_PKEY_encrypt(3),
     EVP_PKEY_get_default_digest_nid(3), EVP_PKEY_keygen(3),
     EVP_PKEY_meth_set_ctrl(3),	EVP_PKEY_sign(3), EVP_PKEY_verify(3),
     EVP_PKEY_verify_recover(3)

HISTORY
     The functions EVP_PKEY_CTX_set_rsa_padding(),
     EVP_PKEY_CTX_set_rsa_keygen_bits(), EVP_PKEY_CTX_set_rsa_keygen_pubexp(),
     and EVP_PKEY_CTX_set_rsa_pss_saltlen() first appeared in OpenSSL 1.0.0
     and have been available since OpenBSD 4.9.

     The functions EVP_PKEY_CTX_get_rsa_padding(),
     EVP_PKEY_CTX_set_rsa_mgf1_md(), EVP_PKEY_CTX_get_rsa_mgf1_md(), and
     EVP_PKEY_CTX_get_rsa_pss_saltlen()	first appeared in OpenSSL 1.0.1	and
     have been available since OpenBSD 5.3.

     The functions EVP_PKEY_CTX_set_rsa_oaep_md(),
     EVP_PKEY_CTX_get_rsa_oaep_md(), EVP_PKEY_CTX_set0_rsa_oaep_label(), and
     EVP_PKEY_CTX_get0_rsa_oaep_label()	first appeared in OpenSSL 1.0.2	and
     have been available since OpenBSD 6.7.

     The function RSA_pkey_ctx_ctrl() first appeared in	OpenSSL	1.1.1 and has
     been available since OpenBSD 6.7.

FreeBSD	13.0		       November	1, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RSA_pkey_ctx_ctrl&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help