- code documented
[strongswan.git] / Source / charon / transforms / 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 <transforms/rsa/rsa_public_key.h>
29 #include <transforms/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 * @TODO Implement proper key set/get load/save
40 * methods using ASN1.
41 *
42 * @b Constructors:
43 * - rsa_private_key_create()
44 *
45 * @see rsa_public_key_t
46 *
47 * @ingroup rsa
48 */
49 struct rsa_private_key_t {
50
51 /**
52 * @bief Build a signature over a chunk using EMSA-PKCS1 encoding.
53 *
54 * This signature creates a hash using the specified hash algorithm, concatenates
55 * it with an ASN1-OID of the hash algorithm and runs the RSASP1 function
56 * on it.
57 *
58 * @param this rsa_private_key to use
59 * @param hash_algorithm hash algorithm to use for hashing
60 * @param data data to sign
61 * @param[out] signature allocated signature
62 * @return
63 * - SUCCESS
64 * - INVALID_STATE, if key not set
65 * - NOT_SUPPORTED, if hash algorithm not supported
66 */
67 status_t (*build_emsa_pkcs1_signature) (rsa_private_key_t *this, hash_algorithm_t hash_algorithm, chunk_t data, chunk_t *signature);
68
69 /**
70 * @brief Set the key.
71 *
72 * Currently uses a proprietary format which is only inteded
73 * for testing. This should be replaced with a proper
74 * ASN1 encoded key format, when charon gets the ASN1
75 * capabilities.
76 *
77 * @param this calling object
78 * @param key key (in a propriarity format)
79 * @return currently SUCCESS in any case
80 */
81 status_t (*set_key) (rsa_private_key_t *this, chunk_t key);
82
83 /**
84 * @brief Gets the key.
85 *
86 * Currently uses a proprietary format which is only inteded
87 * for testing. This should be replaced with a proper
88 * ASN1 encoded key format, when charon gets the ASN1
89 * capabilities.
90 *
91 * @param this calling object
92 * @param key key (in a propriarity format)
93 * @return
94 * - SUCCESS
95 * - INVALID_STATE, if key not set
96 */
97 status_t (*get_key) (rsa_private_key_t *this, chunk_t *key);
98
99 /**
100 * @brief Loads a key from a file.
101 *
102 * Not implemented!
103 *
104 * @param this calling object
105 * @param file file from which key should be read
106 * @return NOT_SUPPORTED
107 */
108 status_t (*load_key) (rsa_private_key_t *this, char *file);
109
110 /**
111 * @brief Saves a key to a file.
112 *
113 * Not implemented!
114 *
115 * @param this calling object
116 * @param file file to which the key should be written.
117 * @return NOT_SUPPORTED
118 */
119 status_t (*save_key) (rsa_private_key_t *this, char *file);
120
121 /**
122 * @brief Generate a new key.
123 *
124 * Generates a new private_key with specified key size
125 *
126 * @param this calling object
127 * @param key_size size of the key in bits
128 * @return
129 * - SUCCESS
130 * - INVALID_ARG if key_size invalid
131 */
132 status_t (*generate_key) (rsa_private_key_t *this, size_t key_size);
133
134 /**
135 * @brief Create a rsa_public_key_t with the public
136 * parts of the key.
137 *
138 * @param this calling object
139 * @return public_key
140 */
141 rsa_public_key_t *(*get_public_key) (rsa_private_key_t *this);
142
143 /**
144 * @brief Destroys the private key.
145 *
146 * @param this private key to destroy
147 */
148 void (*destroy) (rsa_private_key_t *this);
149 };
150
151 /**
152 * @brief Create a new rsa_private_key without
153 * any key inside.
154 *
155 * @return created rsa_private_key_t.
156 *
157 * @ingroup rsa
158 */
159 rsa_private_key_t *rsa_private_key_create();
160
161 #endif /*RSA_PRIVATE_KEY_H_*/