1 files changed, 245 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
new file mode 100644
index 0000000000..5b1b94653a
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
@@ -0,0 +1,245 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt EVP_PKEY_CTX_CTRL 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_CTX_ctrl ,
+.Nm EVP_PKEY_CTX_ctrl_str ,
+.Nm EVP_PKEY_get_default_digest_nid ,
+.Nm EVP_PKEY_CTX_set_signature_md ,
+.Nm EVP_PKEY_CTX_set_rsa_padding ,
+.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen ,
+.Nm EVP_PKEY_CTX_set_rsa_rsa_keygen_bits ,
+.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp ,
+.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 ,
+.Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid
+.Nd algorithm specific control operations
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft int
+.Fo EVP_PKEY_CTX_ctrl
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int keytype"
+.Fa "int optype"
+.Fa "int cmd"
+.Fa "int p1"
+.Fa "void *p2"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_ctrl_str
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "const char *type"
+.Fa "const char *value"
+.Fc
+.Ft int
+.Fo EVP_PKEY_get_default_digest_nid
+.Fa "EVP_PKEY *pkey"
+.Fa "int *pnid"
+.Fc
+.In openssl/rsa.h
+.Ft int
+.Fo EVP_PKEY_CTX_set_signature_md
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "const EVP_MD *md"
+.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_set_rsa_pss_saltlen
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_set_rsa_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
+.In openssl/dsa.h
+.Ft int
+.Fo EVP_PKEY_CTX_set_dsa_paramgen_bits
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int nbits"
+.Fc
+.In openssl/dh.h
+.Ft int
+.Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_set_dh_paramgen_generator
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int gen"
+.Fc
+.In openssl/ec.h
+.Ft int
+.Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int nid"
+.Fc
+.Sh DESCRIPTION
+The function
+.Fn EVP_PKEY_CTX_ctrl
+sends a control operation to the context
+.Fa ctx .
+The key type used must match
+.Fa keytype
+if it is not -1.
+The parameter
+.Fa optype
+is a mask indicating which operations the control can be applied to.
+The control command is indicated in
+.Fa cmd
+and any additional arguments in
+.Fa p1
+and
+.Fa p2 .
+.Pp
+Applications will not normally call
+.Fn EVP_PKEY_CTX_ctrl
+directly but will instead call one of the algorithm specific macros
+below.
+.Pp
+The function
+.Fn EVP_PKEY_CTX_ctrl_str
+allows an application to send an algorithm specific control operation to
+a context
+.Fa ctx
+in string form.
+This is intended to be used for options specified on the command line or
+in text files.
+The commands supported are documented in the
+.Xr openssl 1
+utility command line pages for the option
+.Fl pkeyopt
+which is supported by the
+.Cm pkeyutl ,
+.Cm genpkey ,
+and
+.Cm req
+commands.
+.Pp
+All the remaining "functions" are implemented as macros.
+.Pp
+The
+.Fn EVP_PKEY_CTX_set_signature_md
+macro sets the message digest type used in a signature.
+It can be used with any public key algorithm supporting signature
+operations.
+.Pp
+The macro
+.Fn EVP_PKEY_CTX_set_rsa_padding
+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_SSLV23_PADDING
+for SSLv23 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 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_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_set_rsa_rsa_keygen_bits
+macro sets the RSA key length for RSA key generation to
+.Fa mbits .
+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 macro
+.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits
+sets the number of bits used for DSA parameter generation to
+.Fa nbits .
+If not specified, 1024 is used.
+.Pp
+The macro
+.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len
+sets the length of the DH prime parameter
+.Fa len
+for DH parameter generation.
+If this macro is not called, then 1024 is used.
+.Pp
+The
+.Fn EVP_PKEY_CTX_set_dh_paramgen_generator
+macro sets DH generator to
+.Fa gen
+for DH parameter generation.
+If not specified, 2 is used.
+.Pp
+The
+.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid
+sets the EC curve for EC parameter generation to
+.Fa nid .
+For EC parameter generation, this macro must be called or an error occurs
+because there is no default curve.
+.Sh RETURN VALUES
+.Fn EVP_PKEY_CTX_ctrl
+and its macros return a positive value for success and 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_PKEY_CTX_new 3 ,
+.Xr EVP_PKEY_decrypt 3 ,
+.Xr EVP_PKEY_derive 3 ,
+.Xr EVP_PKEY_encrypt 3 ,
+.Xr EVP_PKEY_keygen 3 ,
+.Xr EVP_PKEY_sign 3 ,
+.Xr EVP_PKEY_verify 3 ,
+.Xr EVP_PKEY_verify_recover 3
+.Sh HISTORY
+These functions were first added to OpenSSL 1.0.0.