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) 66 extern "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. The 88 // caller must call |ASN1_OBJECT_free| on the result to release it. 89 OPENSSL_EXPORT ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *obj); 90 91 // OBJ_cmp returns a value less than, equal to or greater than zero if |a| is 92 // less than, equal to or greater than |b|, respectively. 93 OPENSSL_EXPORT int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); 94 95 // OBJ_get0_data returns a pointer to the DER representation of |obj|. This is 96 // the contents of the DER-encoded identifier, not including the tag and length. 97 // If |obj| does not have an associated object identifier (i.e. it is a nid-only 98 // value), this value is the empty string. 99 OPENSSL_EXPORT const uint8_t *OBJ_get0_data(const ASN1_OBJECT *obj); 100 101 // OBJ_length returns the length of the DER representation of |obj|. This is the 102 // contents of the DER-encoded identifier, not including the tag and length. If 103 // |obj| does not have an associated object identifier (i.e. it is a nid-only 104 // value), this value is the empty string. 105 OPENSSL_EXPORT size_t OBJ_length(const ASN1_OBJECT *obj); 106 107 108 // Looking up nids. 109 110 // OBJ_obj2nid returns the nid corresponding to |obj|, or |NID_undef| if no 111 // such object is known. 112 OPENSSL_EXPORT int OBJ_obj2nid(const ASN1_OBJECT *obj); 113 114 // OBJ_cbs2nid returns the nid corresponding to the DER data in |cbs|, or 115 // |NID_undef| if no such object is known. 116 OPENSSL_EXPORT int OBJ_cbs2nid(const CBS *cbs); 117 118 // OBJ_sn2nid returns the nid corresponding to |short_name|, or |NID_undef| if 119 // no such short name is known. 120 OPENSSL_EXPORT int OBJ_sn2nid(const char *short_name); 121 122 // OBJ_ln2nid returns the nid corresponding to |long_name|, or |NID_undef| if 123 // no such long name is known. 124 OPENSSL_EXPORT int OBJ_ln2nid(const char *long_name); 125 126 // OBJ_txt2nid returns the nid corresponding to |s|, which may be a short name, 127 // long name, or an ASCII string containing a dotted sequence of numbers. It 128 // returns the nid or NID_undef if unknown. 129 OPENSSL_EXPORT int OBJ_txt2nid(const char *s); 130 131 132 // Getting information about nids. 133 134 // OBJ_nid2obj returns the |ASN1_OBJECT| corresponding to |nid|, or NULL if 135 // |nid| is unknown. 136 // 137 // Although the output is not const, this function returns a static, immutable 138 // |ASN1_OBJECT|. It is not necessary to release the object with 139 // |ASN1_OBJECT_free|. 140 // 141 // However, functions like |X509_ALGOR_set0| expect to take ownership of a 142 // possibly dynamically-allocated |ASN1_OBJECT|. |ASN1_OBJECT_free| is a no-op 143 // for static |ASN1_OBJECT|s, so |OBJ_nid2obj| is compatible with such 144 // functions. 145 // 146 // Callers are encouraged to store the result of this function in a const 147 // pointer. However, if using functions like |X509_ALGOR_set0|, callers may use 148 // a non-const pointer and manage ownership. 149 OPENSSL_EXPORT ASN1_OBJECT *OBJ_nid2obj(int nid); 150 151 // OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. 152 OPENSSL_EXPORT const char *OBJ_nid2sn(int nid); 153 154 // OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown. 155 OPENSSL_EXPORT const char *OBJ_nid2ln(int nid); 156 157 // OBJ_nid2cbb writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns 158 // one on success or zero otherwise. 159 OPENSSL_EXPORT int OBJ_nid2cbb(CBB *out, int nid); 160 161 162 // Dealing with textual representations of object identifiers. 163 164 // OBJ_txt2obj returns an ASN1_OBJECT for the textual representation in |s|. 165 // If |dont_search_names| is zero, then |s| will be matched against the long 166 // and short names of a known objects to find a match. Otherwise |s| must 167 // contain an ASCII string with a dotted sequence of numbers. The resulting 168 // object need not be previously known. It returns a freshly allocated 169 // |ASN1_OBJECT| or NULL on error. 170 OPENSSL_EXPORT ASN1_OBJECT *OBJ_txt2obj(const char *s, int dont_search_names); 171 172 // OBJ_obj2txt converts |obj| to a textual representation. If 173 // |always_return_oid| is zero then |obj| will be matched against known objects 174 // and the long (preferably) or short name will be used if found. Otherwise 175 // |obj| will be converted into a dotted sequence of integers. If |out| is not 176 // NULL, then at most |out_len| bytes of the textual form will be written 177 // there. If |out_len| is at least one, then string written to |out| will 178 // always be NUL terminated. It returns the number of characters that could 179 // have been written, not including the final NUL, or -1 on error. 180 OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj, 181 int always_return_oid); 182 183 184 // Adding objects at runtime. 185 186 // OBJ_create adds a known object and returns the NID of the new object, or 187 // NID_undef on error. 188 // 189 // WARNING: This function modifies global state. The table cannot contain 190 // duplicate OIDs, short names, or long names. If two callers in the same 191 // address space add conflicting values, only one registration will take effect. 192 // Avoid this function if possible. Instead, callers can process OIDs unknown to 193 // BoringSSL by acting on the byte representation directly. See |OBJ_get0_data| 194 // and |OBJ_length|. 195 OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name, 196 const char *long_name); 197 198 199 // Handling signature algorithm identifiers. 200 // 201 // Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and 202 // a public key algorithm. The following functions map between pairs of digest 203 // and public-key algorithms and the NIDs that specify their combination. 204 // 205 // Sometimes the combination NID leaves the digest unspecified (e.g. 206 // rsassaPss). In these cases, the digest NID is |NID_undef|. 207 208 // OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to 209 // the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid| 210 // and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of 211 // |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need 212 // that output value. 213 OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid, 214 int *out_pkey_nid); 215 216 // OBJ_find_sigid_by_algs finds the signature NID that corresponds to the 217 // combination of |digest_nid| and |pkey_nid|. If success, it sets 218 // |*out_sign_nid| and returns one. Otherwise it returns zero. The 219 // |out_sign_nid| argument can be NULL if the caller only wishes to learn 220 // whether the combination is valid. 221 OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid, 222 int pkey_nid); 223 224 225 // Deprecated functions. 226 227 typedef struct obj_name_st { 228 int type; 229 int alias; 230 const char *name; 231 const char *data; 232 } OBJ_NAME; 233 234 #define OBJ_NAME_TYPE_MD_METH 1 235 #define OBJ_NAME_TYPE_CIPHER_METH 2 236 237 // OBJ_NAME_do_all_sorted calls |callback| zero or more times, each time with 238 // the name of a different primitive. If |type| is |OBJ_NAME_TYPE_MD_METH| then 239 // the primitives will be hash functions, alternatively if |type| is 240 // |OBJ_NAME_TYPE_CIPHER_METH| then the primitives will be ciphers or cipher 241 // modes. 242 // 243 // This function is ill-specified and should never be used. 244 OPENSSL_EXPORT void OBJ_NAME_do_all_sorted( 245 int type, void (*callback)(const OBJ_NAME *, void *arg), void *arg); 246 247 // OBJ_NAME_do_all calls |OBJ_NAME_do_all_sorted|. 248 OPENSSL_EXPORT void OBJ_NAME_do_all(int type, void (*callback)(const OBJ_NAME *, 249 void *arg), 250 void *arg); 251 252 // OBJ_cleanup does nothing. 253 OPENSSL_EXPORT void OBJ_cleanup(void); 254 255 256 #if defined(__cplusplus) 257 } // extern C 258 #endif 259 260 #define OBJ_R_UNKNOWN_NID 100 261 #define OBJ_R_INVALID_OID_STRING 101 262 263 #endif // OPENSSL_HEADER_OBJ_H 264