]>
Commit | Line | Data |
---|---|---|
a8ca496d RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_PKEY_CTX_set_rsa_pss_keygen_md, | |
6 | EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md, | |
7 | EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen | |
8 | - EVP_PKEY RSA-PSS algorithm support functions | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/rsa.h> | |
13 | ||
14 | int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx, | |
15 | const EVP_MD *md); | |
16 | int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx, | |
17 | const EVP_MD *md); | |
18 | int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx, | |
19 | int saltlen); | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | These are the functions that implement L<RSA-PSS(7)>. | |
24 | ||
25 | =head2 Signing and Verification | |
26 | ||
27 | The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is | |
28 | returned if an attempt is made to set the padding mode to anything other | |
29 | than B<PSS>. It is otherwise similar to the B<RSA> version. | |
30 | ||
31 | The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length. | |
32 | If the key has usage restrictions then an error is returned if an attempt is | |
33 | made to set the salt length below the minimum value. It is otherwise similar | |
34 | to the B<RSA> operation except detection of the salt length (using | |
ffd89124 | 35 | RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has |
a8ca496d RL |
36 | usage restrictions. |
37 | ||
d8fef6da MC |
38 | The L<EVP_PKEY_CTX_set_signature_md(3)> and L<EVP_PKEY_CTX_set_rsa_mgf1_md(3)> |
39 | fuunctions are used to set the digest and MGF1 algorithms respectively. If the | |
40 | key has usage restrictions then an error is returned if an attempt is made to | |
41 | set the digest to anything other than the restricted value. Otherwise these are | |
a8ca496d RL |
42 | similar to the B<RSA> versions. |
43 | ||
44 | =head2 Key Generation | |
45 | ||
ffd89124 | 46 | As with RSA key generation the EVP_PKEY_CTX_set_rsa_keygen_bits() |
a8ca496d RL |
47 | and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS: |
48 | they have exactly the same meaning as for the RSA algorithm. | |
49 | ||
50 | Optional parameter restrictions can be specified when generating a PSS key. | |
51 | If any restrictions are set (using the macros described below) then B<all> | |
52 | parameters are restricted. For example, setting a minimum salt length also | |
53 | restricts the digest and MGF1 algorithms. If any restrictions are in place | |
54 | then they are reflected in the corresponding parameters of the public key | |
55 | when (for example) a certificate request is signed. | |
56 | ||
57 | EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the | |
58 | generated key can use to B<md>. | |
59 | ||
60 | EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the | |
61 | generated key can use to B<md>. | |
62 | ||
63 | EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length | |
64 | to B<saltlen>. | |
65 | ||
66 | =head1 NOTES | |
67 | ||
68 | A context for the B<RSA-PSS> algorithm can be obtained by calling: | |
69 | ||
70 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL); | |
71 | ||
72 | =head1 RETURN VALUES | |
73 | ||
74 | All these functions return 1 for success and 0 or a negative value for failure. | |
75 | In particular a return value of -2 indicates the operation is not supported by | |
76 | the public key algorithm. | |
77 | ||
78 | =head1 SEE ALSO | |
79 | ||
80 | L<RSA-PSS(7)>, | |
81 | L<EVP_PKEY_CTX_new(3)>, | |
82 | L<EVP_PKEY_CTX_ctrl_str(3)>, | |
83 | L<EVP_PKEY_derive(3)> | |
84 | ||
85 | =head1 COPYRIGHT | |
86 | ||
87 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. | |
88 | ||
4746f25a | 89 | Licensed under the Apache License 2.0 (the "License"). You may not use |
a8ca496d RL |
90 | this file except in compliance with the License. You can obtain a copy |
91 | in the file LICENSE in the source distribution or at | |
92 | L<https://www.openssl.org/source/license.html>. | |
93 | ||
94 | =cut |