-*- mode: troff; coding: utf-8 -*-
Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
Standard preamble:
========================================================================
..
.... \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================
Title "OBJ_nid2obj 3"
way too many mistakes in technical documents.
The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros\|(7):
.Vb 1 void OBJ_cleanup(void); .Ve
\fBOBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID n to an ASN1_OBJECT structure, its long name and its short name respectively, or NULL if an error occurred.
\fBOBJ_obj2nid(), OBJ_ln2nid(), 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.
\fBOBJ_txt2nid() returns NID corresponding to text string s. s can be a long name, a short name or the numerical representation of an object.
\fBOBJ_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.
\fBOBJ_obj2txt() converts the ASN1_OBJECT a into a textual representation. Unless buf is NULL, the representation is written as a NUL-terminated string to buf, where at most buf_len bytes are written, truncating the result if necessary. In any case it returns the total string length, excluding the NUL character, required for non-truncated representation, or -1 on error. If no_name is 0 then if the object has a long or short name then that will be used, otherwise the numerical form will be used. If no_name is 1 then the numerical form will always be used.
\fBi2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the no_name set to zero.
\fBOBJ_cmp() compares a to b. If the two are identical 0 is returned.
\fBOBJ_dup() returns a copy of o.
\fBOBJ_create() adds a new object to the internal table. oid is the numerical form of the object, sn the short name and ln the long name. A new NID is returned for the created object in case of success and NID_undef in case of failure.
\fBOBJ_length() returns the size of the content octets of obj.
\fBOBJ_get0_data() returns a pointer to the content octets of obj. The returned pointer is an internal pointer which must not be freed.
\fBOBJ_add_sigid() creates a new composite "Signature Algorithm" that associates a given NID with two other NIDs - one representing the underlying signature algorithm and the other representing a digest algorithm to be used in conjunction with it. signid represents the NID for the composite "Signature Algorithm", dig_id is the NID for the digest algorithm and pkey_id is the NID for the underlying signature algorithm. As there are signature algorithms that do not require a digest, NID_undef is a valid dig_id.
\fBOBJ_cleanup() releases any resources allocated by creating new objects.
For example the OID for commonName has the following definitions:
.Vb 3 #define SN_commonName "CN" #define LN_commonName "commonName" #define NID_commonName 13 .Ve
New objects can be added by calling OBJ_create().
Table objects have certain advantages over other objects: for example their NIDs can be used in a C language switch statement. They are also static constant structures which are shared: that is there is only a single constant structure for each table object.
Objects which are not in the table have the NID value 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.
Some objects are used to represent algorithms which do not have a corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently exists for a particular algorithm). As a result they cannot be encoded or decoded as part of ASN.1 structures. Applications can determine if there is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
These functions cannot return const because an ASN1_OBJECT can represent both an internal, constant, OID and a dynamically-created one. The latter cannot be constant because it needs to be freed after use.
\fBOBJ_nid2ln() and OBJ_nid2sn() returns a valid string or NULL on error.
\fBOBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or NID_undef on error.
\fBOBJ_add_sigid() returns 1 on success or 0 on error.
\fBi2t_ASN1_OBJECT() an OBJ_obj2txt() return -1 on error. On success, they return the length of the string written to buf if buf is not NULL and buf_len is big enough, otherwise the total string length. Note that this does not count the trailing NUL character.
.Vb 1 ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName); .Ve
Check if an object is commonName
.Vb 2 if (OBJ_obj2nid(obj) == NID_commonName) /* Do something */ .Ve
Create a new NID and initialize an object from it:
.Vb 2 int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); ASN1_OBJECT *obj = OBJ_nid2obj(new_nid); .Ve
Create a new object directly:
.Vb 1 obj = OBJ_txt2obj("1.2.3.4", 1); .Ve
Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.