Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
OBJ_NID2OBJ(3) | Library Functions Manual | OBJ_NID2OBJ(3) |
NAME
OBJ_nid2obj
,
OBJ_nid2ln
,
OBJ_nid2sn
,
OBJ_obj2nid
,
OBJ_ln2nid
,
OBJ_sn2nid
,
OBJ_txt2nid
,
OBJ_txt2obj
,
OBJ_obj2txt
,
OBJ_cmp
,
OBJ_dup
,
i2t_ASN1_OBJECT
,
i2a_ASN1_OBJECT
—
inspect and create ASN.1 object identifiers
SYNOPSIS
#include
<openssl/objects.h>
ASN1_OBJECT *
OBJ_nid2obj
(int
n);
const char *
OBJ_nid2ln
(int
n);
const char *
OBJ_nid2sn
(int
n);
int
OBJ_obj2nid
(const
ASN1_OBJECT *o);
int
OBJ_ln2nid
(const
char *ln);
int
OBJ_sn2nid
(const
char *sn);
int
OBJ_txt2nid
(const
char *s);
ASN1_OBJECT *
OBJ_txt2obj
(const
char *s, int no_name);
int
OBJ_obj2txt
(char
*buf, int buf_len,
const ASN1_OBJECT *a,
int no_name);
int
OBJ_cmp
(const
ASN1_OBJECT *a, const ASN1_OBJECT *b);
ASN1_OBJECT *
OBJ_dup
(const
ASN1_OBJECT *o);
#include
<openssl/asn1.h>
int
i2t_ASN1_OBJECT
(char
*buf, int buf_len,
const ASN1_OBJECT *a);
int
i2a_ASN1_OBJECT
(BIO
*out_bio, const ASN1_OBJECT *a);
DESCRIPTION
The ASN.1 object utility functions process ASN1_OBJECT structures which are a representation of the ASN.1 OBJECT IDENTIFIER (OID) type. For convenience, OIDs are usually represented in source code as numeric identifiers, or NIDs. OpenSSL has an internal table of OIDs that are generated when the library is built, and their corresponding NIDs are available as defined constants. For the functions below, application code should treat all returned values — OIDs, NIDs, or names — as constants.OBJ_nid2obj
(),
OBJ_nid2ln
(), and
OBJ_nid2sn
() convert the NID
n to an
ASN1_OBJECT structure, its long name, and its
short name, respectively, or return NULL
if
an error occurred.
OBJ_obj2nid
(),
OBJ_ln2nid
(), and
OBJ_sn2nid
() return the corresponding NID
for the object o, the long name
ln, or the short name
sn, respectively, or
NID_undef
if an error occurred.
OBJ_txt2nid
() returns the NID corresponding
to text string s.
s can be a long name, a short name, or the
numerical representation of an object.
OBJ_txt2obj
() converts the text string
s into an
ASN1_OBJECT structure. If
no_name is 0 then long names and short names
will be interpreted as well as numerical forms. If
no_name is 1, only the numerical form is
acceptable.
OBJ_obj2txt
() converts the
ASN1_OBJECT
a into a textual representation. The
representation is written as a NUL terminated string to
buf. At most
buf_len bytes are written, truncating the
result if necessary. The total amount of space required is returned. If
no_name is 0 and the object has a long or
short name, then that will be used, otherwise the numerical form will be used.
i2t_ASN1_OBJECT
() is the same as
OBJ_obj2txt
() with
no_name set to 0.
i2a_ASN1_OBJECT
() writes a textual
representation of a to
out_bio using
BIO_write(3). It
does not write a terminating NUL byte. If a
is NULL
or contains no data, it writes the
4-byte string “NULL”. If
i2t_ASN1_OBJECT
() fails,
i2a_ASN1_OBJECT
() writes the 9-byte string
“<INVALID>”. Otherwise, it writes the string constructed
with i2t_ASN1_OBJECT
().
OBJ_cmp
() compares
a to b. If
the two are identical, 0 is returned.
OBJ_dup
() returns a deep copy of
o if o is
marked as dynamically allocated. The new object and all data contained in it
is marked as dynamically allocated. If o is
not marked as dynamically allocated,
OBJ_dup
() just returns
o itself.
Objects can have a short name, a long name, and a numerical identifier (NID)
associated with them. A standard set of objects is represented in an internal
table. The appropriate values are defined in the header file
<openssl/objects.h>
.
For example, the OID for commonName has the following definitions:
#define SN_commonName "CN" #define LN_commonName "commonName" #define NID_commonName 13
NID_undef
.
Objects do not need to be in the internal tables to be processed: the functions
OBJ_txt2obj
() and
OBJ_obj2txt
() can process the numerical
form of an OID.
RETURN VALUES
OBJ_nid2obj
(),
OBJ_txt2obj
(), and
OBJ_dup
() return an
ASN1_OBJECT object or
NULL
if an error occurs.
OBJ_nid2ln
() and
OBJ_nid2sn
() return a valid string or
NULL
on error.
OBJ_obj2nid
(),
OBJ_ln2nid
(),
OBJ_sn2nid
(), and
OBJ_txt2nid
() return a NID or
NID_undef
on error.
OBJ_obj2txt
() and
i2t_ASN1_OBJECT
() return the amount of
space required in bytes, including the terminating NUL byte.
i2a_ASN1_OBJECT
() returns the number of bytes
written, even if a is invalid or contains
invalid data, but a negative value if memory allocation or a write operation
fails.
OBJ_cmp
() returns 0 if the contents of
a and b are
identical, or non-zero otherwise.
In some cases of failure of OBJ_nid2obj
(),
OBJ_nid2ln
(),
OBJ_nid2sn
(),
OBJ_txt2nid
(),
OBJ_txt2obj
(),
OBJ_obj2txt
(),
OBJ_dup
(),
i2t_ASN1_OBJECT
(), and
i2a_ASN1_OBJECT
(), the reason can be
determined with
ERR_get_error(3).
EXAMPLES
Create an object for commonName:ASN1_OBJECT *o; o = OBJ_nid2obj(NID_commonName);
if (OBJ_obj2nid(obj) == NID_commonName) /* Do something */
obj = OBJ_txt2obj("1.2.3.4", 1);
SEE ALSO
ASN1_OBJECT_new(3), BIO_new(3), d2i_ASN1_OBJECT(3), OBJ_add_sigid(3), OBJ_create(3), OBJ_NAME_add(3)HISTORY
OBJ_nid2obj
(),
OBJ_nid2ln
(),
OBJ_nid2sn
(),
OBJ_obj2nid
(),
OBJ_ln2nid
(),
OBJ_sn2nid
(),
OBJ_txt2nid
(),
OBJ_cmp
(), and
OBJ_dup
() first appeared in SSLeay 0.5.1.
i2a_ASN1_OBJECT
() first appeared in SSLeay
0.6.0, and i2t_ASN1_OBJECT
() in SSLeay
0.9.0. All these functions have been available since OpenBSD
2.4.
OBJ_txt2obj
() first appeared in OpenSSL
0.9.2b. OBJ_obj2txt
() first appeared in
OpenSSL 0.9.4. Both functions have been available since
OpenBSD 2.6.
BUGS
OBJ_obj2txt
() is awkward and messy to use: it
doesn't follow the convention of other OpenSSL functions where the buffer can
be set to NULL
to determine the amount of
data that should be written. Instead buf must
point to a valid buffer and buf_len should be
set to a positive value. A buffer length of 80 should be more than enough to
handle any OID encountered in practice.March 31, 2022 | Debian |