yuezonghe | 824eb0c | 2024-06-27 02:32:26 -0700 | [diff] [blame^] | 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 I<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 I<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 I<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 I<s>. I<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 I<s> into an ASN1_OBJECT structure. |
| 67 | If I<no_name> is 0 then long names and short names will be interpreted |
| 68 | as well as numerical forms. If I<no_name> is 1 only the numerical form |
| 69 | is acceptable. |
| 70 | |
| 71 | OBJ_obj2txt() converts the B<ASN1_OBJECT> I<a> into a textual representation. |
| 72 | Unless I<buf> is NULL, |
| 73 | the representation is written as a NUL-terminated string to I<buf>, where |
| 74 | at most I<buf_len> bytes are written, truncating the result if necessary. |
| 75 | In any case it returns the total string length, excluding the NUL character, |
| 76 | required for non-truncated representation, or -1 on error. |
| 77 | If I<no_name> is 0 then if the object has a long or short name |
| 78 | then that will be used, otherwise the numerical form will be used. |
| 79 | If I<no_name> is 1 then the numerical form will always be used. |
| 80 | |
| 81 | i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I<no_name> set to zero. |
| 82 | |
| 83 | OBJ_cmp() compares I<a> to I<b>. If the two are identical 0 is returned. |
| 84 | |
| 85 | OBJ_dup() returns a copy of I<o>. |
| 86 | |
| 87 | OBJ_create() adds a new object to the internal table. I<oid> is the |
| 88 | numerical form of the object, I<sn> the short name and I<ln> the |
| 89 | long name. A new NID is returned for the created object in case of |
| 90 | success and NID_undef in case of failure. |
| 91 | |
| 92 | OBJ_length() returns the size of the content octets of I<obj>. |
| 93 | |
| 94 | OBJ_get0_data() returns a pointer to the content octets of I<obj>. |
| 95 | The returned pointer is an internal pointer which B<must not> be freed. |
| 96 | |
| 97 | OBJ_cleanup() releases any resources allocated by creating new objects. |
| 98 | |
| 99 | =head1 NOTES |
| 100 | |
| 101 | Objects in OpenSSL can have a short name, a long name and a numerical |
| 102 | identifier (NID) associated with them. A standard set of objects is |
| 103 | represented in an internal table. The appropriate values are defined |
| 104 | in the header file B<objects.h>. |
| 105 | |
| 106 | For example the OID for commonName has the following definitions: |
| 107 | |
| 108 | #define SN_commonName "CN" |
| 109 | #define LN_commonName "commonName" |
| 110 | #define NID_commonName 13 |
| 111 | |
| 112 | New objects can be added by calling OBJ_create(). |
| 113 | |
| 114 | Table objects have certain advantages over other objects: for example |
| 115 | their NIDs can be used in a C language switch statement. They are |
| 116 | also static constant structures which are shared: that is there |
| 117 | is only a single constant structure for each table object. |
| 118 | |
| 119 | Objects which are not in the table have the NID value NID_undef. |
| 120 | |
| 121 | Objects do not need to be in the internal tables to be processed, |
| 122 | the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical |
| 123 | form of an OID. |
| 124 | |
| 125 | Some objects are used to represent algorithms which do not have a |
| 126 | corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently |
| 127 | exists for a particular algorithm). As a result they B<cannot> be encoded or |
| 128 | decoded as part of ASN.1 structures. Applications can determine if there |
| 129 | is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. |
| 130 | |
| 131 | These functions cannot return B<const> because an B<ASN1_OBJECT> can |
| 132 | represent both an internal, constant, OID and a dynamically-created one. |
| 133 | The latter cannot be constant because it needs to be freed after use. |
| 134 | |
| 135 | =head1 RETURN VALUES |
| 136 | |
| 137 | OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an |
| 138 | error occurred. |
| 139 | |
| 140 | OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> |
| 141 | on error. |
| 142 | |
| 143 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return |
| 144 | a NID or B<NID_undef> on error. |
| 145 | |
| 146 | OBJ_add_sigid() returns 1 on success or 0 on error. |
| 147 | |
| 148 | i2t_ASN1_OBJECT() an OBJ_obj2txt() return -1 on error. |
| 149 | On success, they return the length of the string written to I<buf> if I<buf> is |
| 150 | not NULL and I<buf_len> is big enough, otherwise the total string length. |
| 151 | Note that this does not count the trailing NUL character. |
| 152 | |
| 153 | =head1 EXAMPLES |
| 154 | |
| 155 | Create an object for B<commonName>: |
| 156 | |
| 157 | ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName); |
| 158 | |
| 159 | Check if an object is B<commonName> |
| 160 | |
| 161 | if (OBJ_obj2nid(obj) == NID_commonName) |
| 162 | /* Do something */ |
| 163 | |
| 164 | Create a new NID and initialize an object from it: |
| 165 | |
| 166 | int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); |
| 167 | ASN1_OBJECT *obj = OBJ_nid2obj(new_nid); |
| 168 | |
| 169 | Create a new object directly: |
| 170 | |
| 171 | obj = OBJ_txt2obj("1.2.3.4", 1); |
| 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-2022 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 |