| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | i2t_ASN1_OBJECT,
|
|---|
| 6 | OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln,
|
|---|
| 7 | OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp,
|
|---|
| 8 | OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
|
|---|
| 9 | - ASN1 object utility functions
|
|---|
| 10 |
|
|---|
| 11 | =head1 SYNOPSIS
|
|---|
| 12 |
|
|---|
| 13 | #include <openssl/objects.h>
|
|---|
| 14 |
|
|---|
| 15 | ASN1_OBJECT *OBJ_nid2obj(int n);
|
|---|
| 16 | const char *OBJ_nid2ln(int n);
|
|---|
| 17 | const char *OBJ_nid2sn(int n);
|
|---|
| 18 |
|
|---|
| 19 | int OBJ_obj2nid(const ASN1_OBJECT *o);
|
|---|
| 20 | int OBJ_ln2nid(const char *ln);
|
|---|
| 21 | int OBJ_sn2nid(const char *sn);
|
|---|
| 22 |
|
|---|
| 23 | int OBJ_txt2nid(const char *s);
|
|---|
| 24 |
|
|---|
| 25 | ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name);
|
|---|
| 26 | int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
|
|---|
| 27 |
|
|---|
| 28 | int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);
|
|---|
| 29 |
|
|---|
| 30 | int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
|
|---|
| 31 | ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);
|
|---|
| 32 |
|
|---|
| 33 | int OBJ_create(const char *oid, const char *sn, const char *ln);
|
|---|
| 34 |
|
|---|
| 35 | size_t OBJ_length(const ASN1_OBJECT *obj);
|
|---|
| 36 | const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);
|
|---|
| 37 |
|
|---|
| 38 | Deprecated:
|
|---|
| 39 |
|
|---|
| 40 | #if OPENSSL_API_COMPAT < 0x10100000L
|
|---|
| 41 | void OBJ_cleanup(void)
|
|---|
| 42 | #endif
|
|---|
| 43 |
|
|---|
| 44 | =head1 DESCRIPTION
|
|---|
| 45 |
|
|---|
| 46 | The ASN1 object utility functions process ASN1_OBJECT structures which are
|
|---|
| 47 | a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
|
|---|
| 48 | For convenience, OIDs are usually represented in source code as numeric
|
|---|
| 49 | identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that
|
|---|
| 50 | are generated when the library is built, and their corresponding NIDs
|
|---|
| 51 | are available as defined constants. For the functions below, application
|
|---|
| 52 | code should treat all returned values -- OIDs, NIDs, or names -- as
|
|---|
| 53 | constants.
|
|---|
| 54 |
|
|---|
| 55 | OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
|
|---|
| 56 | an ASN1_OBJECT structure, its long name and its short name respectively,
|
|---|
| 57 | or B<NULL> if an error occurred.
|
|---|
| 58 |
|
|---|
| 59 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
|
|---|
| 60 | for the object B<o>, the long name <ln> or the short name <sn> respectively
|
|---|
| 61 | or NID_undef if an error occurred.
|
|---|
| 62 |
|
|---|
| 63 | OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
|
|---|
| 64 | a long name, a short name or the numerical representation of an object.
|
|---|
| 65 |
|
|---|
| 66 | OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
|
|---|
| 67 | If B<no_name> is 0 then long names and short names will be interpreted
|
|---|
| 68 | as well as numerical forms. If B<no_name> is 1 only the numerical form
|
|---|
| 69 | is acceptable.
|
|---|
| 70 |
|
|---|
| 71 | OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
|
|---|
| 72 | The representation is written as a null terminated string to B<buf>
|
|---|
| 73 | at most B<buf_len> bytes are written, truncating the result if necessary.
|
|---|
| 74 | The total amount of space required is returned. If B<no_name> is 0 then
|
|---|
| 75 | if the object has a long or short name then that will be used, otherwise
|
|---|
| 76 | the numerical form will be used. If B<no_name> is 1 then the numerical
|
|---|
| 77 | form will always be used.
|
|---|
| 78 |
|
|---|
| 79 | i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero.
|
|---|
| 80 |
|
|---|
| 81 | OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
|
|---|
| 82 |
|
|---|
| 83 | OBJ_dup() returns a copy of B<o>.
|
|---|
| 84 |
|
|---|
| 85 | OBJ_create() adds a new object to the internal table. B<oid> is the
|
|---|
| 86 | numerical form of the object, B<sn> the short name and B<ln> the
|
|---|
| 87 | long name. A new NID is returned for the created object in case of
|
|---|
| 88 | success and NID_undef in case of failure.
|
|---|
| 89 |
|
|---|
| 90 | OBJ_length() returns the size of the content octets of B<obj>.
|
|---|
| 91 |
|
|---|
| 92 | OBJ_get0_data() returns a pointer to the content octets of B<obj>.
|
|---|
| 93 | The returned pointer is an internal pointer which B<must not> be freed.
|
|---|
| 94 |
|
|---|
| 95 | OBJ_cleanup() releases any resources allocated by creating new objects.
|
|---|
| 96 |
|
|---|
| 97 | =head1 NOTES
|
|---|
| 98 |
|
|---|
| 99 | Objects in OpenSSL can have a short name, a long name and a numerical
|
|---|
| 100 | identifier (NID) associated with them. A standard set of objects is
|
|---|
| 101 | represented in an internal table. The appropriate values are defined
|
|---|
| 102 | in the header file B<objects.h>.
|
|---|
| 103 |
|
|---|
| 104 | For example the OID for commonName has the following definitions:
|
|---|
| 105 |
|
|---|
| 106 | #define SN_commonName "CN"
|
|---|
| 107 | #define LN_commonName "commonName"
|
|---|
| 108 | #define NID_commonName 13
|
|---|
| 109 |
|
|---|
| 110 | New objects can be added by calling OBJ_create().
|
|---|
| 111 |
|
|---|
| 112 | Table objects have certain advantages over other objects: for example
|
|---|
| 113 | their NIDs can be used in a C language switch statement. They are
|
|---|
| 114 | also static constant structures which are shared: that is there
|
|---|
| 115 | is only a single constant structure for each table object.
|
|---|
| 116 |
|
|---|
| 117 | Objects which are not in the table have the NID value NID_undef.
|
|---|
| 118 |
|
|---|
| 119 | Objects do not need to be in the internal tables to be processed,
|
|---|
| 120 | the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
|
|---|
| 121 | form of an OID.
|
|---|
| 122 |
|
|---|
| 123 | Some objects are used to represent algorithms which do not have a
|
|---|
| 124 | corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently
|
|---|
| 125 | exists for a particular algorithm). As a result they B<cannot> be encoded or
|
|---|
| 126 | decoded as part of ASN.1 structures. Applications can determine if there
|
|---|
| 127 | is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
|
|---|
| 128 |
|
|---|
| 129 | These functions cannot return B<const> because an B<ASN1_OBJECT> can
|
|---|
| 130 | represent both an internal, constant, OID and a dynamically-created one.
|
|---|
| 131 | The latter cannot be constant because it needs to be freed after use.
|
|---|
| 132 |
|
|---|
| 133 | =head1 RETURN VALUES
|
|---|
| 134 |
|
|---|
| 135 | OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
|
|---|
| 136 | error occurred.
|
|---|
| 137 |
|
|---|
| 138 | OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
|
|---|
| 139 | on error.
|
|---|
| 140 |
|
|---|
| 141 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
|
|---|
| 142 | a NID or B<NID_undef> on error.
|
|---|
| 143 |
|
|---|
| 144 | =head1 EXAMPLES
|
|---|
| 145 |
|
|---|
| 146 | Create an object for B<commonName>:
|
|---|
| 147 |
|
|---|
| 148 | ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName);
|
|---|
| 149 |
|
|---|
| 150 | Check if an object is B<commonName>
|
|---|
| 151 |
|
|---|
| 152 | if (OBJ_obj2nid(obj) == NID_commonName)
|
|---|
| 153 | /* Do something */
|
|---|
| 154 |
|
|---|
| 155 | Create a new NID and initialize an object from it:
|
|---|
| 156 |
|
|---|
| 157 | int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
|
|---|
| 158 | ASN1_OBJECT *obj = OBJ_nid2obj(new_nid);
|
|---|
| 159 |
|
|---|
| 160 | Create a new object directly:
|
|---|
| 161 |
|
|---|
| 162 | obj = OBJ_txt2obj("1.2.3.4", 1);
|
|---|
| 163 |
|
|---|
| 164 | =head1 BUGS
|
|---|
| 165 |
|
|---|
| 166 | OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
|
|---|
| 167 | convention of other OpenSSL functions where the buffer can be set
|
|---|
| 168 | to B<NULL> to determine the amount of data that should be written.
|
|---|
| 169 | Instead B<buf> must point to a valid buffer and B<buf_len> should
|
|---|
| 170 | be set to a positive value. A buffer length of 80 should be more
|
|---|
| 171 | than enough to handle any OID encountered in practice.
|
|---|
| 172 |
|
|---|
| 173 | =head1 SEE ALSO
|
|---|
| 174 |
|
|---|
| 175 | L<ERR_get_error(3)>
|
|---|
| 176 |
|
|---|
| 177 | =head1 HISTORY
|
|---|
| 178 |
|
|---|
| 179 | OBJ_cleanup() was deprecated in OpenSSL 1.1.0 by L<OPENSSL_init_crypto(3)>
|
|---|
| 180 | and should not be used.
|
|---|
| 181 |
|
|---|
| 182 | =head1 COPYRIGHT
|
|---|
| 183 |
|
|---|
| 184 | Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 185 |
|
|---|
| 186 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 187 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 188 | in the file LICENSE in the source distribution or at
|
|---|
| 189 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 190 |
|
|---|
| 191 | =cut
|
|---|
