212 lines
9.1 KiB
HTML
Executable File
212 lines
9.1 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>OBJ_nid2obj</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#bugs">BUGS</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>i2t_ASN1_OBJECT,
|
|
OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln,
|
|
OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp,
|
|
OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
|
|
- ASN1 object utility functions</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/objects.h></pre>
|
|
<pre>
|
|
ASN1_OBJECT *OBJ_nid2obj(int n);
|
|
const char *OBJ_nid2ln(int n);
|
|
const char *OBJ_nid2sn(int n);</pre>
|
|
<pre>
|
|
int OBJ_obj2nid(const ASN1_OBJECT *o);
|
|
int OBJ_ln2nid(const char *ln);
|
|
int OBJ_sn2nid(const char *sn);</pre>
|
|
<pre>
|
|
int OBJ_txt2nid(const char *s);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);</pre>
|
|
<pre>
|
|
int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
|
|
ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);</pre>
|
|
<pre>
|
|
int OBJ_create(const char *oid, const char *sn, const char *ln);</pre>
|
|
<pre>
|
|
size_t OBJ_length(const ASN1_OBJECT *obj);
|
|
const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);</pre>
|
|
<p>Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
|
|
<strong>OPENSSL_API_COMPAT</strong> with a suitable version value, see
|
|
<em>openssl_user_macros(7)</em>:</p>
|
|
<pre>
|
|
void OBJ_cleanup(void)</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The ASN1 object utility functions process ASN1_OBJECT structures which are
|
|
a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
|
|
For convenience, OIDs are usually represented in source code as numeric
|
|
identifiers, or <strong>NID</strong>s. 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.</p>
|
|
<p>OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID <strong>n</strong> to
|
|
an ASN1_OBJECT structure, its long name and its short name respectively,
|
|
or <strong>NULL</strong> if an error occurred.</p>
|
|
<p>OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
|
|
for the object <strong>o</strong>, the long name <ln> or the short name <sn> respectively
|
|
or NID_undef if an error occurred.</p>
|
|
<p>OBJ_txt2nid() returns NID corresponding to text string <s>. <strong>s</strong> can be
|
|
a long name, a short name or the numerical representation of an object.</p>
|
|
<p>OBJ_txt2obj() converts the text string <strong>s</strong> into an ASN1_OBJECT structure.
|
|
If <strong>no_name</strong> is 0 then long names and short names will be interpreted
|
|
as well as numerical forms. If <strong>no_name</strong> is 1 only the numerical form
|
|
is acceptable.</p>
|
|
<p>OBJ_obj2txt() converts the <strong>ASN1_OBJECT</strong> <strong>a</strong> into a textual representation.
|
|
The representation is written as a null terminated string to <strong>buf</strong>
|
|
at most <strong>buf_len</strong> bytes are written, truncating the result if necessary.
|
|
The total amount of space required is returned. If <strong>no_name</strong> 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 <strong>no_name</strong> is 1 then the numerical
|
|
form will always be used.</p>
|
|
<p>i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the <strong>no_name</strong> set to zero.</p>
|
|
<p><code>OBJ_cmp()</code> compares <strong>a</strong> to <strong>b</strong>. If the two are identical 0 is returned.</p>
|
|
<p><code>OBJ_dup()</code> returns a copy of <strong>o</strong>.</p>
|
|
<p><code>OBJ_create()</code> adds a new object to the internal table. <strong>oid</strong> is the
|
|
numerical form of the object, <strong>sn</strong> the short name and <strong>ln</strong> the
|
|
long name. A new NID is returned for the created object in case of
|
|
success and NID_undef in case of failure.</p>
|
|
<p><code>OBJ_length()</code> returns the size of the content octets of <strong>obj</strong>.</p>
|
|
<p>OBJ_get0_data() returns a pointer to the content octets of <strong>obj</strong>.
|
|
The returned pointer is an internal pointer which <strong>must not</strong> be freed.</p>
|
|
<p><code>OBJ_cleanup()</code> releases any resources allocated by creating new objects.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>Objects in OpenSSL 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 <strong>objects.h</strong>.</p>
|
|
<p>For example the OID for commonName has the following definitions:</p>
|
|
<pre>
|
|
#define SN_commonName "CN"
|
|
#define LN_commonName "commonName"
|
|
#define NID_commonName 13</pre>
|
|
<p>New objects can be added by calling <code>OBJ_create()</code>.</p>
|
|
<p>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.</p>
|
|
<p>Objects which are not in the table have the NID value NID_undef.</p>
|
|
<p>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.</p>
|
|
<p>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 <strong>cannot</strong> be encoded or
|
|
decoded as part of ASN.1 structures. Applications can determine if there
|
|
is a corresponding OBJECT IDENTIFIER by checking <code>OBJ_length()</code> is not zero.</p>
|
|
<p>These functions cannot return <strong>const</strong> because an <strong>ASN1_OBJECT</strong> 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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>OBJ_nid2obj() returns an <strong>ASN1_OBJECT</strong> structure or <strong>NULL</strong> is an
|
|
error occurred.</p>
|
|
<p>OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or <strong>NULL</strong>
|
|
on error.</p>
|
|
<p>OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
|
|
a NID or <strong>NID_undef</strong> on error.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Create an object for <strong>commonName</strong>:</p>
|
|
<pre>
|
|
ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName);</pre>
|
|
<p>Check if an object is <strong>commonName</strong></p>
|
|
<pre>
|
|
if (OBJ_obj2nid(obj) == NID_commonName)
|
|
/* Do something */</pre>
|
|
<p>Create a new NID and initialize an object from it:</p>
|
|
<pre>
|
|
int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
|
|
ASN1_OBJECT *obj = OBJ_nid2obj(new_nid);</pre>
|
|
<p>Create a new object directly:</p>
|
|
<pre>
|
|
obj = OBJ_txt2obj("1.2.3.4", 1);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="bugs">BUGS</a></h1>
|
|
<p>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 <strong>NULL</strong> to determine the amount of data that should be written.
|
|
Instead <strong>buf</strong> must point to a valid buffer and <strong>buf_len</strong> should
|
|
be set to a positive value. A buffer length of 80 should be more
|
|
than enough to handle any OID encountered in practice.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ERR_get_error(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p><code>OBJ_cleanup()</code> was deprecated in OpenSSL 1.1.0 by <em>OPENSSL_init_crypto(3)</em>
|
|
and should not be used.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>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
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|