Add documentation for PSS control operations.
[openssl.git] / doc / man3 / EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY_CTX_set_rsa_pss_keygen_md, EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md,
6 EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen - RSA PSS signature algorithm
7
8 =head1 SYNOPSIS
9
10  #include <openssl/rsa.h>
11
12  int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,
13                                         const EVP_MD *md);
14  int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
15                                              const EVP_MD *md);
16  int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,
17                                              int saltlen);
18
19 =head1 DESCRIPTION
20
21 The B<EVP_PKEY_RSA_PSS> algorithm implements the RSA PSS signature algorithm.
22 It is a restricted version of the RSA algorithm which only supports signing,
23 verification and key generation using PSS padding modes with optional
24 parameter restrictions.
25
26 It has associated private key and public key formats.
27
28 This algorithm shares several control operations with the B<RSA> algorithm
29 but with some restrictions described below.
30
31 =head1 SIGNING AND VERIFICATION
32
33 Siging and verification is similar to the B<RSA> algorithm except the
34 padding mode is always PSS. If the key used restricts parameters then
35 the corresponding signature parameters are set to the restrictions:
36 for example if the key can only be used with digest SHA256, MGF1 SHA256
37 and minimum salt length 32 then the digest, MGF1 digest and salt length
38 will be set to SHA256, SHA256 and 32 respectively.
39
40 The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
41 returned if an attempt is made to set the padding mode to anything other
42 than B<PSS>. It is otherwise similar to the B<RSA> version.
43
44 The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
45 If the key is restricted then an error is returned if an attempt is made
46 to set the salt below the minimum value. It is otherwise similar to the
47 B<RSA> operation except special negative values are not supported.
48
49 The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
50 are used to set the digest and MGF1 algorithms respectively. If the key is
51 restricted then an error is returned if an attempt is made to set the
52 digest to anything other than the restricted value. Otherwise these are
53 similar to the B<RSA> versions.
54
55 =head1 KEY GENERATION
56
57 As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
58 and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA PSS:
59 they have exactly the same meaning as for the RSA algorithm.
60
61 Optional parameter restrictions can be specified when generating a PSS key
62 by default no parameter restrictions are placed on a generate key. If any
63 restrictions are set (using the macros described below) then B<all>
64 parameters are restricted: e.g. setting a minimum salt length also restricts
65 the digest and MGF1 algorithms. If any restrictions are in place then
66 they are reflected in the corresponding parameters of the public key
67 when (for example) a certificate request is signed.
68
69 EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
70 generated key can use to B<md>.
71
72 EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the
73 generated key can use to B<md>.
74
75 EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length
76 to B<saltlen>.
77
78 =head1 RETURN VALUES
79
80 All these functions return 1 for success and 0 or a negative value for failure.
81 In particular a return value of -2 indicates the operation is not supported by
82 the public key algorithm.
83
84 =head1 SEE ALSO
85
86 L<EVP_PKEY_CTX_new(3)>,
87 L<EVP_PKEY_CTX_ctrl_str(3)>,
88 L<EVP_PKEY_derive(3)>
89
90 =head1 COPYRIGHT
91
92 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
93
94 Licensed under the OpenSSL license (the "License").  You may not use
95 this file except in compliance with the License.  You can obtain a copy
96 in the file LICENSE in the source distribution or at
97 L<https://www.openssl.org/source/license.html>.
98
99 =cut