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_OBJECTS_H
58#define OPENSSL_HEADER_OBJECTS_H
59
60#include <openssl/base.h>
61
62#include <openssl/bytestring.h>
63#include <openssl/obj_mac.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
95/* Looking up nids. */
96
97/* OBJ_obj2nid returns the nid corresponding to |obj|, or |NID_undef| if no
98 * such object is known. */
99OPENSSL_EXPORT int OBJ_obj2nid(const ASN1_OBJECT *obj);
100
101/* OBJ_cbs2nid returns the nid corresponding to the DER data in |cbs|, or
102 * |NID_undef| if no such object is known. */
103OPENSSL_EXPORT int OBJ_cbs2nid(const CBS *cbs);
104
105/* OBJ_sn2nid returns the nid corresponding to |short_name|, or |NID_undef| if
106 * no such short name is known. */
107OPENSSL_EXPORT int OBJ_sn2nid(const char *short_name);
108
109/* OBJ_ln2nid returns the nid corresponding to |long_name|, or |NID_undef| if
110 * no such long name is known. */
111OPENSSL_EXPORT int OBJ_ln2nid(const char *long_name);
112
113/* OBJ_txt2nid returns the nid corresponding to |s|, which may be a short name,
114 * long name, or an ASCII string containing a dotted sequence of numbers. It
115 * returns the nid or NID_undef if unknown. */
116OPENSSL_EXPORT int OBJ_txt2nid(const char *s);
117
118
119/* Getting information about nids. */
120
121/* OBJ_nid2obj returns the ASN1_OBJECT corresponding to |nid|, or NULL if |nid|
122 * is unknown. */
123OPENSSL_EXPORT const ASN1_OBJECT *OBJ_nid2obj(int nid);
124
125/* OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. */
126OPENSSL_EXPORT const char *OBJ_nid2sn(int nid);
127
128/* OBJ_nid2sn returns the long name for |nid|, or NULL if |nid| is unknown. */
129OPENSSL_EXPORT const char *OBJ_nid2ln(int nid);
130
131/* OBJ_nid2cbs writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns
132 * one on success or zero otherwise. */
133OPENSSL_EXPORT int OBJ_nid2cbb(CBB *out, int nid);
134
135
136/* Dealing with textual representations of object identifiers. */
137
138/* OBJ_txt2obj returns an ASN1_OBJECT for the textual respresentation in |s|.
139 * If |dont_search_names| is zero, then |s| will be matched against the long
140 * and short names of a known objects to find a match. Otherwise |s| must
141 * contain an ASCII string with a dotted sequence of numbers. The resulting
142 * object need not be previously known. It returns a freshly allocated
143 * |ASN1_OBJECT| or NULL on error. */
144OPENSSL_EXPORT ASN1_OBJECT *OBJ_txt2obj(const char *s, int dont_search_names);
145
146/* OBJ_obj2txt converts |obj| to a textual representation. If
147 * |dont_return_name| is zero then |obj| will be matched against known objects
148 * and the long (preferably) or short name will be used if found. Otherwise
149 * |obj| will be converted into a dotted sequence of integers. If |out| is not
150 * NULL, then at most |out_len| bytes of the textual form will be written
151 * there. If |out_len| is at least one, then string written to |out| will
152 * always be NUL terminated. It returns the number of characters that could
153 * have been written, not including the final NUL, or -1 on error. */
154OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj,
155                               int dont_return_name);
156
157
158/* Adding objects at runtime. */
159
160/* OBJ_create adds a known object and returns the nid of the new object, or
161 * NID_undef on error. */
162OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name,
163                              const char *long_name);
164
165
166/* Handling signature algorithm identifiers.
167 *
168 * Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and
169 * a public key algorithm. The following functions map between pairs of digest
170 * and public-key algorithms and the NIDs that specify their combination.
171 *
172 * Sometimes the combination NID leaves the digest unspecified (e.g.
173 * rsassaPss). In these cases, the digest NID is |NID_undef|. */
174
175/* OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to
176 * the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid|
177 * and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of
178 * |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need
179 * that output value. */
180OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid,
181                                       int *out_pkey_nid);
182
183/* OBJ_find_sigid_by_algs finds the signature NID that corresponds to the
184 * combination of |digest_nid| and |pkey_nid|. If success, it sets
185 * |*out_sign_nid| and returns one. Otherwise it returns zero. The
186 * |out_sign_nid| argument can be NULL if the caller only wishes to learn
187 * whether the combination is valid. */
188OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid,
189                                          int pkey_nid);
190
191
192#if defined(__cplusplus)
193}  /* extern C */
194#endif
195
196#define OBJ_F_OBJ_txt2obj 100
197#define OBJ_F_OBJ_create 101
198#define OBJ_F_OBJ_dup 102
199#define OBJ_F_OBJ_nid2obj 103
200#define OBJ_R_UNKNOWN_NID 100
201
202#endif  /* OPENSSL_HEADER_OBJECTS_H */
203