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