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. 88 OPENSSL_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. 92 OPENSSL_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|. 95 OPENSSL_EXPORT const uint8_t *OBJ_get0_data(const ASN1_OBJECT *obj); 96 97 // OBJ_length returns the length of the DER representation of |obj|. 98 OPENSSL_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. 105 OPENSSL_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. 109 OPENSSL_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. 113 OPENSSL_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. 117 OPENSSL_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. 122 OPENSSL_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. 129 OPENSSL_EXPORT const ASN1_OBJECT *OBJ_nid2obj(int nid); 130 131 // OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. 132 OPENSSL_EXPORT const char *OBJ_nid2sn(int nid); 133 134 // OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown. 135 OPENSSL_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. 139 OPENSSL_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. 150 OPENSSL_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. 160 OPENSSL_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. 168 OPENSSL_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. 186 OPENSSL_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. 194 OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid, 195 int pkey_nid); 196 197 198 // Deprecated functions. 199 200 typedef 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. 217 OPENSSL_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|. 221 OPENSSL_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. 226 OPENSSL_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