Public/Private keys implement a has_fingerprint() method
[strongswan.git] / src / libstrongswan / credentials / keys / key_encoding.h
1 /*
2 * Copyright (C) 2009 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup key_encoding key_encoding
18 * @{ @ingroup keys
19 */
20
21 #ifndef KEY_ENCODING_H_
22 #define KEY_ENCODING_H_
23
24 typedef struct key_encoding_t key_encoding_t;
25 typedef enum key_encoding_type_t key_encoding_type_t;
26 typedef enum key_encoding_part_t key_encoding_part_t;
27
28 #include <library.h>
29
30 /**
31 * Key encoder function implementing encoding/fingerprinting.
32 *
33 * The variable argument list takes key_encoding_part_t, followed by part
34 * specific arguments, terminated by KEY_PART_END.
35 *
36 * @param type format to encode the key to
37 * @param args list of (key_encoding_part_t, data)
38 * @param encoding encoding result, allocated
39 * @return TRUE if encoding successful
40 */
41 typedef bool (*key_encoder_t)(key_encoding_type_t type, chunk_t *encoding,
42 va_list args);
43
44 /**
45 * Helper function for key_encoder_t implementations to parse argument list.
46 *
47 * Key encoder functions get a variable argument list to parse. To simplify
48 * the job, this function reads the arguments and returns chunks for each
49 * part.
50 * The argument list of this function takes a key_encoding_part_t, followed
51 * by a data pointer receiving the value, terminated by KEY_PART_END.
52 *
53 * @param args argument list passed to key encoder function
54 * @param ... list of (key_encoding_part_t, data*)
55 * @return TRUE if all parts found, FALSE otherwise
56 */
57 bool key_encoding_args(va_list args, ...);
58
59 /**
60 * Encoding type of a fingerprint/private-/public-key.
61 *
62 * Fingerprints have have the KEY_ID_*, public keys the KEY_PUB_* and
63 * private keys the KEY_PRIV_* prefix.
64 */
65 enum key_encoding_type_t {
66 /** SHA1 fingerprint over subjectPublicKeyInfo */
67 KEY_ID_PUBKEY_INFO_SHA1 = 0,
68 /** SHA1 fingerprint over subjectPublicKey */
69 KEY_ID_PUBKEY_SHA1,
70 /** PGPv3 fingerprint */
71 KEY_ID_PGPV3,
72 /** PGPv4 fingerprint */
73 KEY_ID_PGPV4,
74
75 KEY_ID_MAX,
76
77 /** PKCS#1 and similar ASN.1 key encoding */
78 KEY_PUB_ASN1_DER,
79 KEY_PRIV_ASN1_DER,
80 /** subjectPublicKeyInfo encoding */
81 KEY_PUB_SPKI_ASN1_DER,
82 /** PEM oncoded PKCS#1 key */
83 KEY_PUB_PEM,
84 KEY_PRIV_PEM,
85 /** PGP key encoding */
86 KEY_PUB_PGP,
87 KEY_PRIV_PGP,
88
89 KEY_ENCODING_MAX,
90 };
91
92 /**
93 * Parts of a key to encode.
94 */
95 enum key_encoding_part_t {
96 /** modulus of a RSA key, n */
97 KEY_PART_RSA_MODULUS,
98 /** public exponent of a RSA key, e */
99 KEY_PART_RSA_PUB_EXP,
100 /** private exponent of a RSA key, d */
101 KEY_PART_RSA_PRIV_EXP,
102 /** prime1 a RSA key, p */
103 KEY_PART_RSA_PRIME1,
104 /** prime2 a RSA key, q */
105 KEY_PART_RSA_PRIME2,
106 /** exponent1 a RSA key, exp1 */
107 KEY_PART_RSA_EXP1,
108 /** exponent1 a RSA key, exp2 */
109 KEY_PART_RSA_EXP2,
110 /** coefficient of RSA key, coeff */
111 KEY_PART_RSA_COEFF,
112 /** a DER encoded RSA public key */
113 KEY_PART_RSA_PUB_ASN1_DER,
114 /** a DER encoded RSA private key */
115 KEY_PART_RSA_PRIV_ASN1_DER,
116 /** a DER encoded ECDSA public key */
117 KEY_PART_ECDSA_PUB_ASN1_DER,
118 /** a DER encoded ECDSA private key */
119 KEY_PART_ECDSA_PRIV_ASN1_DER,
120
121 KEY_PART_END,
122 };
123
124 /**
125 * Private/Public key encoding and fingerprinting facility.
126 */
127 struct key_encoding_t {
128
129 /**
130 * Encode a key into a format using several key parts, optional caching.
131 *
132 * The variable argument list takes key_encoding_part_t, followed by part
133 * specific arguments, terminated by KEY_PART_END.
134 * If a cache key is given, the returned encoding points to internal data:
135 * do not free or modify. If no cache key is given, the encoding is
136 * allocated and must be freed by the caller.
137 *
138 * @param type format the key should be encoded to
139 * @param cache key to use for caching, NULL to not cache
140 * @param encoding encoding result, allocated if caching disabled
141 * @param ... list of (key_encoding_part_t, data)
142 * @return TRUE if encoding successful
143 */
144 bool (*encode)(key_encoding_t *this, key_encoding_type_t type, void *cache,
145 chunk_t *encoding, ...);
146
147 /**
148 * Clear all cached encodings of a given cache key.
149 *
150 * @param cache key used in encode() for caching
151 */
152 void (*clear_cache)(key_encoding_t *this, void *cache);
153
154 /**
155 * Check for a cached encoding.
156 *
157 * @param type format of the key encoding
158 * @param cache key to use for caching, as given to encode()
159 * @param encoding encoding result, internal data
160 * @return TRUE if cache entry found
161 */
162 bool (*get_cache)(key_encoding_t *this, key_encoding_type_t type,
163 void *cache, chunk_t *encoding);
164
165 /**
166 * Cache a key encoding created externally.
167 *
168 * After calling cache(), the passed encoding is owned by the key encoding
169 * facility.
170 *
171 * @param type format of the key encoding
172 * @param cache key to use for caching, as given to encode()
173 * @param encoding encoding to cache, gets owned by this
174 */
175 void (*cache)(key_encoding_t *this, key_encoding_type_t type, void *cache,
176 chunk_t encoding);
177
178 /**
179 * Register a key encoder function.
180 *
181 * @param encoder key encoder function to add
182 */
183 void (*add_encoder)(key_encoding_t *this, key_encoder_t encoder);
184
185 /**
186 * Unregister a previously registered key encoder function.
187 *
188 * @param encoder key encoder function to remove
189 */
190 void (*remove_encoder)(key_encoding_t *this, key_encoder_t encoder);
191
192 /**
193 * Destroy a key_encoding_t.
194 */
195 void (*destroy)(key_encoding_t *this);
196 };
197
198 /**
199 * Create a key_encoding instance.
200 */
201 key_encoding_t *key_encoding_create();
202
203 #endif /* KEY_ENCODING_ @}*/