programs/charon/lib/crypto/rsa/rsa_private_key.h

   1 /**
   2  * @file rsa_private_key.h
   3  *
   4  * @brief Interface of rsa_private_key_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef RSA_PRIVATE_KEY_H_
  24 #define RSA_PRIVATE_KEY_H_
  25
  26 #include <types.h>
  27 #include <definitions.h>
  28 #include <crypto/rsa/rsa_public_key.h>
  29 #include <crypto/hashers/hasher.h>
  30
  31
  32 typedef struct rsa_private_key_t rsa_private_key_t;
  33
  34 /**
  35  * @brief RSA private key with associated functions.
  36  *
  37  * Currently only supports signing using EMSA encoding.
  38  *
  39  * @b Constructors:
  40  *  - rsa_private_key_create()
  41  *  - rsa_private_key_create_from_chunk()
  42  *  - rsa_private_key_create_from_file()
  43  *
  44  * @see rsa_public_key_t
  45  *
  46  * @todo Implement get_key(), save_key(), get_public_key()
  47  *
  48  * @ingroup rsa
  49  */
  50 struct rsa_private_key_t {
  51
  52         /**
  53          * @brief Build a signature over a chunk using EMSA-PKCS1 encoding.
  54          *
  55          * This signature creates a hash using the specified hash algorithm, concatenates
  56          * it with an ASN1-OID of the hash algorithm and runs the RSASP1 function
  57          * on it.
  58          *
  59          * @param this                          calling object
  60          * @param hash_algorithm        hash algorithm to use for hashing
  61          * @param data                          data to sign
  62          * @param[out] signature        allocated signature
  63          * @return
  64          *                                                      - SUCCESS
  65          *                                                      - INVALID_STATE, if key not set
  66          *                                                      - NOT_SUPPORTED, if hash algorithm not supported
  67          */
  68         status_t (*build_emsa_pkcs1_signature) (rsa_private_key_t *this, hash_algorithm_t hash_algorithm, chunk_t data, chunk_t *signature);
  69
  70         /**
  71          * @brief Gets the key.
  72          *
  73          * UNIMPLEMENTED!
  74          *
  75          * @param this                          calling object
  76          * @param key                           key (in a propriarity format)
  77          * @return
  78          *                                                      - SUCCESS
  79          *                                                      - INVALID_STATE, if key not set
  80          */
  81         status_t (*get_key) (rsa_private_key_t *this, chunk_t *key);
  82
  83         /**
  84          * @brief Saves a key to a file.
  85          *
  86          * Not implemented!
  87          *
  88          * @param this                          calling object
  89          * @param file                          file to which the key should be written.
  90          * @return                                      NOT_SUPPORTED
  91          */
  92         status_t (*save_key) (rsa_private_key_t *this, char *file);
  93
  94         /**
  95          * @brief Generate a new key.
  96          *
  97          * Generates a new private_key with specified key size
  98          *
  99          * @param this                          calling object
 100          * @param key_size                      size of the key in bits
 101          * @return
 102          *                                                      - SUCCESS
 103          *                                                      - INVALID_ARG if key_size invalid
 104          */
 105         status_t (*generate_key) (rsa_private_key_t *this, size_t key_size);
 106
 107         /**
 108          * @brief Create a rsa_public_key_t with the public
 109          * parts of the key.
 110          *
 111          * @param this                          calling object
 112          * @return                                      public_key
 113          */
 114         rsa_public_key_t *(*get_public_key) (rsa_private_key_t *this);
 115
 116         /**
 117          * @brief Check if a private key belongs to a public key.
 118          *
 119          * Compares the public part of the private key with the
 120          * public key, return TRUE if it equals.
 121          *
 122          * @param this                          private key
 123          * @param public                        public key
 124          * @return                                      TRUE, if keys belong together
 125          */
 126         bool (*belongs_to) (rsa_private_key_t *this, rsa_public_key_t *public);
 127
 128         /**
 129          * @brief Clone the private key.
 130          *
 131          * @param this                          private key to clone
 132          * @return                                      clone of this
 133          */
 134         rsa_private_key_t *(*clone) (rsa_private_key_t *this);
 135
 136         /**
 137          * @brief Destroys the private key.
 138          *
 139          * @param this                          private key to destroy
 140          */
 141         void (*destroy) (rsa_private_key_t *this);
 142 };
 143
 144 /**
 145  * @brief Generate a new RSA key with specified key lenght.
 146  *
 147  * @param key_size                      size of the key in bits
 148  * @return                                      generated rsa_private_key_t.
 149  *
 150  * @ingroup rsa
 151  */
 152 rsa_private_key_t *rsa_private_key_create(size_t key_size);
 153
 154 /**
 155  * @brief Load an RSA private key from a chunk.
 156  *
 157  * Load a key from a chunk, encoded as described in PKCS#1
 158  * (ASN1 DER encoded).
 159  *
 160  * @param chunk                         chunk containing the DER encoded key
 161  * @return                                      loaded rsa_private_key_t, or NULL
 162  *
 163  * @ingroup rsa
 164  */
 165 rsa_private_key_t *rsa_private_key_create_from_chunk(chunk_t chunk);
 166
 167 /**
 168  * @brief Load an RSA private key from a file.
 169  *
 170  * Load a key from a file, which is either in a unencrypted binary
 171  * format (DER), or in a (encrypted) PEM format. The supplied
 172  * passphrase is used to decrypt an ecrypted key.
 173  *
 174  * @param filename                      filename which holds the key
 175  * @param passphrase            optional passphase for decryption
 176  * @return                                      loaded rsa_private_key_t, or NULL
 177  *
 178  * @todo Implement PEM file loading
 179  * @todo Implement key decryption
 180  *
 181  * @ingroup rsa
 182  */
 183 rsa_private_key_t *rsa_private_key_create_from_file(char *filename, char *passphrase);
 184
 185 #endif /*RSA_PRIVATE_KEY_H_*/