Version bump to 5.8.4
[strongswan.git] / src / libstrongswan / credentials / keys / public_key.h
1 /*
2 * Copyright (C) 2015-2017 Tobias Brunner
3 * Copyright (C) 2014-2017 Andreas Steffen
4 * Copyright (C) 2007 Martin Willi
5 * HSR Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup public_key public_key
20 * @{ @ingroup keys
21 */
22
23 #ifndef PUBLIC_KEY_H_
24 #define PUBLIC_KEY_H_
25
26 typedef struct public_key_t public_key_t;
27 typedef enum key_type_t key_type_t;
28 typedef enum signature_scheme_t signature_scheme_t;
29 typedef enum encryption_scheme_t encryption_scheme_t;
30
31 #include <utils/identification.h>
32 #include <credentials/cred_encoding.h>
33
34 /**
35 * Type of a key pair, the used crypto system
36 */
37 enum key_type_t {
38 /** key type wildcard */
39 KEY_ANY = 0,
40 /** RSA crypto system as in PKCS#1 */
41 KEY_RSA = 1,
42 /** ECDSA as in ANSI X9.62 */
43 KEY_ECDSA = 2,
44 /** DSA */
45 KEY_DSA = 3,
46 /** Ed25519 PureEdDSA instance as in RFC 8032 */
47 KEY_ED25519 = 4,
48 /** Ed448 PureEdDSA instance as in RFC 8032 */
49 KEY_ED448 = 5,
50 /** BLISS */
51 KEY_BLISS = 6,
52 };
53
54 /**
55 * Enum names for key_type_t
56 */
57 extern enum_name_t *key_type_names;
58
59 /**
60 * Signature scheme for signature creation
61 *
62 * EMSA-PKCS1 signatures are defined in PKCS#1 standard.
63 * A prepended ASN.1 encoded digestInfo field contains the
64 * OID of the used hash algorithm.
65 */
66 enum signature_scheme_t {
67 /** Unknown signature scheme */
68 SIGN_UNKNOWN,
69 /** EMSA-PKCS1_v1.5 signature over digest without digestInfo */
70 SIGN_RSA_EMSA_PKCS1_NULL,
71 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and MD5 */
72 SIGN_RSA_EMSA_PKCS1_MD5,
73 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-1 */
74 SIGN_RSA_EMSA_PKCS1_SHA1,
75 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-2_224 */
76 SIGN_RSA_EMSA_PKCS1_SHA2_224,
77 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-2_256 */
78 SIGN_RSA_EMSA_PKCS1_SHA2_256,
79 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-2_384 */
80 SIGN_RSA_EMSA_PKCS1_SHA2_384,
81 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-2_512 */
82 SIGN_RSA_EMSA_PKCS1_SHA2_512,
83 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-3_224 */
84 SIGN_RSA_EMSA_PKCS1_SHA3_224,
85 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-3_256 */
86 SIGN_RSA_EMSA_PKCS1_SHA3_256,
87 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-3_384 */
88 SIGN_RSA_EMSA_PKCS1_SHA3_384,
89 /** EMSA-PKCS1_v1.5 signature as in PKCS#1 using RSA and SHA-3_512 */
90 SIGN_RSA_EMSA_PKCS1_SHA3_512,
91 /** EMSA-PSS signature as in PKCS#1 using RSA */
92 SIGN_RSA_EMSA_PSS,
93 /** ECDSA with SHA-1 using DER encoding as in RFC 3279 */
94 SIGN_ECDSA_WITH_SHA1_DER,
95 /** ECDSA with SHA-256 using DER encoding as in RFC 3279 */
96 SIGN_ECDSA_WITH_SHA256_DER,
97 /** ECDSA with SHA-384 using DER encoding as in RFC 3279 */
98 SIGN_ECDSA_WITH_SHA384_DER,
99 /** ECDSA with SHA-1 using DER encoding as in RFC 3279 */
100 SIGN_ECDSA_WITH_SHA512_DER,
101 /** ECDSA over precomputed digest, signature as in RFC 4754 */
102 SIGN_ECDSA_WITH_NULL,
103 /** ECDSA on the P-256 curve with SHA-256 as in RFC 4754 */
104 SIGN_ECDSA_256,
105 /** ECDSA on the P-384 curve with SHA-384 as in RFC 4754 */
106 SIGN_ECDSA_384,
107 /** ECDSA on the P-521 curve with SHA-512 as in RFC 4754 */
108 SIGN_ECDSA_521,
109 /** PureEdDSA on Curve25519 as in RFC 8410 */
110 SIGN_ED25519,
111 /** PureEdDSA on Curve448 as in RFC 8410 */
112 SIGN_ED448,
113 /** BLISS with SHA-2_256 */
114 SIGN_BLISS_WITH_SHA2_256,
115 /** BLISS with SHA-2_384 */
116 SIGN_BLISS_WITH_SHA2_384,
117 /** BLISS with SHA-2_512 */
118 SIGN_BLISS_WITH_SHA2_512,
119 /** BLISS with SHA-3_256 */
120 SIGN_BLISS_WITH_SHA3_256,
121 /** BLISS with SHA-3_384 */
122 SIGN_BLISS_WITH_SHA3_384,
123 /** BLISS with SHA-3_512 */
124 SIGN_BLISS_WITH_SHA3_512,
125 };
126
127 /**
128 * Enum names for signature_scheme_t
129 */
130 extern enum_name_t *signature_scheme_names;
131
132 /**
133 * Encryption scheme for public key data encryption.
134 */
135 enum encryption_scheme_t {
136 /** Unknown encryption scheme */
137 ENCRYPT_UNKNOWN,
138 /** RSAES-PKCS1-v1_5 as in PKCS#1 */
139 ENCRYPT_RSA_PKCS1,
140 /** RSAES-OAEP as in PKCS#1, using SHA1 as hash, no label */
141 ENCRYPT_RSA_OAEP_SHA1,
142 /** RSAES-OAEP as in PKCS#1, using SHA-224 as hash, no label */
143 ENCRYPT_RSA_OAEP_SHA224,
144 /** RSAES-OAEP as in PKCS#1, using SHA-256 as hash, no label */
145 ENCRYPT_RSA_OAEP_SHA256,
146 /** RSAES-OAEP as in PKCS#1, using SHA-384 as hash, no label */
147 ENCRYPT_RSA_OAEP_SHA384,
148 /** RSAES-OAEP as in PKCS#1, using SHA-512 as hash, no label */
149 ENCRYPT_RSA_OAEP_SHA512,
150 };
151
152 /**
153 * Enum names for encryption_scheme_t
154 */
155 extern enum_name_t *encryption_scheme_names;
156
157 /**
158 * Abstract interface of a public key.
159 */
160 struct public_key_t {
161
162 /**
163 * Get the key type.
164 *
165 * @return type of the key
166 */
167 key_type_t (*get_type)(public_key_t *this);
168
169 /**
170 * Verifies a signature against a chunk of data.
171 *
172 * @param scheme signature scheme to use for verification
173 * @param params optional parameters required by the specified scheme
174 * @param data data to check signature against
175 * @param signature signature to check
176 * @return TRUE if signature matches
177 */
178 bool (*verify)(public_key_t *this, signature_scheme_t scheme, void *params,
179 chunk_t data, chunk_t signature);
180
181 /**
182 * Encrypt a chunk of data.
183 *
184 * @param scheme encryption scheme to use
185 * @param plain chunk containing plaintext data
186 * @param crypto where to allocate encrypted data
187 * @return TRUE if data successfully encrypted
188 */
189 bool (*encrypt)(public_key_t *this, encryption_scheme_t scheme,
190 chunk_t plain, chunk_t *crypto);
191
192 /**
193 * Check if two public keys are equal.
194 *
195 * @param other other public key
196 * @return TRUE, if equality
197 */
198 bool (*equals)(public_key_t *this, public_key_t *other);
199
200 /**
201 * Get the strength of the key in bits.
202 *
203 * @return strength of the key in bits
204 */
205 int (*get_keysize) (public_key_t *this);
206
207 /**
208 * Get the fingerprint of the key.
209 *
210 * @param type type of fingerprint, one of KEYID_*
211 * @param fp fingerprint, points to internal data
212 * @return TRUE if fingerprint type supported
213 */
214 bool (*get_fingerprint)(public_key_t *this, cred_encoding_type_t type,
215 chunk_t *fp);
216
217 /**
218 * Check if a key has a given fingerprint of any kind.
219 *
220 * @param fp fingerprint to check
221 * @return TRUE if key has given fingerprint
222 */
223 bool (*has_fingerprint)(public_key_t *this, chunk_t fp);
224
225 /**
226 * Get the key in an encoded form as a chunk.
227 *
228 * @param type type of the encoding, one of PUBKEY_*
229 * @param encoding encoding of the key, allocated
230 * @return TRUE if encoding supported
231 */
232 bool (*get_encoding)(public_key_t *this, cred_encoding_type_t type,
233 chunk_t *encoding);
234
235 /**
236 * Increase the refcount of the key.
237 *
238 * @return this with an increased refcount
239 */
240 public_key_t* (*get_ref)(public_key_t *this);
241
242 /**
243 * Destroy a public_key instance.
244 */
245 void (*destroy)(public_key_t *this);
246 };
247
248 /**
249 * Generic public key equals() implementation, usable by implementers.
250 *
251 * @param public public key to check
252 * @param other key to compare
253 * @return TRUE if this is equal to other
254 */
255 bool public_key_equals(public_key_t *public, public_key_t *other);
256
257 /**
258 * Generic public key has_fingerprint() implementation, usable by implementers.
259 *
260 * @param public public key to check
261 * @param fingerprint fingerprint to check
262 * @return TRUE if key has given fingerprint
263 */
264 bool public_key_has_fingerprint(public_key_t *public, chunk_t fingerprint);
265
266 /**
267 * Conversion of ASN.1 signature or hash OID to signature scheme.
268 *
269 * @param oid ASN.1 OID
270 * @return signature scheme, SIGN_UNKNOWN if OID is unsupported
271 */
272 signature_scheme_t signature_scheme_from_oid(int oid);
273
274 /**
275 * Conversion of signature scheme to ASN.1 signature OID.
276 *
277 * @param scheme signature scheme
278 * @return ASN.1 OID, OID_UNKNOWN if not supported
279 */
280 int signature_scheme_to_oid(signature_scheme_t scheme);
281
282 /**
283 * Enumerate signature schemes that are appropriate for a key of the given type
284 * and size|strength ordered by increasing strength.
285 *
286 * @param type type of the key
287 * @param size size or strength of the key
288 * @return enumerator over signature_params_t* (by strength)
289 */
290 enumerator_t *signature_schemes_for_key(key_type_t type, int size);
291
292 /**
293 * Determine the type of key associated with a given signature scheme.
294 *
295 * @param scheme signature scheme
296 * @return key type (could be KEY_ANY)
297 */
298 key_type_t key_type_from_signature_scheme(signature_scheme_t scheme);
299
300
301 #endif /** PUBLIC_KEY_H_ @}*/