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