1.\" $OpenBSD: X509_NAME_get_index_by_NID.3,v 1.16 2023/05/29 11:54:50 beck 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: May 29 2023 $ 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 bytes encoded as UTF-8 from the first entry in 140.Fa name 141which matches 142.Fa nid 143or 144.Fa obj . 145If 146.Fa buf 147is 148.Dv NULL , 149nothing is written, but the return value is calculated as usual. 150If 151.Fa buf 152is not 153.Dv NULL , 154no more than 155.Fa len 156bytes will be written and the text written to 157.Fa buf 158will be NUL terminated. 159.Pp 160If 161.Fa len 162is not large enough to hold the NUL byte terminated UTF-8 encoding of 163the text, or if the UTF-8 encoding of the text would contains a NUL 164byte, no data will be written and the call will return failure. 165.Pp 166All relevant 167.Dv NID_* 168and 169.Dv OBJ_* 170codes can be found in the 171.In openssl/objects.h 172header file. 173.Pp 174Applications which could pass invalid NIDs to 175.Fn X509_NAME_get_index_by_NID 176should check for the return value of -2. 177Alternatively the NID validity can be determined first by checking that 178.Fn OBJ_nid2obj nid 179is not 180.Dv NULL . 181.Sh RETURN VALUES 182.Fn X509_NAME_get_index_by_NID 183returns the index of the next matching entry, -1 if not found, or -2 if the 184.Fa nid 185does not correspond to a valid OID. 186.Pp 187.Fn X509_NAME_get_index_by_OBJ 188returns the index of the next matching entry or -1 if not found. 189.Pp 190.Fn X509_NAME_entry_count 191returns the total number of entries in 192.Fa name . 193.Pp 194.Fn X509_NAME_get_entry 195returns an internal pointer which must not be freed by the caller or 196.Dv NULL 197if the index is invalid. 198.Pp 199.Fn X509_NAME_get_text_by_NID 200and 201.Fn X509_NAME_get_text_by_OBJ 202return the length of the output UTF-8 string written, not counting the 203terminating NUL, or -1 in the case of an error or no match being found. 204.Pp 205In some cases of failure of 206.Fn X509_NAME_get_index_by_NID 207and 208.Fn X509_NAME_get_text_by_NID , 209the reason can be determined with 210.Xr ERR_get_error 3 . 211.Sh EXAMPLES 212Process all entries: 213.Bd -literal 214int i; 215X509_NAME_ENTRY *e; 216 217for (i = 0; i < X509_NAME_entry_count(nm); i++) { 218 e = X509_NAME_get_entry(nm, i); 219 /* Do something with e */ 220} 221.Ed 222.Pp 223Process all commonName entries: 224.Bd -literal 225int lastpos = -1; 226X509_NAME_ENTRY *e; 227 228for (;;) { 229 lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); 230 if (lastpos == -1) 231 break; 232 e = X509_NAME_get_entry(nm, lastpos); 233 /* Do something with e */ 234} 235.Ed 236.Sh SEE ALSO 237.Xr d2i_X509_NAME 3 , 238.Xr X509_NAME_ENTRY_get_object 3 , 239.Xr X509_NAME_new 3 240.Sh HISTORY 241These functions first appeared in SSLeay 0.8.0 242and have been available since 243.Ox 2.4 . 244.Sh CAVEATS 245.Fn X509_NAME_get_text_by_NID 246and 247.Fn X509_NAME_get_text_by_OBJ 248are legacy functions which have various limitations which make them of 249minimal use in practice. 250They can only find the first matching entry and will copy the contents 251of the field verbatim: this can be highly confusing if the target is a 252multicharacter string type like a 253.Vt BMPString 254or a 255.Vt UTF8String . 256.Pp 257For a more general solution, 258.Fn X509_NAME_get_index_by_NID 259or 260.Fn X509_NAME_get_index_by_OBJ 261should be used, followed by 262.Fn X509_NAME_get_entry 263on any matching indices and then the various 264.Vt X509_NAME_ENTRY 265utility functions on the result. 266