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 #include <credentials/keys/key_encoding.h>
  32
  33 /**
  34  * Type of a key pair, the used crypto system
  35  */
  36 enum key_type_t {
  37         /** key type wildcard */
  38         KEY_ANY   = 0,
  39         /** RSA crypto system as in PKCS#1 */
  40         KEY_RSA   = 1,
  41         /** ECDSA as in ANSI X9.62 */
  42         KEY_ECDSA = 2,
  43         /** DSA */
  44         KEY_DSA   = 3,
  45         /** ElGamal, ... */
  46 };
  47
  48 /**
  49  * Enum names for key_type_t
  50  */
  51 extern enum_name_t *key_type_names;
  52
  53 /**
  54  * Signature scheme for signature creation
  55  *
  56  * EMSA-PKCS1 signatures are defined in PKCS#1 standard.
  57  * A prepended ASN.1 encoded digestInfo field contains the
  58  * OID of the used hash algorithm.
  59  */
  60 enum signature_scheme_t {
  61         /** Unknown signature scheme                                       */
  62         SIGN_UNKNOWN,
  63         /** EMSA-PKCS1_v1.5 signature over digest without digestInfo       */
  64         SIGN_RSA_EMSA_PKCS1_NULL,
  65         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and MD5       */
  66         SIGN_RSA_EMSA_PKCS1_MD5,
  67         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-1     */
  68         SIGN_RSA_EMSA_PKCS1_SHA1,
  69         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-224   */
  70         SIGN_RSA_EMSA_PKCS1_SHA224,
  71         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-256   */
  72         SIGN_RSA_EMSA_PKCS1_SHA256,
  73         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-384   */
  74         SIGN_RSA_EMSA_PKCS1_SHA384,
  75         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-512   */
  76         SIGN_RSA_EMSA_PKCS1_SHA512,
  77         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  78         SIGN_ECDSA_WITH_SHA1_DER,
  79         /** ECDSA with SHA-256 using DER encoding as in RFC 3279           */
  80         SIGN_ECDSA_WITH_SHA256_DER,
  81         /** ECDSA with SHA-384 using DER encoding as in RFC 3279           */
  82         SIGN_ECDSA_WITH_SHA384_DER,
  83         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  84         SIGN_ECDSA_WITH_SHA512_DER,
  85         /** ECDSA over precomputed digest, signature as in RFC 4754        */
  86         SIGN_ECDSA_WITH_NULL,
  87         /** ECDSA on the P-256 curve with SHA-256 as in RFC 4754           */
  88         SIGN_ECDSA_256,
  89         /** ECDSA on the P-384 curve with SHA-384 as in RFC 4754           */
  90         SIGN_ECDSA_384,
  91         /** ECDSA on the P-521 curve with SHA-512 as in RFC 4754           */
  92         SIGN_ECDSA_521,
  93 };
  94
  95 /**
  96  * Enum names for signature_scheme_t
  97  */
  98 extern enum_name_t *signature_scheme_names;
  99
 100 /**
 101  * Abstract interface of a public key.
 102  */
 103 struct public_key_t {
 104
 105         /**
 106          * Get the key type.
 107          *
 108          * @return                      type of the key
 109          */
 110         key_type_t (*get_type)(public_key_t *this);
 111
 112         /**
 113          * Verifies a signature against a chunk of data.
 114          *
 115          * @param scheme        signature scheme to use for verification, may be default
 116          * @param data          data to check signature against
 117          * @param signature     signature to check
 118          * @return                      TRUE if signature matches
 119          */
 120         bool (*verify)(public_key_t *this, signature_scheme_t scheme,
 121                                    chunk_t data, chunk_t signature);
 122
 123         /**
 124          * Encrypt a chunk of data.
 125          *
 126          * @param plain         chunk containing plaintext data
 127          * @param crypto        where to allocate encrypted data
 128          * @return                      TRUE if data successfully encrypted
 129          */
 130         bool (*encrypt)(public_key_t *this, chunk_t plain, chunk_t *crypto);
 131
 132         /**
 133          * Check if two public keys are equal.
 134          *
 135          * @param other         other public key
 136          * @return                      TRUE, if equality
 137          */
 138         bool (*equals)(public_key_t *this, public_key_t *other);
 139
 140         /**
 141          * Get the strength of the key in bytes.
 142          *
 143          * @return                      strength of the key in bytes
 144          */
 145         size_t (*get_keysize) (public_key_t *this);
 146
 147         /**
 148          * Get the fingerprint of the key.
 149          *
 150          * @param type          type of fingerprint, one of KEY_ID_*
 151          * @param fp            fingerprint, points to internal data
 152          * @return                      TRUE if fingerprint type supported
 153          */
 154         bool (*get_fingerprint)(public_key_t *this, key_encoding_type_t type,
 155                                                         chunk_t *fp);
 156
 157         /**
 158          * Check if a key has a given fingerprint of any kind.
 159          *
 160          * @param fp            fingerprint to check
 161          * @return                      TRUE if key has given fingerprint
 162          */
 163         bool (*has_fingerprint)(public_key_t *this, chunk_t fp);
 164
 165         /**
 166          * Get the key in an encoded form as a chunk.
 167          *
 168          * @param type          type of the encoding, one of KEY_PRIV_*
 169          * @param encoding      encoding of the key, allocated
 170          * @return                      TRUE if encoding supported
 171          */
 172         bool (*get_encoding)(public_key_t *this, key_encoding_type_t type,
 173                                                  chunk_t *encoding);
 174
 175         /**
 176          * Increase the refcount of the key.
 177          *
 178          * @return                      this with an increased refcount
 179          */
 180         public_key_t* (*get_ref)(public_key_t *this);
 181
 182         /**
 183          * Destroy a public_key instance.
 184          */
 185         void (*destroy)(public_key_t *this);
 186 };
 187
 188 /**
 189  * Generic public key equals() implementation, usable by implementors.
 190  *
 191  * @param this                  first key to compare
 192  * @param other                 second key to compare
 193  * @return                              TRUE if this is equal to other
 194  */
 195 bool public_key_equals(public_key_t *this, public_key_t *other);
 196
 197 /**
 198  * Generic public key has_fingerprint() implementation, usable by implementors.
 199  *
 200  * @param this                  key to check fingerprint
 201  * @param fp                    fingerprint to check
 202  * @return                              TRUE if key has given fingerprint
 203  */
 204 bool public_key_has_fingerprint(public_key_t *this, chunk_t fingerprint);
 205
 206 /**
 207  * Conversion of ASN.1 signature or hash OID to signature scheme.
 208  *
 209  * @param oid                   ASN.1 OID
 210  * @return                              signature_scheme, SIGN_UNKNOWN if OID is unsupported
 211  */
 212 signature_scheme_t signature_scheme_from_oid(int oid);
 213
 214 #endif /** PUBLIC_KEY_H_ @}*/