]>
Commit | Line | Data |
---|---|---|
4e1b50e2 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | i2t_ASN1_OBJECT, |
6 | OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, | |
7 | OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, | |
8 | OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup | |
9 | - ASN1 object utility functions | |
4e1b50e2 DSH |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
c264592d UM |
13 | #include <openssl/objects.h> |
14 | ||
c952780c RS |
15 | ASN1_OBJECT *OBJ_nid2obj(int n); |
16 | const char *OBJ_nid2ln(int n); | |
17 | const char *OBJ_nid2sn(int n); | |
4e1b50e2 DSH |
18 | |
19 | int OBJ_obj2nid(const ASN1_OBJECT *o); | |
20 | int OBJ_ln2nid(const char *ln); | |
21 | int OBJ_sn2nid(const char *sn); | |
22 | ||
23 | int OBJ_txt2nid(const char *s); | |
24 | ||
c952780c | 25 | ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name); |
4e1b50e2 DSH |
26 | int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); |
27 | ||
e83f154f | 28 | int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); |
4e1b50e2 | 29 | |
c952780c RS |
30 | int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); |
31 | ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o); | |
32 | ||
33 | int OBJ_create(const char *oid, const char *sn, const char *ln); | |
4e1b50e2 | 34 | |
2e430277 DSH |
35 | size_t OBJ_length(const ASN1_OBJECT *obj); |
36 | const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); | |
37 | ||
be80b21d RL |
38 | Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining |
39 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
40 | L<openssl_user_macros(7)>: | |
7b8cc9b3 | 41 | |
f64f17c3 | 42 | void OBJ_cleanup(void); |
7b8cc9b3 | 43 | |
4e1b50e2 DSH |
44 | =head1 DESCRIPTION |
45 | ||
46 | The ASN1 object utility functions process ASN1_OBJECT structures which are | |
47 | a representation of the ASN1 OBJECT IDENTIFIER (OID) type. | |
5d28ff38 RS |
48 | For convenience, OIDs are usually represented in source code as numeric |
49 | identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that | |
50 | are generated when the library is built, and their corresponding NIDs | |
51 | are available as defined constants. For the functions below, application | |
52 | code should treat all returned values -- OIDs, NIDs, or names -- as | |
53 | constants. | |
4e1b50e2 | 54 | |
1bc74519 | 55 | OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to |
4e1b50e2 | 56 | an ASN1_OBJECT structure, its long name and its short name respectively, |
34e4a964 | 57 | or B<NULL> if an error occurred. |
4e1b50e2 DSH |
58 | |
59 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID | |
60 | for the object B<o>, the long name <ln> or the short name <sn> respectively | |
61 | or NID_undef if an error occurred. | |
62 | ||
63 | OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be | |
186bb907 | 64 | a long name, a short name or the numerical representation of an object. |
4e1b50e2 DSH |
65 | |
66 | OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. | |
67 | If B<no_name> is 0 then long names and short names will be interpreted | |
68 | as well as numerical forms. If B<no_name> is 1 only the numerical form | |
69 | is acceptable. | |
70 | ||
71 | OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. | |
72 | The representation is written as a null terminated string to B<buf> | |
73 | at most B<buf_len> bytes are written, truncating the result if necessary. | |
74 | The total amount of space required is returned. If B<no_name> is 0 then | |
75 | if the object has a long or short name then that will be used, otherwise | |
76 | the numerical form will be used. If B<no_name> is 1 then the numerical | |
77 | form will always be used. | |
78 | ||
c952780c RS |
79 | i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero. |
80 | ||
4e1b50e2 DSH |
81 | OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. |
82 | ||
83 | OBJ_dup() returns a copy of B<o>. | |
84 | ||
1bc74519 | 85 | OBJ_create() adds a new object to the internal table. B<oid> is the |
4e1b50e2 | 86 | numerical form of the object, B<sn> the short name and B<ln> the |
2d162ea9 AP |
87 | long name. A new NID is returned for the created object in case of |
88 | success and NID_undef in case of failure. | |
4e1b50e2 | 89 | |
2e430277 DSH |
90 | OBJ_length() returns the size of the content octets of B<obj>. |
91 | ||
92 | OBJ_get0_data() returns a pointer to the content octets of B<obj>. | |
93 | The returned pointer is an internal pointer which B<must not> be freed. | |
94 | ||
b3696a55 | 95 | OBJ_cleanup() releases any resources allocated by creating new objects. |
7b8cc9b3 | 96 | |
4e1b50e2 DSH |
97 | =head1 NOTES |
98 | ||
99 | Objects in OpenSSL can have a short name, a long name and a numerical | |
100 | identifier (NID) associated with them. A standard set of objects is | |
101 | represented in an internal table. The appropriate values are defined | |
102 | in the header file B<objects.h>. | |
103 | ||
104 | For example the OID for commonName has the following definitions: | |
105 | ||
106 | #define SN_commonName "CN" | |
107 | #define LN_commonName "commonName" | |
108 | #define NID_commonName 13 | |
109 | ||
110 | New objects can be added by calling OBJ_create(). | |
111 | ||
112 | Table objects have certain advantages over other objects: for example | |
113 | their NIDs can be used in a C language switch statement. They are | |
114 | also static constant structures which are shared: that is there | |
115 | is only a single constant structure for each table object. | |
116 | ||
117 | Objects which are not in the table have the NID value NID_undef. | |
118 | ||
119 | Objects do not need to be in the internal tables to be processed, | |
120 | the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical | |
121 | form of an OID. | |
122 | ||
186bb907 | 123 | Some objects are used to represent algorithms which do not have a |
2e430277 DSH |
124 | corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently |
125 | exists for a particular algorithm). As a result they B<cannot> be encoded or | |
126 | decoded as part of ASN.1 structures. Applications can determine if there | |
127 | is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. | |
128 | ||
5d28ff38 RS |
129 | These functions cannot return B<const> because an B<ASN1_OBJECT> can |
130 | represent both an internal, constant, OID and a dynamically-created one. | |
131 | The latter cannot be constant because it needs to be freed after use. | |
132 | ||
4564e77a PY |
133 | =head1 RETURN VALUES |
134 | ||
135 | OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an | |
136 | error occurred. | |
137 | ||
138 | OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> | |
139 | on error. | |
140 | ||
141 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return | |
142 | a NID or B<NID_undef> on error. | |
143 | ||
4e1b50e2 DSH |
144 | =head1 EXAMPLES |
145 | ||
146 | Create an object for B<commonName>: | |
147 | ||
e9b77246 | 148 | ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName); |
4e1b50e2 | 149 | |
0711be16 | 150 | Check if an object is B<commonName> |
4e1b50e2 DSH |
151 | |
152 | if (OBJ_obj2nid(obj) == NID_commonName) | |
2947af32 | 153 | /* Do something */ |
4e1b50e2 DSH |
154 | |
155 | Create a new NID and initialize an object from it: | |
156 | ||
e9b77246 BB |
157 | int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); |
158 | ASN1_OBJECT *obj = OBJ_nid2obj(new_nid); | |
1bc74519 | 159 | |
4e1b50e2 DSH |
160 | Create a new object directly: |
161 | ||
162 | obj = OBJ_txt2obj("1.2.3.4", 1); | |
163 | ||
164 | =head1 BUGS | |
165 | ||
1bc74519 | 166 | OBJ_obj2txt() is awkward and messy to use: it doesn't follow the |
4e1b50e2 DSH |
167 | convention of other OpenSSL functions where the buffer can be set |
168 | to B<NULL> to determine the amount of data that should be written. | |
169 | Instead B<buf> must point to a valid buffer and B<buf_len> should | |
170 | be set to a positive value. A buffer length of 80 should be more | |
171 | than enough to handle any OID encountered in practice. | |
172 | ||
4e1b50e2 DSH |
173 | =head1 SEE ALSO |
174 | ||
9b86974e | 175 | L<ERR_get_error(3)> |
4e1b50e2 DSH |
176 | |
177 | =head1 HISTORY | |
178 | ||
b3696a55 RS |
179 | OBJ_cleanup() was deprecated in OpenSSL 1.1.0 by L<OPENSSL_init_crypto(3)> |
180 | and should not be used. | |
4e1b50e2 | 181 | |
e2f92610 RS |
182 | =head1 COPYRIGHT |
183 | ||
0f84cbc3 | 184 | Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 185 | |
4746f25a | 186 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
187 | this file except in compliance with the License. You can obtain a copy |
188 | in the file LICENSE in the source distribution or at | |
189 | L<https://www.openssl.org/source/license.html>. | |
190 | ||
191 | =cut |