src/libstrongswan/credentials/keys/private_key.h

   1 /*
   2  * Copyright (C) 2017 Tobias Brunner
   3  * Copyright (C) 2007 Martin Willi
   4  * HSR Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup private_key private_key
  19  * @{ @ingroup keys
  20  */
  21
  22 #ifndef PRIVATE_KEY_H_
  23 #define PRIVATE_KEY_H_
  24
  25 typedef struct private_key_t private_key_t;
  26
  27 #include <credentials/cred_encoding.h>
  28 #include <credentials/keys/public_key.h>
  29
  30 /**
  31  * Abstract private key interface.
  32  */
  33 struct private_key_t {
  34
  35         /**
  36          * Get the key type.
  37          *
  38          * @return                      type of the key
  39          */
  40         key_type_t (*get_type)(private_key_t *this);
  41
  42         /**
  43          * Get signature schemes supported by this key.
  44          *
  45          * This is useful for keys that only support certain hash algorithms or
  46          * require specific parameters for RSA/PSS signatures.
  47          *
  48          * @note Implementing this method is optional. If multiple schemes are
  49          * returned, they should be ordered by decreasing preference.
  50          *
  51          * @return                      enumerator over signature_params_t*
  52          */
  53         enumerator_t *(*supported_signature_schemes)(private_key_t *this);
  54
  55         /**
  56          * Create a signature over a chunk of data.
  57          *
  58          * @param scheme        signature scheme to use
  59          * @param params        optional parameters required by the specified scheme
  60          * @param data          chunk of data to sign
  61          * @param signature     where to allocate created signature
  62          * @return                      TRUE if signature created
  63          */
  64         bool (*sign)(private_key_t *this, signature_scheme_t scheme, void *params,
  65                                  chunk_t data, chunk_t *signature);
  66         /**
  67          * Decrypt a chunk of data.
  68          *
  69          * @param scheme        expected encryption scheme used
  70          * @param crypto        chunk containing encrypted data
  71          * @param plain         where to allocate decrypted data
  72          * @return                      TRUE if data decrypted and plaintext allocated
  73          */
  74         bool (*decrypt)(private_key_t *this, encryption_scheme_t scheme,
  75                                         chunk_t crypto, chunk_t *plain);
  76
  77         /**
  78          * Get the strength of the key in bits.
  79          *
  80          * @return                      strength of the key in bits
  81          */
  82         int (*get_keysize) (private_key_t *this);
  83
  84         /**
  85          * Get the public part from the private key.
  86          *
  87          * @return                      public key
  88          */
  89         public_key_t* (*get_public_key)(private_key_t *this);
  90
  91         /**
  92          * Check if two private keys are equal.
  93          *
  94          * @param other         other private key
  95          * @return                      TRUE, if equality
  96          */
  97         bool (*equals) (private_key_t *this, private_key_t *other);
  98
  99         /**
 100          * Check if a private key belongs to a public key.
 101          *
 102          * @param public        public key
 103          * @return                      TRUE, if keys belong together
 104          */
 105         bool (*belongs_to) (private_key_t *this, public_key_t *public);
 106
 107         /**
 108          * Get the fingerprint of the key.
 109          *
 110          * @param type          type of fingerprint, one of KEYID_*
 111          * @param fp            fingerprint, points to internal data
 112          * @return                      TRUE if fingerprint type supported
 113          */
 114         bool (*get_fingerprint)(private_key_t *this, cred_encoding_type_t type,
 115                                                         chunk_t *fp);
 116
 117         /**
 118          * Check if a key has a given fingerprint of any kind.
 119          *
 120          * @param fp            fingerprint to check
 121          * @return                      TRUE if key has given fingerprint
 122          */
 123         bool (*has_fingerprint)(private_key_t *this, chunk_t fp);
 124
 125         /**
 126          * Get the key in an encoded form as a chunk.
 127          *
 128          * @param type          type of the encoding, one of PRIVKEY_*
 129          * @param encoding      encoding of the key, allocated
 130          * @return                      TRUE if encoding supported
 131          */
 132         bool (*get_encoding)(private_key_t *this, cred_encoding_type_t type,
 133                                                  chunk_t *encoding);
 134
 135         /**
 136          * Increase the refcount to this private key.
 137          *
 138          * @return                      this, with an increased refcount
 139          */
 140         private_key_t* (*get_ref)(private_key_t *this);
 141
 142         /**
 143          * Decrease refcount, destroy private_key if no more references.
 144          */
 145         void (*destroy)(private_key_t *this);
 146 };
 147
 148 /**
 149  * Generic private key equals() implementation, usable by implementers.
 150  *
 151  * @param private               private key to check
 152  * @param other                 key to compare
 153  * @return                              TRUE if this is equal to other
 154  */
 155 bool private_key_equals(private_key_t *private, private_key_t *other);
 156
 157 /**
 158  * Generic private key belongs_to() implementation, usable by implementers.
 159  *
 160  * @param private               private key to check
 161  * @param public                public key to compare
 162  * @return                              TRUE if this is equal to other
 163  */
 164 bool private_key_belongs_to(private_key_t *private, public_key_t *public);
 165
 166 /**
 167  * Generic private key has_fingerprint() implementation, usable by implementers.
 168  *
 169  * @param private               private key to check
 170  * @param fingerprint   fingerprint to check
 171  * @return                              TRUE if key has given fingerprint
 172  */
 173 bool private_key_has_fingerprint(private_key_t *private, chunk_t fingerprint);
 174
 175 #endif /** PRIVATE_KEY_H_ @}*/