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 OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name, 189 const char *long_name); 190 191 192 // Handling signature algorithm identifiers. 193 // 194 // Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and 195 // a public key algorithm. The following functions map between pairs of digest 196 // and public-key algorithms and the NIDs that specify their combination. 197 // 198 // Sometimes the combination NID leaves the digest unspecified (e.g. 199 // rsassaPss). In these cases, the digest NID is |NID_undef|. 200 201 // OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to 202 // the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid| 203 // and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of 204 // |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need 205 // that output value. 206 OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid, 207 int *out_pkey_nid); 208 209 // OBJ_find_sigid_by_algs finds the signature NID that corresponds to the 210 // combination of |digest_nid| and |pkey_nid|. If success, it sets 211 // |*out_sign_nid| and returns one. Otherwise it returns zero. The 212 // |out_sign_nid| argument can be NULL if the caller only wishes to learn 213 // whether the combination is valid. 214 OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid, 215 int pkey_nid); 216 217 218 // Deprecated functions. 219 220 typedef struct obj_name_st { 221 int type; 222 int alias; 223 const char *name; 224 const char *data; 225 } OBJ_NAME; 226 227 #define OBJ_NAME_TYPE_MD_METH 1 228 #define OBJ_NAME_TYPE_CIPHER_METH 2 229 230 // OBJ_NAME_do_all_sorted calls |callback| zero or more times, each time with 231 // the name of a different primitive. If |type| is |OBJ_NAME_TYPE_MD_METH| then 232 // the primitives will be hash functions, alternatively if |type| is 233 // |OBJ_NAME_TYPE_CIPHER_METH| then the primitives will be ciphers or cipher 234 // modes. 235 // 236 // This function is ill-specified and should never be used. 237 OPENSSL_EXPORT void OBJ_NAME_do_all_sorted( 238 int type, void (*callback)(const OBJ_NAME *, void *arg), void *arg); 239 240 // OBJ_NAME_do_all calls |OBJ_NAME_do_all_sorted|. 241 OPENSSL_EXPORT void OBJ_NAME_do_all(int type, void (*callback)(const OBJ_NAME *, 242 void *arg), 243 void *arg); 244 245 // OBJ_cleanup does nothing. 246 OPENSSL_EXPORT void OBJ_cleanup(void); 247 248 249 #if defined(__cplusplus) 250 } // extern C 251 #endif 252 253 #define OBJ_R_UNKNOWN_NID 100 254 #define OBJ_R_INVALID_OID_STRING 101 255 256 #endif // OPENSSL_HEADER_OBJ_H 257