lib/libcrypto/man/X509_NAME_get_index_by_NID.3

   1 .\"     $OpenBSD: X509_NAME_get_index_by_NID.3,v 1.10 2018/07/09 09:57:41 tb 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 9 2018 $
  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
 101 These functions allow an
 102 .Vt X509_NAME
 103 structure to be examined.
 104 The
 105 .Vt X509_NAME
 106 structure is the same as the ASN.1
 107 .Vt Name
 108 type defined in RFC 2459 (and elsewhere) and used, for example,
 109 in certificate subject and issuer names.
 110 .Pp
 111 .Fn X509_NAME_get_index_by_NID
 112 and
 113 .Fn X509_NAME_get_index_by_OBJ
 114 retrieve the next index matching
 115 .Fa nid
 116 or
 117 .Fa obj
 118 after
 119 .Fa lastpos .
 120 .Fa lastpos
 121 should initially be set to -1.
 122 If there are no more entries, -1 is returned.
 123 If
 124 .Fa nid
 125 is invalid (doesn't correspond to a valid OID), -2 is returned.
 126 .Pp
 127 .Fn X509_NAME_entry_count
 128 returns the total number of entries in
 129 .Fa name .
 130 .Pp
 131 .Fn X509_NAME_get_entry
 132 retrieves the
 133 .Vt X509_NAME_ENTRY
 134 from
 135 .Fa name
 136 corresponding to index
 137 .Fa loc .
 138 Acceptable values for
 139 .Fa loc
 140 run from 0 to
 141 .Fn X509_NAME_entry_count name
 142 - 1.
 143 The value returned is an internal pointer which must not be freed.
 144 .Pp
 145 .Fn X509_NAME_get_text_by_NID
 146 and
 147 .Fn X509_NAME_get_text_by_OBJ
 148 retrieve the "text" from the first entry in
 149 .Fa name
 150 which matches
 151 .Fa nid
 152 or
 153 .Fa obj .
 154 If no such entry exists, -1 is returned.
 155 At most
 156 .Fa len
 157 bytes will be written and the text written to
 158 .Fa buf
 159 will be NUL terminated.
 160 The length of the output string written is returned excluding the
 161 terminating NUL.
 162 If
 163 .Fa buf
 164 is
 165 .Dv NULL
 166 then the amount of space needed in
 167 .Fa buf
 168 (excluding the final NUL) is returned.
 169 .Pp
 170 All relevant
 171 .Dv NID_*
 172 and
 173 .Dv OBJ_*
 174 codes can be found in the header files
 175 .In openssl/obj_mac.h
 176 and
 177 .In openssl/objects.h .
 178 .Pp
 179 Applications which could pass invalid NIDs to
 180 .Fn X509_NAME_get_index_by_NID
 181 should check for the return value of -2.
 182 Alternatively the NID validity can be determined first by checking that
 183 .Fn OBJ_nid2obj nid
 184 is not
 185 .Dv NULL .
 186 .Sh RETURN VALUES
 187 .Fn X509_NAME_get_index_by_NID
 188 and
 189 .Fn X509_NAME_get_index_by_OBJ
 190 return the index of the next matching entry or -1 if not found.
 191 .Pp
 192 .Fn X509_NAME_entry_count
 193 returns the total number of entries.
 194 .Pp
 195 .Fn X509_NAME_get_entry
 196 returns an
 197 .Vt X509_NAME
 198 pointer to the requested entry or
 199 .Dv NULL
 200 if the index is invalid.
 201 .Sh EXAMPLES
 202 Process all entries:
 203 .Bd -literal
 204 int i;
 205 X509_NAME_ENTRY *e;
 206
 207 for (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
 213 Process all commonName entries:
 214 .Bd -literal
 215 int lastpos = -1;
 216 X509_NAME_ENTRY *e;
 217
 218 for (;;) {
 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 ERR_get_error 3 ,
 229 .Xr X509_NAME_new 3
 230 .Sh HISTORY
 231 These functions first appeared in SSLeay 0.8.0
 232 and have been available since
 233 .Ox 2.4 .
 234 .Sh CAVEATS
 235 .Fn X509_NAME_get_text_by_NID
 236 and
 237 .Fn X509_NAME_get_text_by_OBJ
 238 are legacy functions which have various limitations which make them of
 239 minimal use in practice.
 240 They can only find the first matching entry and will copy the contents
 241 of the field verbatim: this can be highly confusing if the target is a
 242 multicharacter string type like a
 243 .Vt BMPString
 244 or a
 245 .Vt UTF8String .
 246 .Pp
 247 For a more general solution,
 248 .Fn X509_NAME_get_index_by_NID
 249 or
 250 .Fn X509_NAME_get_index_by_OBJ
 251 should be used, followed by
 252 .Fn X509_NAME_get_entry
 253 on any matching indices and then the various
 254 .Vt X509_NAME_ENTRY
 255 utility functions on the result.