- comments added
[strongswan.git] / Source / charon / transforms / rsa / rsa_private_key.h
1 /**
2 * @file rsa_private_key.h
3 *
4 * @brief Interface 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
29 #include <transforms/rsa/rsa_public_key.h>
30 #include <transforms/hashers/hasher.h>
31
32
33 typedef struct rsa_private_key_t rsa_private_key_t;
34
35 /**
36 * @brief RSA private key with associated functions.
37 *
38 * Currently only supports signing using EMSA encoding.
39 *
40 * @todo Implement proper key set/get load/save
41 * methods using ASN1.
42 *
43 * @b Constructors:
44 * - rsa_private_key_create()
45 *
46 * @see rsa_public_key_t
47 *
48 * @ingroup rsa
49 */
50 struct rsa_private_key_t {
51
52 /**
53 * @bief Build a signature over a chunk using EMSA-PKCS1 encoding.
54 *
55 * This signature creates a hash using the specied 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 rsa_private_key to use
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 Set the key.
72 *
73 * Currently uses a proprietary format which is only inteded
74 * for testing. This should be replaced with a proper
75 * ASN1 encoded key format, when charon gets the ASN1
76 * capabilities.
77 *
78 * @param this calling object
79 * @param key key (in a propriarity format)
80 * @return currently SUCCESS in any case
81 */
82 status_t (*set_key) (rsa_private_key_t *this, chunk_t key);
83
84 /**
85 * @brief Gets the key.
86 *
87 * Currently uses a proprietary format which is only inteded
88 * for testing. This should be replaced with a proper
89 * ASN1 encoded key format, when charon gets the ASN1
90 * capabilities.
91 *
92 * @param this calling object
93 * @param key key (in a propriarity format)
94 * @return
95 * - SUCCESS
96 * - INVALID_STATE, if key not set
97 */
98 status_t (*get_key) (rsa_private_key_t *this, chunk_t *key);
99
100 /**
101 * @brief Loads a key from a file.
102 *
103 * Not implemented!
104 *
105 * @param this calling object
106 * @param file file from which key should be read
107 * @return NOT_SUPPORTED
108 */
109 status_t (*load_key) (rsa_private_key_t *this, char *file);
110
111 /**
112 * @brief Saves a key to a file.
113 *
114 * Not implemented!
115 *
116 * @param this calling object
117 * @param file file to which the key should be written.
118 * @return NOT_SUPPORTED
119 */
120 status_t (*save_key) (rsa_private_key_t *this, char *file);
121
122 /**
123 * @brief Generate a new key.
124 *
125 * Generates a new private_key with specified key size
126 *
127 * @param this calling object
128 * @param key_size size of the key in bits
129 * @return
130 * - SUCCESS
131 * - INVALID_ARG if key_size invalid
132 */
133 status_t (*generate_key) (rsa_private_key_t *this, size_t key_size);
134
135 /**
136 * @brief Create a rsa_public_key_t with the public
137 * parts of the key.
138 *
139 * @param this calling object
140 * @return public_key
141 */
142 rsa_public_key_t *(*get_public_key) (rsa_private_key_t *this);
143
144 /**
145 * @brief Destroys the private key.
146 *
147 * @param this private key to destroy
148 */
149 void (*destroy) (rsa_private_key_t *this);
150 };
151
152 /**
153 * @brief Create a new rsa_private_key without
154 * any key inside.
155 *
156 * @return created rsa_private_key_t.
157 *
158 * @ingroup rsa
159 */
160 rsa_private_key_t *rsa_private_key_create();
161
162 #endif /*RSA_PRIVATE_KEY_H_*/