1=pod 2 3=head1 NAME 4 5OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, 6OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility 7functions 8 9=head1 SYNOPSIS 10 11 ASN1_OBJECT * OBJ_nid2obj(int n); 12 const char * OBJ_nid2ln(int n); 13 const char * OBJ_nid2sn(int n); 14 15 int OBJ_obj2nid(const ASN1_OBJECT *o); 16 int OBJ_ln2nid(const char *ln); 17 int OBJ_sn2nid(const char *sn); 18 19 int OBJ_txt2nid(const char *s); 20 21 ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name); 22 int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); 23 24 int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b); 25 ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o); 26 27 int OBJ_create(const char *oid,const char *sn,const char *ln); 28 void OBJ_cleanup(void); 29 30=head1 DESCRIPTION 31 32The ASN1 object utility functions process ASN1_OBJECT structures which are 33a representation of the ASN1 OBJECT IDENTIFIER (OID) type. 34 35OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to 36an ASN1_OBJECT structure, its long name and its short name respectively, 37or B<NULL> is an error occurred. 38 39OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID 40for the object B<o>, the long name <ln> or the short name <sn> respectively 41or NID_undef if an error occurred. 42 43OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be 44a long name, a short name or the numerical respresentation of an object. 45 46OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. 47If B<no_name> is 0 then long names and short names will be interpreted 48as well as numerical forms. If B<no_name> is 1 only the numerical form 49is acceptable. 50 51OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. 52The representation is written as a null terminated string to B<buf> 53at most B<buf_len> bytes are written, truncating the result if necessary. 54The total amount of space required is returned. If B<no_name> is 0 then 55if the object has a long or short name then that will be used, otherwise 56the numerical form will be used. If B<no_name> is 1 then the numerical 57form will always be used. 58 59OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. 60 61OBJ_dup() returns a copy of B<o>. 62 63OBJ_create() adds a new object to the internal table. B<oid> is the 64numerical form of the object, B<sn> the short name and B<ln> the 65long name. A new NID is returned for the created object. 66 67OBJ_cleanup() cleans up OpenSSLs internal object table: this should 68be called before an application exits if any new objects were added 69using OBJ_create(). 70 71=head1 NOTES 72 73Objects in OpenSSL can have a short name, a long name and a numerical 74identifier (NID) associated with them. A standard set of objects is 75represented in an internal table. The appropriate values are defined 76in the header file B<objects.h>. 77 78For example the OID for commonName has the following definitions: 79 80 #define SN_commonName "CN" 81 #define LN_commonName "commonName" 82 #define NID_commonName 13 83 84New objects can be added by calling OBJ_create(). 85 86Table objects have certain advantages over other objects: for example 87their NIDs can be used in a C language switch statement. They are 88also static constant structures which are shared: that is there 89is only a single constant structure for each table object. 90 91Objects which are not in the table have the NID value NID_undef. 92 93Objects do not need to be in the internal tables to be processed, 94the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical 95form of an OID. 96 97=head1 EXAMPLES 98 99Create an object for B<commonName>: 100 101 ASN1_OBJECT *o; 102 o = OBJ_nid2obj(NID_commonName); 103 104Check if an object is B<commonName> 105 106 if (OBJ_obj2nid(obj) == NID_commonName) 107 /* Do something */ 108 109Create a new NID and initialize an object from it: 110 111 int new_nid; 112 ASN1_OBJECT *obj; 113 new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 114 115 obj = OBJ_nid2obj(new_nid); 116 117Create a new object directly: 118 119 obj = OBJ_txt2obj("1.2.3.4", 1); 120 121=head1 BUGS 122 123OBJ_obj2txt() is awkward and messy to use: it doesn't follow the 124convention of other OpenSSL functions where the buffer can be set 125to B<NULL> to determine the amount of data that should be written. 126Instead B<buf> must point to a valid buffer and B<buf_len> should 127be set to a positive value. A buffer length of 80 should be more 128than enough to handle any OID encountered in practice. 129 130=head1 RETURN VALUES 131 132OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an 133error occurred. 134 135OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> 136on error. 137 138OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return 139a NID or B<NID_undef> on error. 140 141=head1 SEE ALSO 142 143L<ERR_get_error(3)|ERR_get_error(3)> 144 145=head1 HISTORY 146 147TBA 148 149=cut 150