src/libstrongswan/credentials/keys/private_key.h

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