OBJ_nid2obj.pod revision 337982
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. 36For convenience, OIDs are usually represented in source code as numeric 37identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that 38are generated when the library is built, and their corresponding NIDs 39are available as defined constants. For the functions below, application 40code should treat all returned values -- OIDs, NIDs, or names -- as 41constants. 42 43OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to 44an ASN1_OBJECT structure, its long name and its short name respectively, 45or B<NULL> if an error occurred. 46 47OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID 48for the object B<o>, the long name <ln> or the short name <sn> respectively 49or NID_undef if an error occurred. 50 51OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be 52a long name, a short name or the numerical respresentation of an object. 53 54OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. 55If B<no_name> is 0 then long names and short names will be interpreted 56as well as numerical forms. If B<no_name> is 1 only the numerical form 57is acceptable. 58 59OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. 60The representation is written as a null terminated string to B<buf> 61at most B<buf_len> bytes are written, truncating the result if necessary. 62The total amount of space required is returned. If B<no_name> is 0 then 63if the object has a long or short name then that will be used, otherwise 64the numerical form will be used. If B<no_name> is 1 then the numerical 65form will always be used. 66 67OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. 68 69OBJ_dup() returns a copy of B<o>. 70 71OBJ_create() adds a new object to the internal table. B<oid> is the 72numerical form of the object, B<sn> the short name and B<ln> the 73long name. A new NID is returned for the created object. 74 75OBJ_cleanup() cleans up OpenSSLs internal object table: this should 76be called before an application exits if any new objects were added 77using OBJ_create(). 78 79=head1 NOTES 80 81Objects in OpenSSL can have a short name, a long name and a numerical 82identifier (NID) associated with them. A standard set of objects is 83represented in an internal table. The appropriate values are defined 84in the header file B<objects.h>. 85 86For example the OID for commonName has the following definitions: 87 88 #define SN_commonName "CN" 89 #define LN_commonName "commonName" 90 #define NID_commonName 13 91 92New objects can be added by calling OBJ_create(). 93 94Table objects have certain advantages over other objects: for example 95their NIDs can be used in a C language switch statement. They are 96also static constant structures which are shared: that is there 97is only a single constant structure for each table object. 98 99Objects which are not in the table have the NID value NID_undef. 100 101Objects do not need to be in the internal tables to be processed, 102the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical 103form of an OID. 104 105Some objects are used to represent algorithms which do not have a 106corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently 107exists for a particular algorithm). As a result they B<cannot> be encoded or 108decoded as part of ASN.1 structures. Applications can determine if there 109is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. 110 111These functions cannot return B<const> because an B<ASN1_OBJECT> can 112represent both an internal, constant, OID and a dynamically-created one. 113The latter cannot be constant because it needs to be freed after use. 114 115=head1 EXAMPLES 116 117Create an object for B<commonName>: 118 119 ASN1_OBJECT *o; 120 o = OBJ_nid2obj(NID_commonName); 121 122Check if an object is B<commonName> 123 124 if (OBJ_obj2nid(obj) == NID_commonName) 125 /* Do something */ 126 127Create a new NID and initialize an object from it: 128 129 int new_nid; 130 ASN1_OBJECT *obj; 131 132 new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); 133 134 obj = OBJ_nid2obj(new_nid); 135 136Create a new object directly: 137 138 obj = OBJ_txt2obj("1.2.3.4", 1); 139 140=head1 BUGS 141 142OBJ_obj2txt() is awkward and messy to use: it doesn't follow the 143convention of other OpenSSL functions where the buffer can be set 144to B<NULL> to determine the amount of data that should be written. 145Instead B<buf> must point to a valid buffer and B<buf_len> should 146be set to a positive value. A buffer length of 80 should be more 147than enough to handle any OID encountered in practice. 148 149=head1 RETURN VALUES 150 151OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an 152error occurred. 153It returns a pointer to an internal table and does not 154allocate memory; ASN1_OBJECT_free() will have no effect. 155 156OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> 157on error. 158 159OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return 160a NID or B<NID_undef> on error. 161 162=head1 SEE ALSO 163 164L<ERR_get_error(3)|ERR_get_error(3)> 165 166=head1 HISTORY 167 168TBA 169 170=cut 171