Home | History | Annotate | Download | only in openssl 
      1 /* Copyright (C) 1995-1998 Eric Young (eay (at) cryptsoft.com)
      2  * All rights reserved.
      3  *
      4  * This package is an SSL implementation written
      5  * by Eric Young (eay (at) 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 (at) 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 (at) 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 (at) 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