1.\" $OpenBSD: X509_NAME_get_index_by_NID.3,v 1.12 2019/06/14 13:59:32 schwarze 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: June 14 2019 $ 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 header files 161.In openssl/obj_mac.h 162and 163.In openssl/objects.h . 164.Pp 165Applications which could pass invalid NIDs to 166.Fn X509_NAME_get_index_by_NID 167should check for the return value of -2. 168Alternatively the NID validity can be determined first by checking that 169.Fn OBJ_nid2obj nid 170is not 171.Dv NULL . 172.Sh RETURN VALUES 173.Fn X509_NAME_get_index_by_NID 174returns the index of the next matching entry, -1 if not found, or -2 if the 175.Fa nid 176does not correspond to a valid OID. 177.Pp 178.Fn X509_NAME_get_index_by_OBJ 179returns the index of the next matching entry or -1 if not found. 180.Pp 181.Fn X509_NAME_entry_count 182returns the total number of entries in 183.Fa name . 184.Pp 185.Fn X509_NAME_get_entry 186returns an internal pointer which must not be freed by the caller or 187.Dv NULL 188if the index is invalid. 189.Pp 190.Fn X509_NAME_get_text_by_NID 191and 192.Fn X509_NAME_get_text_by_OBJ 193return the length of the output string written, not counting the 194terminating NUL, or -1 if no match is found. 195.Pp 196In some cases of failure of 197.Fn X509_NAME_get_index_by_NID 198and 199.Fn X509_NAME_get_text_by_NID , 200the reason can be determined with 201.Xr ERR_get_error 3 . 202.Sh EXAMPLES 203Process all entries: 204.Bd -literal 205int i; 206X509_NAME_ENTRY *e; 207 208for (i = 0; i < X509_NAME_entry_count(nm); i++) { 209 e = X509_NAME_get_entry(nm, i); 210 /* Do something with e */ 211} 212.Ed 213.Pp 214Process all commonName entries: 215.Bd -literal 216int lastpos = -1; 217X509_NAME_ENTRY *e; 218 219for (;;) { 220 lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); 221 if (lastpos == -1) 222 break; 223 e = X509_NAME_get_entry(nm, lastpos); 224 /* Do something with e */ 225} 226.Ed 227.Sh SEE ALSO 228.Xr d2i_X509_NAME 3 , 229.Xr X509_NAME_ENTRY_get_object 3 , 230.Xr X509_NAME_new 3 231.Sh HISTORY 232These functions first appeared in SSLeay 0.8.0 233and have been available since 234.Ox 2.4 . 235.Sh CAVEATS 236.Fn X509_NAME_get_text_by_NID 237and 238.Fn X509_NAME_get_text_by_OBJ 239are legacy functions which have various limitations which make them of 240minimal use in practice. 241They can only find the first matching entry and will copy the contents 242of the field verbatim: this can be highly confusing if the target is a 243multicharacter string type like a 244.Vt BMPString 245or a 246.Vt UTF8String . 247.Pp 248For a more general solution, 249.Fn X509_NAME_get_index_by_NID 250or 251.Fn X509_NAME_get_index_by_OBJ 252should be used, followed by 253.Fn X509_NAME_get_entry 254on any matching indices and then the various 255.Vt X509_NAME_ENTRY 256utility functions on the result. 257