Import of old SSLeay release: SSLeay 0.8.1b
[openssl.git] / doc / obj.doc
1 The Object library.
2
3 As part of my Crypto library, I found I required a method of identifying various
4 objects.  These objects normally had 3 different values associated with
5 them, a short text name, a long (or lower case) text name, and an
6 ASN.1 Object Identifier (which is a sequence of numbers).
7 This library contains a static list of objects and functions to lookup
8 according to one type and to return the other types.
9
10 To use these routines, 'Object.h' needs to be included.
11
12 For each supported object, #define entries are defined as follows
13 #define SN_Algorithm                    "Algorithm"
14 #define LN_algorithm                    "algorithm"
15 #define NID_algorithm                   38
16 #define OBJ_algorithm                   1L,3L,14L,3L,2L
17
18 SN_  stands for short name.
19 LN_  stands for either long name or lowercase name.
20 NID_ stands for Numeric ID.  I each object has a unique NID and this
21      should be used internally to identify objects.
22 OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the
23      ASN1 routines.  These values are used in ASN1 encoding.
24
25 The following functions are to be used to return pointers into a static
26 definition of these types.  What this means is "don't try to free() any
27 pointers returned from these functions.
28
29 ASN1_OBJECT *OBJ_nid2obj(
30 int n);
31         Return the ASN1_OBJECT that corresponds to a NID of n.
32         
33 char *OBJ_nid2ln(
34 int n);
35         Return the long/lower case name of the object represented by the
36         NID of n.
37         
38 char *OBJ_nid2sn(
39 int n);
40         Return the short name for the object represented by the NID of n.
41
42 ASN1_OBJECT *OBJ_dup(
43 ASN1_OBJECT *o);
44         Duplicate and return a new ASN1_OBJECT that is the same as the
45         passed parameter.
46         
47 int OBJ_obj2nid(
48 ASN1_OBJECT *o);
49         Given ASN1_OBJECT o, return the NID that corresponds.
50         
51 int OBJ_ln2nid(
52 char *s);
53         Given the long/lower case name 's', return the NID of the object.
54         
55 int OBJ_sn2nid(
56 char *s);
57         Given the short name 's', return the NID of the object.
58         
59 char *OBJ_bsearch(
60 char *key,
61 char *base,
62 int num,
63 int size,
64 int (*cmp)());
65         Since I have come across a few platforms that do not have the
66         bsearch() function, OBJ_bsearch is my version of that function.
67         Feel free to use this function, but you may as well just use the
68         normal system bsearch(3) if it is present.  This version also
69         has tolerance of being passed NULL pointers.