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