Version bump to 5.9.0
[strongswan.git] / src / libstrongswan / credentials / keys / private_key.h
index fbb5abf..079c779 100644 (file)
@@ -1,6 +1,7 @@
 /*
+ * Copyright (C) 2017 Tobias Brunner
  * Copyright (C) 2007 Martin Willi
- * Hochschule fuer Technik Rapperswil
+ * HSR Hochschule fuer Technik Rapperswil
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * for more details.
- *
- * $Id$
  */
+
 /**
  * @defgroup private_key private_key
  * @{ @ingroup keys
@@ -25,7 +24,7 @@
 
 typedef struct private_key_t private_key_t;
 
-#include <utils/identification.h>
+#include <credentials/cred_encoding.h>
 #include <credentials/keys/public_key.h>
 
 /**
@@ -41,103 +40,136 @@ struct private_key_t {
        key_type_t (*get_type)(private_key_t *this);
 
        /**
+        * Get signature schemes supported by this key.
+        *
+        * This is useful for keys that only support certain hash algorithms or
+        * require specific parameters for RSA/PSS signatures.
+        *
+        * @note Implementing this method is optional. If multiple schemes are
+        * returned, they should be ordered by decreasing preference.
+        *
+        * @return                      enumerator over signature_params_t*
+        */
+       enumerator_t *(*supported_signature_schemes)(private_key_t *this);
+
+       /**
         * Create a signature over a chunk of data.
         *
         * @param scheme        signature scheme to use
+        * @param params        optional parameters required by the specified scheme
         * @param data          chunk of data to sign
         * @param signature     where to allocate created signature
         * @return                      TRUE if signature created
         */
-       bool (*sign)(private_key_t *this, signature_scheme_t scheme, 
+       bool (*sign)(private_key_t *this, signature_scheme_t scheme, void *params,
                                 chunk_t data, chunk_t *signature);
        /**
         * Decrypt a chunk of data.
         *
+        * @param scheme        expected encryption scheme used
         * @param crypto        chunk containing encrypted data
         * @param plain         where to allocate decrypted data
         * @return                      TRUE if data decrypted and plaintext allocated
         */
-       bool (*decrypt)(private_key_t *this, chunk_t crypto, chunk_t *plain);
-       
-       /**
-        * Get the strength of the key in bytes.
-        * 
-        * @return                      strength of the key in bytes
-        */
-       size_t (*get_keysize) (private_key_t *this);
+       bool (*decrypt)(private_key_t *this, encryption_scheme_t scheme,
+                                       chunk_t crypto, chunk_t *plain);
 
        /**
-        * Get a unique key identifier, such as a hash over the public key.
-        * 
-        * @param type          type of the key ID to get
-        * @return                      unique ID of the key as identification_t, or NULL
+        * Get the strength of the key in bits.
+        *
+        * @return                      strength of the key in bits
         */
-       identification_t* (*get_id) (private_key_t *this, id_type_t type);
-       
+       int (*get_keysize) (private_key_t *this);
+
        /**
         * Get the public part from the private key.
         *
         * @return                      public key
         */
        public_key_t* (*get_public_key)(private_key_t *this);
-       
+
+       /**
+        * Check if two private keys are equal.
+        *
+        * @param other         other private key
+        * @return                      TRUE, if equality
+        */
+       bool (*equals) (private_key_t *this, private_key_t *other);
+
        /**
         * Check if a private key belongs to a public key.
-        * 
+        *
         * @param public        public key
         * @return                      TRUE, if keys belong together
         */
        bool (*belongs_to) (private_key_t *this, public_key_t *public);
-       
+
+       /**
+        * Get the fingerprint of the key.
+        *
+        * @param type          type of fingerprint, one of KEYID_*
+        * @param fp            fingerprint, points to internal data
+        * @return                      TRUE if fingerprint type supported
+        */
+       bool (*get_fingerprint)(private_key_t *this, cred_encoding_type_t type,
+                                                       chunk_t *fp);
+
        /**
-        * Get an encoded form of the private key.
+        * Check if a key has a given fingerprint of any kind.
         *
-        * @todo Do we need a encoding type specification?
+        * @param fp            fingerprint to check
+        * @return                      TRUE if key has given fingerprint
+        */
+       bool (*has_fingerprint)(private_key_t *this, chunk_t fp);
+
+       /**
+        * Get the key in an encoded form as a chunk.
         *
-        * @return                      allocated chunk containing encoded private key
+        * @param type          type of the encoding, one of PRIVKEY_*
+        * @param encoding      encoding of the key, allocated
+        * @return                      TRUE if encoding supported
         */
-       chunk_t (*get_encoding)(private_key_t *this);   
-       
+       bool (*get_encoding)(private_key_t *this, cred_encoding_type_t type,
+                                                chunk_t *encoding);
+
        /**
         * Increase the refcount to this private key.
         *
         * @return                      this, with an increased refcount
         */
        private_key_t* (*get_ref)(private_key_t *this);
-               
+
        /**
-     * Decrease refcount, destroy private_key if no more references.
-     */
-    void (*destroy)(private_key_t *this);
+        * Decrease refcount, destroy private_key if no more references.
+        */
+       void (*destroy)(private_key_t *this);
 };
 
 /**
- * Read a private key from a file.
- * 
- * @param type                 type of the key
- * @param filename             filename to read key from
- * @param passphrase   passphrase to decrypt an encrypted key
- * @return                             loaded private key, NULL if failed
+ * Generic private key equals() implementation, usable by implementers.
+ *
+ * @param private              private key to check
+ * @param other                        key to compare
+ * @return                             TRUE if this is equal to other
  */
-private_key_t *private_key_create_from_file(key_type_t type, char *filename,
-                                                                                   chunk_t passphrase);
+bool private_key_equals(private_key_t *private, private_key_t *other);
 
 /**
- * Create a private key from a chunk.
- * 
- * @param type                 type of the key
- * @param chunk                        chunk to create key from
- * @return                             loaded private key, NULL if failed
+ * Generic private key belongs_to() implementation, usable by implementers.
+ *
+ * @param private              private key to check
+ * @param public               public key to compare
+ * @return                             TRUE if this is equal to other
  */
-private_key_t *private_key_create_from_chunk(key_type_t type, chunk_t chunk);
+bool private_key_belongs_to(private_key_t *private, public_key_t *public);
 
 /**
- * Generate a new private key.
- * 
- * @param type                 type of the key
- * @param size                 key size in bytes
- * @return                             generated private key, NULL if failed
+ * Generic private key has_fingerprint() implementation, usable by implementers.
+ *
+ * @param private              private key to check
+ * @param fingerprint  fingerprint to check
+ * @return                             TRUE if key has given fingerprint
  */
-private_key_t *private_key_create_generated(key_type_t type, size_t size);
+bool private_key_has_fingerprint(private_key_t *private, chunk_t fingerprint);
 
-#endif /* PRIVATE_KEY_H_ @} */
+#endif /** PRIVATE_KEY_H_ @}*/