some cleanups here and there
[strongswan.git] / src / libstrongswan / crypto / rsa / rsa_public_key.h
1 /**
2 * @file rsa_public_key.h
3 *
4 * @brief Interface of rsa_public_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
24 #ifndef RSA_PUBLIC_KEY_H_
25 #define RSA_PUBLIC_KEY_H_
26
27 #include <gmp.h>
28
29 #include <types.h>
30 #include <definitions.h>
31
32
33 typedef struct rsa_public_key_t rsa_public_key_t;
34
35 /**
36 * @brief RSA public key with associated functions.
37 *
38 * Currently only supports signature verification using
39 * the EMSA encoding (see PKCS1)
40 *
41 * @b Constructors:
42 * - rsa_public_key_create_from_chunk()
43 * - rsa_public_key_create_from_file()
44 * - rsa_private_key_t.get_public_key()
45 *
46 * @see rsa_private_key_t
47 *
48 * @todo Implement getkey() and savekey()
49 *
50 * @ingroup rsa
51 */
52 struct rsa_public_key_t {
53
54 /**
55 * @brief Verify a EMSA-PKCS1 encodined signature.
56 *
57 * Processes the supplied signature with the RSAVP1 function,
58 * selects the hash algorithm form the resultign ASN1-OID and
59 * verifies the hash against the supplied data.
60 *
61 * @param this rsa_public_key to use
62 * @param data data to sign
63 * @param signature signature to verify
64 * @return
65 * - SUCCESS, if signature ok
66 * - INVALID_STATE, if key not set
67 * - NOT_SUPPORTED, if hash algorithm not supported
68 * - INVALID_ARG, if signature is not a signature
69 * - FAILED if signature invalid or unable to verify
70 */
71 status_t (*verify_emsa_pkcs1_signature) (const rsa_public_key_t *this, chunk_t data, chunk_t signature);
72
73 /**
74 * @brief Gets the key.
75 *
76 * Currently uses a proprietary format which is only inteded
77 * for testing. This should be replaced with a proper
78 * ASN1 encoded key format, when charon gets the ASN1
79 * capabilities.
80 *
81 * @param this calling object
82 * @param key key (in a propriarity format)
83 * @return
84 * - SUCCESS
85 * - INVALID_STATE, if key not set
86 */
87 status_t (*get_key) (const rsa_public_key_t *this, chunk_t *key);
88
89 /**
90 * @brief Saves a key to a file.
91 *
92 * Not implemented!
93 *
94 * @param this calling object
95 * @param file file to which the key should be written.
96 * @return NOT_SUPPORTED
97 */
98 status_t (*save_key) (const rsa_public_key_t *this, char *file);
99
100 /**
101 * @brief Get the modulus of the key.
102 *
103 * @param this calling object
104 * @return modulus (n) of the key
105 */
106 mpz_t *(*get_modulus) (const rsa_public_key_t *this);
107
108 /**
109 * @brief Get the size of the modulus in bytes.
110 *
111 * @param this calling object
112 * @return size of the modulus (n) in bytes
113 */
114 size_t (*get_keysize) (const rsa_public_key_t *this);
115
116 /**
117 * @brief Get the keyid formed as the SHA-1 hash of a publicKeyInfo object.
118 *
119 * @param this calling object
120 * @return keyid in the form of a SHA-1 hash
121 */
122 chunk_t (*get_keyid) (const rsa_public_key_t *this);
123
124 /**
125 * @brief Clone the public key.
126 *
127 * @param this public key to clone
128 * @return clone of this
129 */
130 rsa_public_key_t *(*clone) (const rsa_public_key_t *this);
131
132 /**
133 * @brief Destroys the public key.
134 *
135 * @param this public key to destroy
136 */
137 void (*destroy) (rsa_public_key_t *this);
138 };
139
140 /**
141 * @brief Load an RSA public key from a chunk.
142 *
143 * Load a key from a chunk, encoded in the more frequently
144 * used publicKeyInfo object (ASN1 DER encoded).
145 *
146 * @param chunk chunk containing the DER encoded key
147 * @return loaded rsa_public_key_t, or NULL
148 *
149 * @ingroup rsa
150 */
151 rsa_public_key_t *rsa_public_key_create_from_chunk(chunk_t chunk);
152
153 /**
154 * @brief Load an RSA public key from a file.
155 *
156 * Load a key from a file, which is either in binary
157 * format (DER), or in PEM format.
158 *
159 * @param filename filename which holds the key
160 * @return loaded rsa_public_key_t, or NULL
161 *
162 * @ingroup rsa
163 */
164 rsa_public_key_t *rsa_public_key_create_from_file(char *filename);
165
166 #endif /*RSA_PUBLIC_KEY_H_*/