1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_PKEY_is_a, EVP_PKEY_can_sign, EVP_PKEY_type_names_do_all, 6*b077aed3SPierre ProncheryEVP_PKEY_get0_type_name, EVP_PKEY_get0_description, EVP_PKEY_get0_provider 7*b077aed3SPierre Pronchery- key type and capabilities functions 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery=head1 SYNOPSIS 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery #include <openssl/evp.h> 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery int EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name); 14*b077aed3SPierre Pronchery int EVP_PKEY_can_sign(const EVP_PKEY *pkey); 15*b077aed3SPierre Pronchery int EVP_PKEY_type_names_do_all(const EVP_PKEY *pkey, 16*b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 17*b077aed3SPierre Pronchery void *data); 18*b077aed3SPierre Pronchery const char *EVP_PKEY_get0_type_name(const EVP_PKEY *key); 19*b077aed3SPierre Pronchery const char *EVP_PKEY_get0_description(const EVP_PKEY *key); 20*b077aed3SPierre Pronchery const OSSL_PROVIDER *EVP_PKEY_get0_provider(const EVP_PKEY *key); 21*b077aed3SPierre Pronchery 22*b077aed3SPierre Pronchery=head1 DESCRIPTION 23*b077aed3SPierre Pronchery 24*b077aed3SPierre ProncheryEVP_PKEY_is_a() checks if the key type of I<pkey> is I<name>. 25*b077aed3SPierre Pronchery 26*b077aed3SPierre ProncheryEVP_PKEY_can_sign() checks if the functionality for the key type of 27*b077aed3SPierre ProncheryI<pkey> supports signing. No other check is done, such as whether 28*b077aed3SPierre ProncheryI<pkey> contains a private key. 29*b077aed3SPierre Pronchery 30*b077aed3SPierre ProncheryEVP_PKEY_type_names_do_all() traverses all names for I<pkey>'s key type, and 31*b077aed3SPierre Proncherycalls I<fn> with each name and I<data>. For example, an RSA B<EVP_PKEY> may 32*b077aed3SPierre Proncherybe named both C<RSA> and C<rsaEncryption>. 33*b077aed3SPierre ProncheryThe order of the names depends on the provider implementation that holds 34*b077aed3SPierre Proncherythe key. 35*b077aed3SPierre Pronchery 36*b077aed3SPierre ProncheryEVP_PKEY_get0_type_name() returns the first key type name that is found 37*b077aed3SPierre Proncheryfor the given I<pkey>. Note that the I<pkey> may have multiple synonyms 38*b077aed3SPierre Proncheryassociated with it. In this case it depends on the provider implementation 39*b077aed3SPierre Proncherythat holds the key which one will be returned. 40*b077aed3SPierre ProncheryOwnership of the returned string is retained by the I<pkey> object and should 41*b077aed3SPierre Proncherynot be freed by the caller. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryEVP_PKEY_get0_description() returns a description of the type of B<EVP_PKEY>, 44*b077aed3SPierre Proncherymeant for display and human consumption. The description is at the 45*b077aed3SPierre Proncherydiscretion of the key type implementation. 46*b077aed3SPierre Pronchery 47*b077aed3SPierre ProncheryEVP_PKEY_get0_provider() returns the provider of the B<EVP_PKEY>'s 48*b077aed3SPierre ProncheryL<EVP_KEYMGMT(3)>. 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Pronchery=head1 RETURN VALUES 51*b077aed3SPierre Pronchery 52*b077aed3SPierre ProncheryEVP_PKEY_is_a() returns 1 if I<pkey> has the key type I<name>, 53*b077aed3SPierre Proncheryotherwise 0. 54*b077aed3SPierre Pronchery 55*b077aed3SPierre ProncheryEVP_PKEY_can_sign() returns 1 if the I<pkey> key type functionality 56*b077aed3SPierre Proncherysupports signing, otherwise 0. 57*b077aed3SPierre Pronchery 58*b077aed3SPierre ProncheryEVP_PKEY_get0_type_name() returns the name that is found or NULL on error. 59*b077aed3SPierre Pronchery 60*b077aed3SPierre ProncheryEVP_PKEY_get0_description() returns the description if found or NULL if not. 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncheryEVP_PKEY_get0_provider() returns the provider if found or NULL if not. 63*b077aed3SPierre Pronchery 64*b077aed3SPierre ProncheryEVP_PKEY_type_names_do_all() returns 1 if the callback was called for all 65*b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any 66*b077aed3SPierre Proncherynames. 67*b077aed3SPierre Pronchery 68*b077aed3SPierre Pronchery=head1 EXAMPLES 69*b077aed3SPierre Pronchery 70*b077aed3SPierre Pronchery=head2 EVP_PKEY_is_a() 71*b077aed3SPierre Pronchery 72*b077aed3SPierre ProncheryThe loaded providers and what key types they support will ultimately 73*b077aed3SPierre Proncherydetermine what I<name> is possible to use with EVP_PKEY_is_a(). We do know 74*b077aed3SPierre Proncherythat the default provider supports RSA, DH, DSA and EC keys, so we can use 75*b077aed3SPierre Proncherythis as an crude example: 76*b077aed3SPierre Pronchery 77*b077aed3SPierre Pronchery #include <openssl/evp.h> 78*b077aed3SPierre Pronchery 79*b077aed3SPierre Pronchery ... 80*b077aed3SPierre Pronchery /* |pkey| is an EVP_PKEY* */ 81*b077aed3SPierre Pronchery if (EVP_PKEY_is_a(pkey, "RSA")) { 82*b077aed3SPierre Pronchery BIGNUM *modulus = NULL; 83*b077aed3SPierre Pronchery if (EVP_PKEY_get_bn_param(pkey, "n", &modulus)) 84*b077aed3SPierre Pronchery /* do whatever with the modulus */ 85*b077aed3SPierre Pronchery BN_free(modulus); 86*b077aed3SPierre Pronchery } 87*b077aed3SPierre Pronchery 88*b077aed3SPierre Pronchery=head2 EVP_PKEY_can_sign() 89*b077aed3SPierre Pronchery 90*b077aed3SPierre Pronchery #include <openssl/evp.h> 91*b077aed3SPierre Pronchery 92*b077aed3SPierre Pronchery ... 93*b077aed3SPierre Pronchery /* |pkey| is an EVP_PKEY* */ 94*b077aed3SPierre Pronchery if (!EVP_PKEY_can_sign(pkey)) { 95*b077aed3SPierre Pronchery fprintf(stderr, "Not a signing key!"); 96*b077aed3SPierre Pronchery exit(1); 97*b077aed3SPierre Pronchery } 98*b077aed3SPierre Pronchery /* Sign something... */ 99*b077aed3SPierre Pronchery 100*b077aed3SPierre Pronchery=head1 HISTORY 101*b077aed3SPierre Pronchery 102*b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 103*b077aed3SPierre Pronchery 104*b077aed3SPierre Pronchery=head1 COPYRIGHT 105*b077aed3SPierre Pronchery 106*b077aed3SPierre ProncheryCopyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 107*b077aed3SPierre Pronchery 108*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 109*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 110*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 111*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 112*b077aed3SPierre Pronchery 113*b077aed3SPierre Pronchery=cut 114