1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_OBJ_H 11 #define OPENSSL_HEADER_OBJ_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/bytestring.h> 16 #include <openssl/nid.h> // IWYU pragma: export 17 18 #if defined(__cplusplus) 19 extern "C" { 20 #endif 21 22 23 // The objects library deals with the registration and indexing of ASN.1 object 24 // identifiers. These values are often written as a dotted sequence of numbers, 25 // e.g. 1.2.840.113549.1.9.16.3.9. 26 // 27 // Internally, OpenSSL likes to deal with these values by numbering them with 28 // numbers called "nids". OpenSSL has a large, built-in database of common 29 // object identifiers and also has both short and long names for them. 30 // 31 // This library provides functions for translating between object identifiers, 32 // nids, short names and long names. 33 // 34 // The nid values should not be used outside of a single process: they are not 35 // stable identifiers. 36 37 38 // Basic operations. 39 40 // OBJ_dup returns a duplicate copy of |obj| or NULL on allocation failure. The 41 // caller must call |ASN1_OBJECT_free| on the result to release it. 42 OPENSSL_EXPORT ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *obj); 43 44 // OBJ_cmp returns a value less than, equal to or greater than zero if |a| is 45 // less than, equal to or greater than |b|, respectively. 46 OPENSSL_EXPORT int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); 47 48 // OBJ_get0_data returns a pointer to the DER representation of |obj|. This is 49 // the contents of the DER-encoded identifier, not including the tag and length. 50 // If |obj| does not have an associated object identifier (i.e. it is a nid-only 51 // value), this value is the empty string. 52 OPENSSL_EXPORT const uint8_t *OBJ_get0_data(const ASN1_OBJECT *obj); 53 54 // OBJ_length returns the length of the DER representation of |obj|. This is the 55 // contents of the DER-encoded identifier, not including the tag and length. If 56 // |obj| does not have an associated object identifier (i.e. it is a nid-only 57 // value), this value is the empty string. 58 OPENSSL_EXPORT size_t OBJ_length(const ASN1_OBJECT *obj); 59 60 61 // Looking up nids. 62 63 // OBJ_obj2nid returns the nid corresponding to |obj|, or |NID_undef| if no 64 // such object is known. 65 OPENSSL_EXPORT int OBJ_obj2nid(const ASN1_OBJECT *obj); 66 67 // OBJ_cbs2nid returns the nid corresponding to the DER data in |cbs|, or 68 // |NID_undef| if no such object is known. 69 OPENSSL_EXPORT int OBJ_cbs2nid(const CBS *cbs); 70 71 // OBJ_sn2nid returns the nid corresponding to |short_name|, or |NID_undef| if 72 // no such short name is known. 73 OPENSSL_EXPORT int OBJ_sn2nid(const char *short_name); 74 75 // OBJ_ln2nid returns the nid corresponding to |long_name|, or |NID_undef| if 76 // no such long name is known. 77 OPENSSL_EXPORT int OBJ_ln2nid(const char *long_name); 78 79 // OBJ_txt2nid returns the nid corresponding to |s|, which may be a short name, 80 // long name, or an ASCII string containing a dotted sequence of numbers. It 81 // returns the nid or NID_undef if unknown. 82 OPENSSL_EXPORT int OBJ_txt2nid(const char *s); 83 84 85 // Getting information about nids. 86 87 // OBJ_nid2obj returns the |ASN1_OBJECT| corresponding to |nid|, or NULL if 88 // |nid| is unknown. 89 // 90 // Although the output is not const, this function returns a static, immutable 91 // |ASN1_OBJECT|. It is not necessary to release the object with 92 // |ASN1_OBJECT_free|. 93 // 94 // However, functions like |X509_ALGOR_set0| expect to take ownership of a 95 // possibly dynamically-allocated |ASN1_OBJECT|. |ASN1_OBJECT_free| is a no-op 96 // for static |ASN1_OBJECT|s, so |OBJ_nid2obj| is compatible with such 97 // functions. 98 // 99 // Callers are encouraged to store the result of this function in a const 100 // pointer. However, if using functions like |X509_ALGOR_set0|, callers may use 101 // a non-const pointer and manage ownership. 102 OPENSSL_EXPORT ASN1_OBJECT *OBJ_nid2obj(int nid); 103 104 // OBJ_get_undef returns the object for |NID_undef|. Prefer this function over 105 // |OBJ_nid2obj| to avoid pulling in the full OID table. 106 OPENSSL_EXPORT const ASN1_OBJECT *OBJ_get_undef(void); 107 108 // OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. 109 OPENSSL_EXPORT const char *OBJ_nid2sn(int nid); 110 111 // OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown. 112 OPENSSL_EXPORT const char *OBJ_nid2ln(int nid); 113 114 // OBJ_nid2cbb writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns 115 // one on success or zero otherwise. 116 OPENSSL_EXPORT int OBJ_nid2cbb(CBB *out, int nid); 117 118 119 // Dealing with textual representations of object identifiers. 120 121 // OBJ_txt2obj returns an ASN1_OBJECT for the textual representation in |s|. 122 // If |dont_search_names| is zero, then |s| will be matched against the long 123 // and short names of a known objects to find a match. Otherwise |s| must 124 // contain an ASCII string with a dotted sequence of numbers. The resulting 125 // object need not be previously known. It returns a freshly allocated 126 // |ASN1_OBJECT| or NULL on error. 127 OPENSSL_EXPORT ASN1_OBJECT *OBJ_txt2obj(const char *s, int dont_search_names); 128 129 // OBJ_obj2txt converts |obj| to a textual representation. If 130 // |always_return_oid| is zero then |obj| will be matched against known objects 131 // and the long (preferably) or short name will be used if found. Otherwise 132 // |obj| will be converted into a dotted sequence of integers. If |out| is not 133 // NULL, then at most |out_len| bytes of the textual form will be written 134 // there. If |out_len| is at least one, then string written to |out| will 135 // always be NUL terminated. It returns the number of characters that could 136 // have been written, not including the final NUL, or -1 on error. 137 OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj, 138 int always_return_oid); 139 140 141 // Adding objects at runtime. 142 143 // OBJ_create adds a known object and returns the NID of the new object, or 144 // NID_undef on error. 145 // 146 // WARNING: This function modifies global state. The table cannot contain 147 // duplicate OIDs, short names, or long names. If two callers in the same 148 // address space add conflicting values, only one registration will take effect. 149 // Avoid this function if possible. Instead, callers can process OIDs unknown to 150 // BoringSSL by acting on the byte representation directly. See 151 // |ASN1_OBJECT_create|, |OBJ_get0_data|, and |OBJ_length|. 152 OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name, 153 const char *long_name); 154 155 156 // Handling signature algorithm identifiers. 157 // 158 // Some NIDs (e.g. sha256WithRSAEncryption) specify both a digest algorithm and 159 // a public key algorithm. The following functions map between pairs of digest 160 // and public-key algorithms and the NIDs that specify their combination. 161 // 162 // Sometimes the combination NID leaves the digest unspecified (e.g. 163 // rsassaPss). In these cases, the digest NID is |NID_undef|. 164 165 // OBJ_find_sigid_algs finds the digest and public-key NIDs that correspond to 166 // the signing algorithm |sign_nid|. If successful, it sets |*out_digest_nid| 167 // and |*out_pkey_nid| and returns one. Otherwise it returns zero. Any of 168 // |out_digest_nid| or |out_pkey_nid| can be NULL if the caller doesn't need 169 // that output value. 170 OPENSSL_EXPORT int OBJ_find_sigid_algs(int sign_nid, int *out_digest_nid, 171 int *out_pkey_nid); 172 173 // OBJ_find_sigid_by_algs finds the signature NID that corresponds to the 174 // combination of |digest_nid| and |pkey_nid|. If success, it sets 175 // |*out_sign_nid| and returns one. Otherwise it returns zero. The 176 // |out_sign_nid| argument can be NULL if the caller only wishes to learn 177 // whether the combination is valid. 178 OPENSSL_EXPORT int OBJ_find_sigid_by_algs(int *out_sign_nid, int digest_nid, 179 int pkey_nid); 180 181 182 // Deprecated functions. 183 184 typedef struct obj_name_st { 185 int type; 186 int alias; 187 const char *name; 188 const char *data; 189 } OBJ_NAME; 190 191 #define OBJ_NAME_TYPE_MD_METH 1 192 #define OBJ_NAME_TYPE_CIPHER_METH 2 193 194 // OBJ_NAME_do_all_sorted calls |callback| zero or more times, each time with 195 // the name of a different primitive. If |type| is |OBJ_NAME_TYPE_MD_METH| then 196 // the primitives will be hash functions, alternatively if |type| is 197 // |OBJ_NAME_TYPE_CIPHER_METH| then the primitives will be ciphers or cipher 198 // modes. 199 // 200 // This function is ill-specified and should never be used. 201 OPENSSL_EXPORT void OBJ_NAME_do_all_sorted( 202 int type, void (*callback)(const OBJ_NAME *, void *arg), void *arg); 203 204 // OBJ_NAME_do_all calls |OBJ_NAME_do_all_sorted|. 205 OPENSSL_EXPORT void OBJ_NAME_do_all(int type, void (*callback)(const OBJ_NAME *, 206 void *arg), 207 void *arg); 208 209 // OBJ_cleanup does nothing. 210 OPENSSL_EXPORT void OBJ_cleanup(void); 211 212 213 #if defined(__cplusplus) 214 } // extern C 215 #endif 216 217 #define OBJ_R_UNKNOWN_NID 100 218 #define OBJ_R_INVALID_OID_STRING 101 219 220 #endif // OPENSSL_HEADER_OBJ_H 221