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 192