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