1/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
2 * All rights reserved.
3 *
4 * This package is an SSL implementation written
5 * by Eric Young (eay@cryptsoft.com).
6 * The implementation was written so as to conform with Netscapes SSL.
7 *
8 * This library is free for commercial and non-commercial use as long as
9 * the following conditions are aheared to. The following conditions
10 * apply to all code found in this distribution, be it the RC4, RSA,
11 * lhash, DES, etc., code; not just the SSL code. The SSL documentation
12 * included with this distribution is covered by the same copyright terms
13 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
14 *
15 * Copyright remains Eric Young's, and as such any Copyright notices in
16 * the code are not to be removed.
17 * If this package is used in a product, Eric Young should be given attribution
18 * as the author of the parts of the library used.
19 * This can be in the form of a textual message at program startup or
20 * in documentation (online or textual) provided with the package.
21 *
22 * Redistribution and use in source and binary forms, with or without
23 * modification, are permitted provided that the following conditions
24 * are met:
25 * 1. Redistributions of source code must retain the copyright
26 * notice, this list of conditions and the following disclaimer.
27 * 2. Redistributions in binary form must reproduce the above copyright
28 * notice, this list of conditions and the following disclaimer in the
29 * documentation and/or other materials provided with the distribution.
30 * 3. All advertising materials mentioning features or use of this software
31 * must display the following acknowledgement:
32 * "This product includes cryptographic software written by
33 * Eric Young (eay@cryptsoft.com)"
34 * The word 'cryptographic' can be left out if the rouines from the library
35 * being used are not cryptographic related :-).
36 * 4. If you include any Windows specific code (or a derivative thereof) from
37 * the apps directory (application code) you must include an acknowledgement:
38 * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
39 *
40 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
41 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
43 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
44 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
45 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
46 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
48 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
49 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
50 * SUCH DAMAGE.
51 *
52 * The licence and distribution terms for any publically available version or
53 * derivative of this code cannot be changed. i.e. this code cannot simply be
54 * copied and put under another distribution licence
55 * [including the GNU Public Licence.] */
56
57#ifndef OPENSSL_HEADER_OBJ_H
58#define OPENSSL_HEADER_OBJ_H
59
60#include <openssl/base.h>
61
62#include <openssl/bytestring.h>
63#include <openssl/nid.h>
64
65#if defined(__cplusplus)
66extern "C" {
67#endif
68
69
70// The objects library deals with the registration and indexing of ASN.1 object
71// identifiers. These values are often written as a dotted sequence of numbers,
72// e.g. 1.2.840.113549.1.9.16.3.9.
73//
74// Internally, OpenSSL likes to deal with these values by numbering them with
75// numbers called "nids". OpenSSL has a large, built-in database of common
76// object identifiers and also has both short and long names for them.
77//
78// This library provides functions for translating between object identifiers,
79// nids, short names and long names.
80//
81// The nid values should not be used outside of a single process: they are not
82// stable identifiers.
83
84
85// Basic operations.
86
87// OBJ_dup returns a duplicate copy of |obj| or NULL on allocation failure.
88OPENSSL_EXPORT ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *obj);
89
90// OBJ_cmp returns a value less than, equal to or greater than zero if |a| is
91// less than, equal to or greater than |b|, respectively.
92OPENSSL_EXPORT int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
93
94// OBJ_get0_data returns a pointer to the DER representation of |obj|.
95OPENSSL_EXPORT const uint8_t *OBJ_get0_data(const ASN1_OBJECT *obj);
96
97// OBJ_length returns the length of the DER representation of |obj|.
98OPENSSL_EXPORT size_t OBJ_length(const ASN1_OBJECT *obj);
99
100
101// Looking up nids.
102
103// OBJ_obj2nid returns the nid corresponding to |obj|, or |NID_undef| if no
104// such object is known.
105OPENSSL_EXPORT int OBJ_obj2nid(const ASN1_OBJECT *obj);
106
107// OBJ_cbs2nid returns the nid corresponding to the DER data in |cbs|, or
108// |NID_undef| if no such object is known.
109OPENSSL_EXPORT int OBJ_cbs2nid(const CBS *cbs);
110
111// OBJ_sn2nid returns the nid corresponding to |short_name|, or |NID_undef| if
112// no such short name is known.
113OPENSSL_EXPORT int OBJ_sn2nid(const char *short_name);
114
115// OBJ_ln2nid returns the nid corresponding to |long_name|, or |NID_undef| if
116// no such long name is known.
117OPENSSL_EXPORT int OBJ_ln2nid(const char *long_name);
118
119// OBJ_txt2nid returns the nid corresponding to |s|, which may be a short name,
120// long name, or an ASCII string containing a dotted sequence of numbers. It
121// returns the nid or NID_undef if unknown.
122OPENSSL_EXPORT int OBJ_txt2nid(const char *s);
123
124
125// Getting information about nids.
126
127// OBJ_nid2obj returns the ASN1_OBJECT corresponding to |nid|, or NULL if |nid|
128// is unknown.
129OPENSSL_EXPORT const ASN1_OBJECT *OBJ_nid2obj(int nid);
130
131// OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown.
132OPENSSL_EXPORT const char *OBJ_nid2sn(int nid);
133
134// OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown.
135OPENSSL_EXPORT const char *OBJ_nid2ln(int nid);
136
137// OBJ_nid2cbb writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns
138// one on success or zero otherwise.
139OPENSSL_EXPORT int OBJ_nid2cbb(CBB *out, int nid);
140
141
142// Dealing with textual representations of object identifiers.
143
144// OBJ_txt2obj returns an ASN1_OBJECT for the textual representation in |s|.
145// If |dont_search_names| is zero, then |s| will be matched against the long
146// and short names of a known objects to find a match. Otherwise |s| must
147// contain an ASCII string with a dotted sequence of numbers. The resulting
148// object need not be previously known. It returns a freshly allocated
149// |ASN1_OBJECT| or NULL on error.
150OPENSSL_EXPORT ASN1_OBJECT *OBJ_txt2obj(const char *s, int dont_search_names);
151
152// OBJ_obj2txt converts |obj| to a textual representation. If
153// |always_return_oid| is zero then |obj| will be matched against known objects
154// and the long (preferably) or short name will be used if found. Otherwise
155// |obj| will be converted into a dotted sequence of integers. If |out| is not
156// NULL, then at most |out_len| bytes of the textual form will be written
157// there. If |out_len| is at least one, then string written to |out| will
158// always be NUL terminated. It returns the number of characters that could
159// have been written, not including the final NUL, or -1 on error.
160OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj,
161 int always_return_oid);
162
163
164// Adding objects at runtime.
165
166// OBJ_create adds a known object and returns the nid of the new object, or
167// NID_undef on error.
168OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name,
169 const char *long_name);
170
171
172// Handling signature algorithm identifiers.
173//
174// Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and
175// a public key algorithm. The following functions map between pairs of digest
176// and public-key algorithms and the NIDs that specify their combination.
177//
178// Sometimes the combination NID leaves the digest unspecified (e.g.
179// rsassaPss). In these cases, the digest NID is |NID_undef|.
180
181// OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to
182// the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid|
183// and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of
184// |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need
185// that output value.
186OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid,
187 int *out_pkey_nid);
188
189// OBJ_find_sigid_by_algs finds the signature NID that corresponds to the
190// combination of |digest_nid| and |pkey_nid|. If success, it sets
191// |*out_sign_nid| and returns one. Otherwise it returns zero. The
192// |out_sign_nid| argument can be NULL if the caller only wishes to learn
193// whether the combination is valid.
194OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid,
195 int pkey_nid);
196
197
198// Deprecated functions.
199
200typedef struct obj_name_st {
201 int type;
202 int alias;
203 const char *name;
204 const char *data;
205} OBJ_NAME;
206
207#define OBJ_NAME_TYPE_MD_METH 1
208#define OBJ_NAME_TYPE_CIPHER_METH 2
209
210// OBJ_NAME_do_all_sorted calls |callback| zero or more times, each time with
211// the name of a different primitive. If |type| is |OBJ_NAME_TYPE_MD_METH| then
212// the primitives will be hash functions, alternatively if |type| is
213// |OBJ_NAME_TYPE_CIPHER_METH| then the primitives will be ciphers or cipher
214// modes.
215//
216// This function is ill-specified and should never be used.
217OPENSSL_EXPORT void OBJ_NAME_do_all_sorted(
218 int type, void (*callback)(const OBJ_NAME *, void *arg), void *arg);
219
220// OBJ_NAME_do_all calls |OBJ_NAME_do_all_sorted|.
221OPENSSL_EXPORT void OBJ_NAME_do_all(int type, void (*callback)(const OBJ_NAME *,
222 void *arg),
223 void *arg);
224
225// OBJ_cleanup does nothing.
226OPENSSL_EXPORT void OBJ_cleanup(void);
227
228
229#if defined(__cplusplus)
230} // extern C
231#endif
232
233#define OBJ_R_UNKNOWN_NID 100
234#define OBJ_R_INVALID_OID_STRING 101
235
236#endif // OPENSSL_HEADER_OBJ_H
237