path: root/src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3

.\"	$OpenBSD: X509_NAME_get_index_by_NID.3,v 1.16 2023/05/29 11:54:50 beck Exp $
.\"	OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400
.\"
.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2002, 2006, 2014, 2015, 2016 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 29 2023 $
.Dt X509_NAME_GET_INDEX_BY_NID 3
.Os
.Sh NAME
.Nm X509_NAME_get_index_by_NID ,
.Nm X509_NAME_get_index_by_OBJ ,
.Nm X509_NAME_entry_count ,
.Nm X509_NAME_get_entry ,
.Nm X509_NAME_get_text_by_NID ,
.Nm X509_NAME_get_text_by_OBJ
.Nd X509_NAME lookup and enumeration functions
.Sh SYNOPSIS
.In openssl/x509.h
.Ft int
.Fo X509_NAME_get_index_by_NID
.Fa "const X509_NAME *name"
.Fa "int nid"
.Fa "int lastpos"
.Fc
.Ft int
.Fo X509_NAME_get_index_by_OBJ
.Fa "const X509_NAME *name"
.Fa "const ASN1_OBJECT *obj"
.Fa "int lastpos"
.Fc
.Ft int
.Fo X509_NAME_entry_count
.Fa "const X509_NAME *name"
.Fc
.Ft X509_NAME_ENTRY *
.Fo X509_NAME_get_entry
.Fa "const X509_NAME *name"
.Fa "int loc"
.Fc
.Ft int
.Fo X509_NAME_get_text_by_NID
.Fa "X509_NAME *name"
.Fa "int nid"
.Fa "char *buf"
.Fa "int len"
.Fc
.Ft int
.Fo X509_NAME_get_text_by_OBJ
.Fa "X509_NAME *name"
.Fa "const ASN1_OBJECT *obj"
.Fa "char *buf"
.Fa "int len"
.Fc
.Sh DESCRIPTION
These functions allow an
.Vt X509_NAME
structure to be examined.
The
.Vt X509_NAME
structure is the same as the ASN.1
.Vt Name
type defined in RFC 2459 (and elsewhere) and used, for example,
in certificate subject and issuer names.
.Pp
.Fn X509_NAME_get_index_by_NID
and
.Fn X509_NAME_get_index_by_OBJ
retrieve the next index matching
.Fa nid
or
.Fa obj
after
.Fa lastpos .
.Fa lastpos
should initially be set to -1.
.Pp
.Fn X509_NAME_get_entry
retrieves the
.Vt X509_NAME_ENTRY
from
.Fa name
corresponding to index
.Fa loc .
Acceptable values for
.Fa loc
run from 0 to
.Fn X509_NAME_entry_count name
- 1.
.Pp
.Fn X509_NAME_get_text_by_NID
and
.Fn X509_NAME_get_text_by_OBJ
retrieve the bytes encoded as UTF-8 from the first entry in
.Fa name
which matches
.Fa nid
or
.Fa obj .
If
.Fa buf
is
.Dv NULL ,
nothing is written, but the return value is calculated as usual.
If
.Fa buf
is not
.Dv NULL ,
no more than
.Fa len
bytes will be written and the text written to
.Fa buf
will be NUL terminated.
.Pp
If
.Fa len
is not large enough to hold the NUL byte terminated UTF-8 encoding of
the text, or if the UTF-8 encoding of the text would contains a NUL
byte, no data will be written and the call will return failure.
.Pp
All relevant
.Dv NID_*
and
.Dv OBJ_*
codes can be found in the
.In openssl/objects.h
header file.
.Pp
Applications which could pass invalid NIDs to
.Fn X509_NAME_get_index_by_NID
should check for the return value of -2.
Alternatively the NID validity can be determined first by checking that
.Fn OBJ_nid2obj nid
is not
.Dv NULL .
.Sh RETURN VALUES
.Fn X509_NAME_get_index_by_NID
returns the index of the next matching entry, -1 if not found, or -2 if the
.Fa nid
does not correspond to a valid OID.
.Pp
.Fn X509_NAME_get_index_by_OBJ
returns the index of the next matching entry or -1 if not found.
.Pp
.Fn X509_NAME_entry_count
returns the total number of entries in
.Fa name .
.Pp
.Fn X509_NAME_get_entry
returns an internal pointer which must not be freed by the caller or
.Dv NULL
if the index is invalid.
.Pp
.Fn X509_NAME_get_text_by_NID
and
.Fn X509_NAME_get_text_by_OBJ
return the length of the output UTF-8 string written, not counting the
terminating NUL, or -1 in the case of an error or no match being found.
.Pp
In some cases of failure of
.Fn X509_NAME_get_index_by_NID
and
.Fn X509_NAME_get_text_by_NID ,
the reason can be determined with
.Xr ERR_get_error 3 .
.Sh EXAMPLES
Process all entries:
.Bd -literal
int i;
X509_NAME_ENTRY *e;

for (i = 0; i < X509_NAME_entry_count(nm); i++) {
	e = X509_NAME_get_entry(nm, i);
	/* Do something with e */
}
.Ed
.Pp
Process all commonName entries:
.Bd -literal
int lastpos = -1;
X509_NAME_ENTRY *e;

for (;;) {
	lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
	if (lastpos == -1)
		break;
	e = X509_NAME_get_entry(nm, lastpos);
	/* Do something with e */
}
.Ed
.Sh SEE ALSO
.Xr d2i_X509_NAME 3 ,
.Xr X509_NAME_ENTRY_get_object 3 ,
.Xr X509_NAME_new 3
.Sh HISTORY
These functions first appeared in SSLeay 0.8.0
and have been available since
.Ox 2.4 .
.Sh CAVEATS
.Fn X509_NAME_get_text_by_NID
and
.Fn X509_NAME_get_text_by_OBJ
are legacy functions which have various limitations which make them of
minimal use in practice.
They can only find the first matching entry and will copy the contents
of the field verbatim: this can be highly confusing if the target is a
multicharacter string type like a
.Vt BMPString
or a
.Vt UTF8String .
.Pp
For a more general solution,
.Fn X509_NAME_get_index_by_NID
or
.Fn X509_NAME_get_index_by_OBJ
should be used, followed by
.Fn X509_NAME_get_entry
on any matching indices and then the various
.Vt X509_NAME_ENTRY
utility functions on the result.