1.\" $OpenBSD: X509_NAME_get_index_by_NID.3,v 1.13 2022/07/02 17:09:09 jsing Exp $ 2.\" OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2006, 2014, 2015, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: July 2 2022 $ 53.Dt X509_NAME_GET_INDEX_BY_NID 3 54.Os 55.Sh NAME 56.Nm X509_NAME_get_index_by_NID , 57.Nm X509_NAME_get_index_by_OBJ , 58.Nm X509_NAME_entry_count , 59.Nm X509_NAME_get_entry , 60.Nm X509_NAME_get_text_by_NID , 61.Nm X509_NAME_get_text_by_OBJ 62.Nd X509_NAME lookup and enumeration functions 63.Sh SYNOPSIS 64.In openssl/x509.h 65.Ft int 66.Fo X509_NAME_get_index_by_NID 67.Fa "const X509_NAME *name" 68.Fa "int nid" 69.Fa "int lastpos" 70.Fc 71.Ft int 72.Fo X509_NAME_get_index_by_OBJ 73.Fa "const X509_NAME *name" 74.Fa "const ASN1_OBJECT *obj" 75.Fa "int lastpos" 76.Fc 77.Ft int 78.Fo X509_NAME_entry_count 79.Fa "const X509_NAME *name" 80.Fc 81.Ft X509_NAME_ENTRY * 82.Fo X509_NAME_get_entry 83.Fa "const X509_NAME *name" 84.Fa "int loc" 85.Fc 86.Ft int 87.Fo X509_NAME_get_text_by_NID 88.Fa "X509_NAME *name" 89.Fa "int nid" 90.Fa "char *buf" 91.Fa "int len" 92.Fc 93.Ft int 94.Fo X509_NAME_get_text_by_OBJ 95.Fa "X509_NAME *name" 96.Fa "const ASN1_OBJECT *obj" 97.Fa "char *buf" 98.Fa "int len" 99.Fc 100.Sh DESCRIPTION 101These functions allow an 102.Vt X509_NAME 103structure to be examined. 104The 105.Vt X509_NAME 106structure is the same as the ASN.1 107.Vt Name 108type defined in RFC 2459 (and elsewhere) and used, for example, 109in certificate subject and issuer names. 110.Pp 111.Fn X509_NAME_get_index_by_NID 112and 113.Fn X509_NAME_get_index_by_OBJ 114retrieve the next index matching 115.Fa nid 116or 117.Fa obj 118after 119.Fa lastpos . 120.Fa lastpos 121should initially be set to -1. 122.Pp 123.Fn X509_NAME_get_entry 124retrieves the 125.Vt X509_NAME_ENTRY 126from 127.Fa name 128corresponding to index 129.Fa loc . 130Acceptable values for 131.Fa loc 132run from 0 to 133.Fn X509_NAME_entry_count name 134- 1. 135.Pp 136.Fn X509_NAME_get_text_by_NID 137and 138.Fn X509_NAME_get_text_by_OBJ 139retrieve the "text" from the first entry in 140.Fa name 141which matches 142.Fa nid 143or 144.Fa obj . 145At most 146.Fa len 147bytes will be written and the text written to 148.Fa buf 149will be NUL terminated. 150If 151.Fa buf 152is 153.Dv NULL , 154nothing is written, but the return value is calculated as usual. 155.Pp 156All relevant 157.Dv NID_* 158and 159.Dv OBJ_* 160codes can be found in the 161.In openssl/objects.h 162header file. 163.Pp 164Applications which could pass invalid NIDs to 165.Fn X509_NAME_get_index_by_NID 166should check for the return value of -2. 167Alternatively the NID validity can be determined first by checking that 168.Fn OBJ_nid2obj nid 169is not 170.Dv NULL . 171.Sh RETURN VALUES 172.Fn X509_NAME_get_index_by_NID 173returns the index of the next matching entry, -1 if not found, or -2 if the 174.Fa nid 175does not correspond to a valid OID. 176.Pp 177.Fn X509_NAME_get_index_by_OBJ 178returns the index of the next matching entry or -1 if not found. 179.Pp 180.Fn X509_NAME_entry_count 181returns the total number of entries in 182.Fa name . 183.Pp 184.Fn X509_NAME_get_entry 185returns an internal pointer which must not be freed by the caller or 186.Dv NULL 187if the index is invalid. 188.Pp 189.Fn X509_NAME_get_text_by_NID 190and 191.Fn X509_NAME_get_text_by_OBJ 192return the length of the output string written, not counting the 193terminating NUL, or -1 if no match is found. 194.Pp 195In some cases of failure of 196.Fn X509_NAME_get_index_by_NID 197and 198.Fn X509_NAME_get_text_by_NID , 199the reason can be determined with 200.Xr ERR_get_error 3 . 201.Sh EXAMPLES 202Process all entries: 203.Bd -literal 204int i; 205X509_NAME_ENTRY *e; 206 207for (i = 0; i < X509_NAME_entry_count(nm); i++) { 208 e = X509_NAME_get_entry(nm, i); 209 /* Do something with e */ 210} 211.Ed 212.Pp 213Process all commonName entries: 214.Bd -literal 215int lastpos = -1; 216X509_NAME_ENTRY *e; 217 218for (;;) { 219 lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); 220 if (lastpos == -1) 221 break; 222 e = X509_NAME_get_entry(nm, lastpos); 223 /* Do something with e */ 224} 225.Ed 226.Sh SEE ALSO 227.Xr d2i_X509_NAME 3 , 228.Xr X509_NAME_ENTRY_get_object 3 , 229.Xr X509_NAME_new 3 230.Sh HISTORY 231These functions first appeared in SSLeay 0.8.0 232and have been available since 233.Ox 2.4 . 234.Sh CAVEATS 235.Fn X509_NAME_get_text_by_NID 236and 237.Fn X509_NAME_get_text_by_OBJ 238are legacy functions which have various limitations which make them of 239minimal use in practice. 240They can only find the first matching entry and will copy the contents 241of the field verbatim: this can be highly confusing if the target is a 242multicharacter string type like a 243.Vt BMPString 244or a 245.Vt UTF8String . 246.Pp 247For a more general solution, 248.Fn X509_NAME_get_index_by_NID 249or 250.Fn X509_NAME_get_index_by_OBJ 251should be used, followed by 252.Fn X509_NAME_get_entry 253on any matching indices and then the various 254.Vt X509_NAME_ENTRY 255utility functions on the result. 256