1.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.10 2024/12/06 12:51:13 schwarze Exp $ 2.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2020, 2023 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Richard Levitte <levitte@openssl.org>. 22.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: December 6 2024 $ 69.Dt EVP_PKEY_ASN1_GET_COUNT 3 70.Os 71.Sh NAME 72.Nm EVP_PKEY_asn1_get_count , 73.Nm EVP_PKEY_asn1_get0 , 74.Nm EVP_PKEY_get0_asn1 , 75.Nm EVP_PKEY_asn1_find , 76.Nm EVP_PKEY_asn1_find_str , 77.Nm EVP_PKEY_asn1_get0_info 78.Nd enumerate public key ASN.1 methods 79.Sh SYNOPSIS 80.In openssl/evp.h 81.Ft int 82.Fn EVP_PKEY_asn1_get_count void 83.Ft const EVP_PKEY_ASN1_METHOD * 84.Fo EVP_PKEY_asn1_get0 85.Fa "int idx" 86.Fc 87.Ft const EVP_PKEY_ASN1_METHOD * 88.Fo EVP_PKEY_get0_asn1 89.Fa "const EVP_PKEY *pkey" 90.Fc 91.Ft const EVP_PKEY_ASN1_METHOD * 92.Fo EVP_PKEY_asn1_find 93.Fa "ENGINE **engine" 94.Fa "int type" 95.Fc 96.Ft const EVP_PKEY_ASN1_METHOD * 97.Fo EVP_PKEY_asn1_find_str 98.Fa "ENGINE **engine" 99.Fa "const char *str" 100.Fa "int len" 101.Fc 102.Ft int 103.Fo EVP_PKEY_asn1_get0_info 104.Fa "int *ppkey_id" 105.Fa "int *pkey_base_id" 106.Fa "int *ppkey_flags" 107.Fa "const char **pinfo" 108.Fa "const char **ppem_str" 109.Fa "const EVP_PKEY_ASN1_METHOD *ameth" 110.Fc 111.Sh DESCRIPTION 112.Fn EVP_PKEY_asn1_get_count 113returns the number of public key ASN.1 methods available. 114.Pp 115.Fn EVP_PKEY_asn1_get0 116returns the public key ASN.1 method 117.Fa idx . 118The value of 119.Fa idx 120must be in the range from zero to 121.Fn EVP_PKEY_asn1_get_count 122\- 1. 123.Pp 124.Fn EVP_PKEY_asn1_find 125looks up the method with NID 126.Fa type , 127which can be any of the values that 128.Xr EVP_PKEY_base_id 3 129and 130.Xr EVP_PKEY_id 3 131may return. 132If 133.Fa engine 134is not 135.Dv NULL , 136.Pf * Fa engine 137is set to 138.Dv NULL . 139.Pp 140.Fn EVP_PKEY_asn1_find_str 141looks up the method with the PEM type string given by the first 142.Fa len 143bytes of 144.Fa str . 145If 146.Fa len 147is \-1, the 148.Xr strlen 3 149of 150.Fa str 151is used instead. 152The PEM type strings supported by default are listed in the 153.Xr EVP_PKEY_base_id 3 154manual page. 155Just like 156.Fn EVP_PKEY_asn1_find , 157if 158.Fa engine 159is not 160.Dv NULL , 161.Pf * Fa engine 162is set to 163.Dv NULL . 164.Pp 165.Fn EVP_PKEY_asn1_get0_info 166retrieves the public key ID as returned by 167.Xr EVP_PKEY_id 3 , 168the base public key ID as returned by 169.Xr EVP_PKEY_base_id 3 170.Pq both NIDs , 171any flags, and internal pointers owned by 172.Fa ameth 173pointing to its method description string and its PEM type string. 174.Pp 175The following flags bits can occur, OR'ed together in 176.Pf * Fa ppkey_flags : 177.Bl -tag -width Ds 178.It Dv ASN1_PKEY_ALIAS 179This 180.Fa ameth 181object serves as an alias for another 182.Vt EVP_PKEY_ASN1_METHOD 183object and will never be returned from 184.Fn EVP_PKEY_asn1_find 185or 186.Fn EVP_PKEY_asn1_find_str . 187.It Dv ASN1_PKEY_DYNAMIC 188This flag is unused. 189It could formerly be used to mark an 190.Fa ameth 191object as dynamically allocated. 192.It Dv ASN1_PKEY_SIGPARAM_NULL 193If the signing 194.Fa ctx 195uses an 196.Vt EVP_PKEY 197private key associated with this 198.Fa ameth , 199instruct 200.Xr ASN1_item_sign_ctx 3 201to use a parameter type of 202.Dv V_ASN1_NULL 203instead of the default 204.Dv V_ASN1_UNDEF 205when encoding the ASN.1 206.Vt AlgorithmIdentifier 207objects with 208.Xr X509_ALGOR_set0 3 . 209In particular, this is used for 210.Dv EVP_PKEY_RSA . 211.El 212.Sh RETURN VALUES 213.Fn EVP_PKEY_asn1_get_count 214returns the number of available public key methods. 215.Pp 216.Fn EVP_PKEY_asn1_get0 217returns a public key method or 218.Dv NULL 219if 220.Fa idx 221is out of range. 222.Pp 223.Fn EVP_PKEY_get0_asn1 224returns the public key method used by 225.Fa pkey . 226.Pp 227.Fn EVP_PKEY_asn1_find 228and 229.Fn EVP_PKEY_asn1_find_str 230return a matching public key method or 231.Dv NULL 232if no match is found. 233.Pp 234.Fn EVP_PKEY_asn1_get0_info 235returns 1 on success or 0 on failure. 236.Sh SEE ALSO 237.Xr EVP_PKEY_base_id 3 , 238.Xr EVP_PKEY_new 3 239.Sh HISTORY 240These functions first appeared in OpenSSL 1.0.0 241and have been available since 242.Ox 4.9 . 243