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