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