Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OBJ_NID2OBJ 3ossl"
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 \s-1OPENSSL_API_COMPAT\s0 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 \s-1NID\s0 n to an \s-1ASN1_OBJECT\s0 structure, its long name and its short name respectively, or \s-1NULL\s0 if an error occurred.
\fBOBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding \s-1NID\s0 for the object o, the long name ln or the short name sn respectively or NID_undef if an error occurred.
\fBOBJ_txt2nid() returns \s-1NID\s0 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 \s-1ASN1_OBJECT\s0 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 \s-1ASN1_OBJECT\s0 a into a textual representation. Unless buf is \s-1NULL,\s0 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 \s-1NUL\s0 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 \s-1NID\s0 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 \*(L"Signature Algorithm\*(R" that associates a given \s-1NID\s0 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 \s-1NID\s0 for the composite \*(L"Signature Algorithm\*(R", dig_id is the \s-1NID\s0 for the digest algorithm and pkey_id is the \s-1NID\s0 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 \s-1OID\s0 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 \s-1NID\s0 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 \s-1OID.\s0
Some objects are used to represent algorithms which do not have a corresponding \s-1ASN.1 OBJECT IDENTIFIER\s0 encoding (for example no \s-1OID\s0 currently exists for a particular algorithm). As a result they cannot be encoded or decoded as part of \s-1ASN.1\s0 structures. Applications can determine if there is a corresponding \s-1OBJECT IDENTIFIER\s0 by checking OBJ_length() is not zero.
These functions cannot return const because an \s-1ASN1_OBJECT\s0 can represent both an internal, constant, \s-1OID\s0 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 \s-1NULL\s0 on error.
\fBOBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a \s-1NID\s0 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 \s-1NULL\s0 and buf_len is big enough, otherwise the total string length. Note that this does not count the trailing \s-1NUL\s0 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 \s-1NID\s0 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 \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.