In rsa.h rev. 1.45, jsing@ provided the three

macros EVP_PKEY_CTX_set_rsa_pss_keygen_*(3); document them.
Text mostly taken from the OpenSSL 1.1.1 branch, which is still under a
free license, but rearranged to fit the structure of our manual pages.

2 files changed, 64 insertions, 6 deletions

diff --git a/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
index 2bb6a3fd3b2..7714cb05583 100644
--- a/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
+++ b/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.21 2019/11/01 12:02:58 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.22 2019/11/01 13:53:25 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).
@@ -250,6 +250,10 @@ 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.
+If the key is of the type
+.Dv 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.
 .Ss DSA parameters
 The macro
 .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits
diff --git a/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3 b/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
index dea7fe754e7..dbfd9c16f67 100644
--- a/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
+++ b/lib/libcrypto/man/RSA_pkey_ctx_ctrl.3
@@ -1,12 +1,14 @@
-.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.2 2019/11/01 12:45:36 schwarze Exp $
+.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.3 2019/11/01 13:53:25 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" OpenSSL man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
+.\"   87103969 Oct 1 14:11:57 2018 -0700
 .\" selective merge up to:
 .\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod 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.
+.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2017, 2018 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -69,7 +71,10 @@
 .Nm EVP_PKEY_CTX_set0_rsa_oaep_label ,
 .Nm EVP_PKEY_CTX_get0_rsa_oaep_label ,
 .Nm EVP_PKEY_CTX_set_rsa_pss_saltlen ,
-.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen
+.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen ,
+.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_md ,
+.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md ,
+.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
 .Nd RSA private key control operations
 .Sh SYNOPSIS
 .In openssl/rsa.h
@@ -142,6 +147,21 @@
 .Fa "EVP_PKEY_CTX *ctx"
 .Fa "int *plen"
 .Fc
+.Ft int
+.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_md
+.Fa "EVP_PKEY_CTX *pctx"
+.Fa "const EVP_MD *md"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md
+.Fa "EVP_PKEY_CTX *pctx"
+.Fa "const EVP_MD *md"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
+.Fa "EVP_PKEY_CTX *pctx"
+.Fa "int saltlen"
+.Fc
 .Sh DESCRIPTION
 The function
 .Fn RSA_pkey_ctx_ctrl
@@ -173,6 +193,8 @@ for OAEP padding (encrypt and decrypt only),
 for X9.31 padding (signature operations only) and
 .Dv RSA_PKCS1_PSS_PADDING
 (sign and verify only).
+Only the last one can be used with keys of the type
+.Dv EVP_PKEY_RSA_PSS .
 .Pp
 Two RSA padding modes behave differently if
 .Xr EVP_PKEY_CTX_set_signature_md 3
@@ -196,14 +218,14 @@ macro retrieves the RSA padding mode for
 .Pp
 The
 .Fn EVP_PKEY_CTX_set_rsa_keygen_bits
-macro sets the RSA key length for RSA key generation to
+macro sets the RSA key length for RSA or RSA-PSS 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
+macro sets the public exponent value for RSA or RSA-PSS key generation to
 .Fa pubexp .
 Currently, it should be an odd integer.
 The
@@ -221,6 +243,10 @@ The padding mode must have been set to
 .Dv RSA_PKCS1_OAEP_PADDING
 or
 .Dv RSA_PKCS1_PSS_PADDING .
+If the key is of the type
+.Dv 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.
 .Pp
 The
 .Fn EVP_PKEY_CTX_get_rsa_mgf1_md
@@ -285,10 +311,38 @@ based on the PSS block structure.
 If this macro is not called a salt length value of -2 is used by
 default.
 .Pp
+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,
+.Dv RSA_PSS_SALTLEN_AUTO
+is not supported for verification.
+.Pp
 The
 .Fn EVP_PKEY_CTX_get_rsa_pss_saltlen
 macro retrieves the RSA PSS salt length for
 .Fa ctx .
+.Pp
+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 restrictions are in place, then they are reflected in the
+corresponding parameters of the public key when (for example) a
+certificate request is signed.
+.Pp
+.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_md
+restricts the digest algorithm the generated key can use to
+.Fa md .
+.Pp
+.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md
+restricts the MGF1 algorithm the generated key can use to
+.Fa md .
+.Pp
+.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
+restricts the minimum salt length to
+.Fa saltlen .
 .Sh RETURN VALUES
 These functions return a positive value for success or 0 or a negative
 value for failure.