1 /* Copyright (C) 1995-1998 Eric Young ([email protected]) 2 * All rights reserved. 3 * 4 * This package is an SSL implementation written 5 * by Eric Young ([email protected]). 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 ([email protected]). 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 ([email protected])" 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 ([email protected])" 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> // IWYU pragma: export 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_get_undef returns the object for |NID_undef|. Prefer this function over 152 // |OBJ_nid2obj| to avoid pulling in the full OID table. 153 OPENSSL_EXPORT const ASN1_OBJECT *OBJ_get_undef(void); 154 155 // OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. 156 OPENSSL_EXPORT const char *OBJ_nid2sn(int nid); 157 158 // OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown. 159 OPENSSL_EXPORT const char *OBJ_nid2ln(int nid); 160 161 // OBJ_nid2cbb writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns 162 // one on success or zero otherwise. 163 OPENSSL_EXPORT int OBJ_nid2cbb(CBB *out, int nid); 164 165 166 // Dealing with textual representations of object identifiers. 167 168 // OBJ_txt2obj returns an ASN1_OBJECT for the textual representation in |s|. 169 // If |dont_search_names| is zero, then |s| will be matched against the long 170 // and short names of a known objects to find a match. Otherwise |s| must 171 // contain an ASCII string with a dotted sequence of numbers. The resulting 172 // object need not be previously known. It returns a freshly allocated 173 // |ASN1_OBJECT| or NULL on error. 174 OPENSSL_EXPORT ASN1_OBJECT *OBJ_txt2obj(const char *s, int dont_search_names); 175 176 // OBJ_obj2txt converts |obj| to a textual representation. If 177 // |always_return_oid| is zero then |obj| will be matched against known objects 178 // and the long (preferably) or short name will be used if found. Otherwise 179 // |obj| will be converted into a dotted sequence of integers. If |out| is not 180 // NULL, then at most |out_len| bytes of the textual form will be written 181 // there. If |out_len| is at least one, then string written to |out| will 182 // always be NUL terminated. It returns the number of characters that could 183 // have been written, not including the final NUL, or -1 on error. 184 OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj, 185 int always_return_oid); 186 187 188 // Adding objects at runtime. 189 190 // OBJ_create adds a known object and returns the NID of the new object, or 191 // NID_undef on error. 192 // 193 // WARNING: This function modifies global state. The table cannot contain 194 // duplicate OIDs, short names, or long names. If two callers in the same 195 // address space add conflicting values, only one registration will take effect. 196 // Avoid this function if possible. Instead, callers can process OIDs unknown to 197 // BoringSSL by acting on the byte representation directly. See 198 // |ASN1_OBJECT_create|, |OBJ_get0_data|, and |OBJ_length|. 199 OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name, 200 const char *long_name); 201 202 203 // Handling signature algorithm identifiers. 204 // 205 // Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and 206 // a public key algorithm. The following functions map between pairs of digest 207 // and public-key algorithms and the NIDs that specify their combination. 208 // 209 // Sometimes the combination NID leaves the digest unspecified (e.g. 210 // rsassaPss). In these cases, the digest NID is |NID_undef|. 211 212 // OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to 213 // the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid| 214 // and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of 215 // |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need 216 // that output value. 217 OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid, 218 int *out_pkey_nid); 219 220 // OBJ_find_sigid_by_algs finds the signature NID that corresponds to the 221 // combination of |digest_nid| and |pkey_nid|. If success, it sets 222 // |*out_sign_nid| and returns one. Otherwise it returns zero. The 223 // |out_sign_nid| argument can be NULL if the caller only wishes to learn 224 // whether the combination is valid. 225 OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid, 226 int pkey_nid); 227 228 229 // Deprecated functions. 230 231 typedef struct obj_name_st { 232 int type; 233 int alias; 234 const char *name; 235 const char *data; 236 } OBJ_NAME; 237 238 #define OBJ_NAME_TYPE_MD_METH 1 239 #define OBJ_NAME_TYPE_CIPHER_METH 2 240 241 // OBJ_NAME_do_all_sorted calls |callback| zero or more times, each time with 242 // the name of a different primitive. If |type| is |OBJ_NAME_TYPE_MD_METH| then 243 // the primitives will be hash functions, alternatively if |type| is 244 // |OBJ_NAME_TYPE_CIPHER_METH| then the primitives will be ciphers or cipher 245 // modes. 246 // 247 // This function is ill-specified and should never be used. 248 OPENSSL_EXPORT void OBJ_NAME_do_all_sorted( 249 int type, void (*callback)(const OBJ_NAME *, void *arg), void *arg); 250 251 // OBJ_NAME_do_all calls |OBJ_NAME_do_all_sorted|. 252 OPENSSL_EXPORT void OBJ_NAME_do_all(int type, void (*callback)(const OBJ_NAME *, 253 void *arg), 254 void *arg); 255 256 // OBJ_cleanup does nothing. 257 OPENSSL_EXPORT void OBJ_cleanup(void); 258 259 260 #if defined(__cplusplus) 261 } // extern C 262 #endif 263 264 #define OBJ_R_UNKNOWN_NID 100 265 #define OBJ_R_INVALID_OID_STRING 101 266 267 #endif // OPENSSL_HEADER_OBJ_H 268