src/libstrongswan/credentials/keys/public_key.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup public_key public_key
  18  * @{ @ingroup keys
  19  */
  20
  21 #ifndef PUBLIC_KEY_H_
  22 #define PUBLIC_KEY_H_
  23
  24 typedef struct public_key_t public_key_t;
  25 typedef enum key_type_t key_type_t;
  26 typedef enum key_id_type_t key_id_type_t;
  27 typedef enum signature_scheme_t signature_scheme_t;
  28
  29 #include <library.h>
  30 #include <utils/identification.h>
  31
  32 /**
  33  * Type of a key pair, the used crypto system
  34  */
  35 enum key_type_t {
  36         /** key type wildcard */
  37         KEY_ANY   = 0,
  38         /** RSA crypto system as in PKCS#1 */
  39         KEY_RSA   = 1,
  40         /** ECDSA as in ANSI X9.62 */
  41         KEY_ECDSA = 2,
  42         /** DSA */
  43         KEY_DSA   = 3,
  44         /** ElGamal, ... */
  45 };
  46
  47 /**
  48  * Enum names for key_type_t
  49  */
  50 extern enum_name_t *key_type_names;
  51
  52 /**
  53  * Signature scheme for signature creation
  54  *
  55  * EMSA-PKCS1 signatures are defined in PKCS#1 standard.
  56  * A prepended ASN.1 encoded digestInfo field contains the
  57  * OID of the used hash algorithm.
  58  */
  59 enum signature_scheme_t {
  60         /** Unknown signature scheme                                       */
  61         SIGN_UNKNOWN,
  62         /** EMSA-PKCS1_v1.5 signature over digest without digestInfo       */
  63         SIGN_RSA_EMSA_PKCS1_NULL,
  64         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and MD5       */
  65         SIGN_RSA_EMSA_PKCS1_MD5,
  66         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-1     */
  67         SIGN_RSA_EMSA_PKCS1_SHA1,
  68         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-224   */
  69         SIGN_RSA_EMSA_PKCS1_SHA224,
  70         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-256   */
  71         SIGN_RSA_EMSA_PKCS1_SHA256,
  72         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-384   */
  73         SIGN_RSA_EMSA_PKCS1_SHA384,
  74         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-512   */
  75         SIGN_RSA_EMSA_PKCS1_SHA512,
  76         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  77         SIGN_ECDSA_WITH_SHA1_DER,
  78         /** ECDSA with SHA-256 using DER encoding as in RFC 3279           */
  79         SIGN_ECDSA_WITH_SHA256_DER,
  80         /** ECDSA with SHA-384 using DER encoding as in RFC 3279           */
  81         SIGN_ECDSA_WITH_SHA384_DER,
  82         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  83         SIGN_ECDSA_WITH_SHA512_DER,
  84         /** ECDSA over precomputed digest, signature as in RFC 4754        */
  85         SIGN_ECDSA_WITH_NULL,
  86         /** ECDSA on the P-256 curve with SHA-256 as in RFC 4754           */
  87         SIGN_ECDSA_256,
  88         /** ECDSA on the P-384 curve with SHA-384 as in RFC 4754           */
  89         SIGN_ECDSA_384,
  90         /** ECDSA on the P-521 curve with SHA-512 as in RFC 4754           */
  91         SIGN_ECDSA_521,
  92 };
  93
  94 /**
  95  * Enum names for signature_scheme_t
  96  */
  97 extern enum_name_t *signature_scheme_names;
  98
  99 /**
 100  * Abstract interface of a public key.
 101  */
 102 struct public_key_t {
 103
 104         /**
 105          * Get the key type.
 106          *
 107          * @return                      type of the key
 108          */
 109         key_type_t (*get_type)(public_key_t *this);
 110
 111         /**
 112          * Verifies a signature against a chunk of data.
 113          *
 114          * @param scheme        signature scheme to use for verification, may be default
 115          * @param data          data to check signature against
 116          * @param signature     signature to check
 117          * @return                      TRUE if signature matches
 118          */
 119         bool (*verify)(public_key_t *this, signature_scheme_t scheme,
 120                                    chunk_t data, chunk_t signature);
 121
 122         /**
 123          * Encrypt a chunk of data.
 124          *
 125          * @param plain         chunk containing plaintext data
 126          * @param crypto        where to allocate encrypted data
 127          * @return                      TRUE if data successfully encrypted
 128          */
 129         bool (*encrypt)(public_key_t *this, chunk_t plain, chunk_t *crypto);
 130
 131         /**
 132          * Check if two public keys are equal.
 133          *
 134          * @param other         other public key
 135          * @return                      TRUE, if equality
 136          */
 137         bool (*equals)(public_key_t *this, public_key_t *other);
 138
 139         /**
 140          * Get the strength of the key in bytes.
 141          *
 142          * @return                      strength of the key in bytes
 143          */
 144         size_t (*get_keysize) (public_key_t *this);
 145
 146         /**
 147          * Get the fingerprint of the key.
 148          *
 149          * @param type          type of fingerprint, one of KEY_ID_*
 150          * @param fp            fingerprint, points to internal data
 151          * @return                      TRUE if fingerprint type supported
 152          */
 153         bool (*get_fingerprint)(public_key_t *this, key_encoding_type_t type,
 154                                                         chunk_t *fp);
 155
 156         /**
 157          * Get the key in an encoded form as a chunk.
 158          *
 159          * @param type          type of the encoding, one of KEY_PRIV_*
 160          * @param encoding      encoding of the key, allocated
 161          * @return                      TRUE if encoding supported
 162          */
 163         bool (*get_encoding)(public_key_t *this, key_encoding_type_t type,
 164                                                  chunk_t *encoding);
 165
 166         /**
 167          * Increase the refcount of the key.
 168          *
 169          * @return                      this with an increased refcount
 170          */
 171         public_key_t* (*get_ref)(public_key_t *this);
 172
 173         /**
 174          * Destroy a public_key instance.
 175          */
 176         void (*destroy)(public_key_t *this);
 177 };
 178
 179 /**
 180  * Generic public key equals() implementation, usable by implementors.
 181  *
 182  * @param this                  first key to compare
 183  * @param other                 second key to compare
 184  * @return                              TRUE if this is equal to other
 185  */
 186 bool public_key_equals(public_key_t *this, public_key_t *other);
 187
 188 /**
 189  * Conversion of ASN.1 signature or hash OID to signature scheme.
 190  *
 191  * @param oid                   ASN.1 OID
 192  * @return                              signature_scheme, SIGN_UNKNOWN if OID is unsupported
 193  */
 194 signature_scheme_t signature_scheme_from_oid(int oid);
 195
 196 #endif /** PUBLIC_KEY_H_ @}*/