src/libstrongswan/credentials/keys/public_key.h

   1 /*
   2  * Copyright (C) 2015 Tobias Brunner
   3  * Copyright (C) 2007 Martin Willi
   4  * Copyright (C) 2014-2015 Andreas Steffen
   5  * HSR Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup public_key public_key
  20  * @{ @ingroup keys
  21  */
  22
  23 #ifndef PUBLIC_KEY_H_
  24 #define PUBLIC_KEY_H_
  25
  26 typedef struct public_key_t public_key_t;
  27 typedef enum key_type_t key_type_t;
  28 typedef enum signature_scheme_t signature_scheme_t;
  29 typedef enum encryption_scheme_t encryption_scheme_t;
  30
  31 #include <library.h>
  32 #include <utils/identification.h>
  33 #include <credentials/cred_encoding.h>
  34
  35 /**
  36  * Type of a key pair, the used crypto system
  37  */
  38 enum key_type_t {
  39         /** key type wildcard */
  40         KEY_ANY   = 0,
  41         /** RSA crypto system as in PKCS#1 */
  42         KEY_RSA   = 1,
  43         /** ECDSA as in ANSI X9.62 */
  44         KEY_ECDSA = 2,
  45         /** DSA */
  46         KEY_DSA   = 3,
  47         /** BLISS */
  48         KEY_BLISS = 4,
  49         /** ElGamal, ... */
  50 };
  51
  52 /**
  53  * Enum names for key_type_t
  54  */
  55 extern enum_name_t *key_type_names;
  56
  57 /**
  58  * Signature scheme for signature creation
  59  *
  60  * EMSA-PKCS1 signatures are defined in PKCS#1 standard.
  61  * A prepended ASN.1 encoded digestInfo field contains the
  62  * OID of the used hash algorithm.
  63  */
  64 enum signature_scheme_t {
  65         /** Unknown signature scheme                                       */
  66         SIGN_UNKNOWN,
  67         /** EMSA-PKCS1_v1.5 signature over digest without digestInfo       */
  68         SIGN_RSA_EMSA_PKCS1_NULL,
  69         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and MD5       */
  70         SIGN_RSA_EMSA_PKCS1_MD5,
  71         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-1     */
  72         SIGN_RSA_EMSA_PKCS1_SHA1,
  73         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-224   */
  74         SIGN_RSA_EMSA_PKCS1_SHA224,
  75         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-256   */
  76         SIGN_RSA_EMSA_PKCS1_SHA256,
  77         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-384   */
  78         SIGN_RSA_EMSA_PKCS1_SHA384,
  79         /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-512   */
  80         SIGN_RSA_EMSA_PKCS1_SHA512,
  81         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  82         SIGN_ECDSA_WITH_SHA1_DER,
  83         /** ECDSA with SHA-256 using DER encoding as in RFC 3279           */
  84         SIGN_ECDSA_WITH_SHA256_DER,
  85         /** ECDSA with SHA-384 using DER encoding as in RFC 3279           */
  86         SIGN_ECDSA_WITH_SHA384_DER,
  87         /** ECDSA with SHA-1 using DER encoding as in RFC 3279             */
  88         SIGN_ECDSA_WITH_SHA512_DER,
  89         /** ECDSA over precomputed digest, signature as in RFC 4754        */
  90         SIGN_ECDSA_WITH_NULL,
  91         /** ECDSA on the P-256 curve with SHA-256 as in RFC 4754           */
  92         SIGN_ECDSA_256,
  93         /** ECDSA on the P-384 curve with SHA-384 as in RFC 4754           */
  94         SIGN_ECDSA_384,
  95         /** ECDSA on the P-521 curve with SHA-512 as in RFC 4754           */
  96         SIGN_ECDSA_521,
  97         /** BLISS with SHA-2_256                                           */
  98         SIGN_BLISS_WITH_SHA2_256,
  99         /** BLISS with SHA-2_384                                           */
 100         SIGN_BLISS_WITH_SHA2_384,
 101         /** BLISS with SHA-2_512                                           */
 102         SIGN_BLISS_WITH_SHA2_512,
 103         /** BLISS with SHA-3_256                                           */
 104         SIGN_BLISS_WITH_SHA3_256,
 105         /** BLISS with SHA-3_384                                           */
 106         SIGN_BLISS_WITH_SHA3_384,
 107         /** BLISS with SHA-3_512                                           */
 108         SIGN_BLISS_WITH_SHA3_512,
 109 };
 110
 111 /**
 112  * Enum names for signature_scheme_t
 113  */
 114 extern enum_name_t *signature_scheme_names;
 115
 116 /**
 117  * Encryption scheme for public key data encryption.
 118  */
 119 enum encryption_scheme_t {
 120         /** Unknown encryption scheme                                      */
 121         ENCRYPT_UNKNOWN,
 122         /** RSAES-PKCS1-v1_5 as in PKCS#1                                  */
 123         ENCRYPT_RSA_PKCS1,
 124         /** RSAES-OAEP as in PKCS#1, using SHA1 as hash, no label          */
 125         ENCRYPT_RSA_OAEP_SHA1,
 126         /** RSAES-OAEP as in PKCS#1, using SHA-224 as hash, no label       */
 127         ENCRYPT_RSA_OAEP_SHA224,
 128         /** RSAES-OAEP as in PKCS#1, using SHA-256 as hash, no label       */
 129         ENCRYPT_RSA_OAEP_SHA256,
 130         /** RSAES-OAEP as in PKCS#1, using SHA-384 as hash, no label       */
 131         ENCRYPT_RSA_OAEP_SHA384,
 132         /** RSAES-OAEP as in PKCS#1, using SHA-512 as hash, no label       */
 133         ENCRYPT_RSA_OAEP_SHA512,
 134 };
 135
 136 /**
 137  * Enum names for encryption_scheme_t
 138  */
 139 extern enum_name_t *encryption_scheme_names;
 140
 141 /**
 142  * Abstract interface of a public key.
 143  */
 144 struct public_key_t {
 145
 146         /**
 147          * Get the key type.
 148          *
 149          * @return                      type of the key
 150          */
 151         key_type_t (*get_type)(public_key_t *this);
 152
 153         /**
 154          * Verifies a signature against a chunk of data.
 155          *
 156          * @param scheme        signature scheme to use for verification, may be default
 157          * @param data          data to check signature against
 158          * @param signature     signature to check
 159          * @return                      TRUE if signature matches
 160          */
 161         bool (*verify)(public_key_t *this, signature_scheme_t scheme,
 162                                    chunk_t data, chunk_t signature);
 163
 164         /**
 165          * Encrypt a chunk of data.
 166          *
 167          * @param scheme        encryption scheme to use
 168          * @param plain         chunk containing plaintext data
 169          * @param crypto        where to allocate encrypted data
 170          * @return                      TRUE if data successfully encrypted
 171          */
 172         bool (*encrypt)(public_key_t *this, encryption_scheme_t scheme,
 173                                         chunk_t plain, chunk_t *crypto);
 174
 175         /**
 176          * Check if two public keys are equal.
 177          *
 178          * @param other         other public key
 179          * @return                      TRUE, if equality
 180          */
 181         bool (*equals)(public_key_t *this, public_key_t *other);
 182
 183         /**
 184          * Get the strength of the key in bits.
 185          *
 186          * @return                      strength of the key in bits
 187          */
 188         int (*get_keysize) (public_key_t *this);
 189
 190         /**
 191          * Get the fingerprint of the key.
 192          *
 193          * @param type          type of fingerprint, one of KEYID_*
 194          * @param fp            fingerprint, points to internal data
 195          * @return                      TRUE if fingerprint type supported
 196          */
 197         bool (*get_fingerprint)(public_key_t *this, cred_encoding_type_t type,
 198                                                         chunk_t *fp);
 199
 200         /**
 201          * Check if a key has a given fingerprint of any kind.
 202          *
 203          * @param fp            fingerprint to check
 204          * @return                      TRUE if key has given fingerprint
 205          */
 206         bool (*has_fingerprint)(public_key_t *this, chunk_t fp);
 207
 208         /**
 209          * Get the key in an encoded form as a chunk.
 210          *
 211          * @param type          type of the encoding, one of PUBKEY_*
 212          * @param encoding      encoding of the key, allocated
 213          * @return                      TRUE if encoding supported
 214          */
 215         bool (*get_encoding)(public_key_t *this, cred_encoding_type_t type,
 216                                                  chunk_t *encoding);
 217
 218         /**
 219          * Increase the refcount of the key.
 220          *
 221          * @return                      this with an increased refcount
 222          */
 223         public_key_t* (*get_ref)(public_key_t *this);
 224
 225         /**
 226          * Destroy a public_key instance.
 227          */
 228         void (*destroy)(public_key_t *this);
 229 };
 230
 231 /**
 232  * Generic public key equals() implementation, usable by implementors.
 233  *
 234  * @param public                public key to check
 235  * @param other                 key to compare
 236  * @return                              TRUE if this is equal to other
 237  */
 238 bool public_key_equals(public_key_t *public, public_key_t *other);
 239
 240 /**
 241  * Generic public key has_fingerprint() implementation, usable by implementors.
 242  *
 243  * @param public                public key to check
 244  * @param fingerprint   fingerprint to check
 245  * @return                              TRUE if key has given fingerprint
 246  */
 247 bool public_key_has_fingerprint(public_key_t *public, chunk_t fingerprint);
 248
 249 /**
 250  * Conversion of ASN.1 signature or hash OID to signature scheme.
 251  *
 252  * @param oid                   ASN.1 OID
 253  * @return                              signature scheme, SIGN_UNKNOWN if OID is unsupported
 254  */
 255 signature_scheme_t signature_scheme_from_oid(int oid);
 256
 257 /**
 258  * Conversion of signature scheme to ASN.1 signature OID.
 259  *
 260  * @param scheme                signature scheme
 261  * @return                              ASN.1 OID, OID_UNKNOWN if not supported
 262  */
 263 int signature_scheme_to_oid(signature_scheme_t scheme);
 264
 265 /**
 266  * Enumerate signature schemes that are appropriate for a key of the given type
 267  * and size|strength.
 268  *
 269  * @param type                  type of the key
 270  * @param size                  size or strength of the key
 271  * @return                              enumerator over signature_scheme_t (increasing strength)
 272  */
 273 enumerator_t *signature_schemes_for_key(key_type_t type, int size);
 274
 275 /**
 276  * Determine the type of key associated with a given signature scheme.
 277  *
 278  * @param scheme                signature scheme
 279  * @return                              key type (could be KEY_ANY)
 280  */
 281 key_type_t key_type_from_signature_scheme(signature_scheme_t scheme);
 282
 283
 284 #endif /** PUBLIC_KEY_H_ @}*/