]>
Commit | Line | Data |
---|---|---|
4f76d62f RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ae12eac0 RL |
5 | EVP_PKEY_is_a, EVP_PKEY_can_sign, EVP_PKEY_typenames_do_all, |
6 | EVP_PKEY_get0_first_alg_name | |
4f76d62f RL |
7 | - key type and capabilities functions |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/evp.h> | |
12 | ||
13 | int EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name); | |
14 | int EVP_PKEY_can_sign(const EVP_PKEY *pkey); | |
d84f5515 MC |
15 | int EVP_PKEY_typenames_do_all(const EVP_PKEY *pkey, |
16 | void (*fn)(const char *name, void *data), | |
17 | void *data); | |
3f96b687 MC |
18 | const char *EVP_PKEY_get0_first_alg_name(const EVP_PKEY *key); |
19 | ||
4f76d62f RL |
20 | =head1 DESCRIPTION |
21 | ||
22 | EVP_PKEY_is_a() checks if the key type of I<pkey> is I<name>. | |
23 | ||
24 | EVP_PKEY_can_sign() checks if the functionality for the key type of | |
25 | I<pkey> supports signing. No other check is done, such as whether | |
26 | I<pkey> contains a private key. | |
27 | ||
ae12eac0 RL |
28 | EVP_PKEY_typenames_do_all() traverses all names for I<pkey>'s key type, and |
29 | calls I<fn> with each name and I<data>. For example, an RSA B<EVP_PKEY> may | |
30 | be named both C<RSA> and C<rsaEncryption>. | |
31 | The order of the names is undefined. | |
32 | ||
3f96b687 MC |
33 | EVP_PKEY_get0_first_alg_name() returns the first algorithm name that is found |
34 | for the given I<pkey>. Note that the I<pkey> may have multiple synonyms | |
35 | associated with it. In this case it is undefined which one will be returned. | |
36 | Ownership of the returned string is retained by the I<pkey> object and should | |
37 | not be freed by the caller. | |
38 | ||
4f76d62f RL |
39 | =head1 RETURN VALUES |
40 | ||
41 | EVP_PKEY_is_a() returns 1 if I<pkey> has the key type I<name>, | |
42 | otherwise 0. | |
43 | ||
44 | EVP_PKEY_can_sign() returns 1 if the I<pkey> key type functionality | |
45 | supports signing, otherwise 0. | |
46 | ||
3f96b687 MC |
47 | EVP_PKEY_get0_first_alg_name() returns the name that is found or NULL on error. |
48 | ||
d84f5515 MC |
49 | EVP_PKEY_typenames_do_all() returns 1 if the callback was called for all names. |
50 | A return value of 0 means that the callback was not called for any names. | |
51 | ||
4f76d62f RL |
52 | =head1 EXAMPLES |
53 | ||
54 | =head2 EVP_PKEY_is_a() | |
55 | ||
56 | The loaded providers and what key types they support will ultimately | |
57 | determine what I<name> is possible to use with EVP_PKEY_is_a(). We do know | |
58 | that the default provider supports RSA, DH, DSA and EC keys, so we can use | |
59 | this as an crude example: | |
60 | ||
61 | #include <openssl/evp.h> | |
62 | ||
63 | ... | |
64 | /* |pkey| is an EVP_PKEY* */ | |
65 | if (EVP_PKEY_is_a(pkey, "RSA")) { | |
66 | BIGNUM *modulus = NULL; | |
67 | if (EVP_PKEY_get_bn_param(pkey, "n", &modulus)) | |
68 | /* do whatever with the modulus */ | |
69 | BN_free(modulus); | |
70 | } | |
71 | ||
72 | =head2 EVP_PKEY_can_sign() | |
73 | ||
74 | #include <openssl/evp.h> | |
75 | ||
76 | ... | |
77 | /* |pkey| is an EVP_PKEY* */ | |
78 | if (!EVP_PKEY_can_sign(pkey)) { | |
79 | fprintf(stderr, "Not a signing key!"); | |
80 | exit(1); | |
81 | } | |
82 | /* Sign something... */ | |
83 | ||
3f96b687 MC |
84 | =head1 HISTORY |
85 | ||
86 | The functions described here were added in OpenSSL 3.0. | |
87 | ||
4f76d62f RL |
88 | =head1 COPYRIGHT |
89 | ||
90 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
91 | ||
92 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
93 | this file except in compliance with the License. You can obtain a copy | |
94 | in the file LICENSE in the source distribution or at | |
95 | L<https://www.openssl.org/source/license.html>. | |
96 | ||
97 | =cut |