2 * Copyright (C) 2009 Martin Willi
3 * Hochschule fuer Technik Rapperswil
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>.
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
17 * @defgroup key_encoding key_encoding
21 #ifndef KEY_ENCODING_H_
22 #define KEY_ENCODING_H_
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
;
31 * Key encoder function implementing encoding/fingerprinting.
33 * The variable argument list takes key_encoding_part_t, followed by part
34 * specific arguments, terminated by KEY_PART_END.
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
41 typedef bool (*key_encoder_t
)(key_encoding_type_t type
, chunk_t
*encoding
,
45 * Helper function for key_encoder_t implementations to parse argument list.
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
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.
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
57 bool key_encoding_args(va_list args
, ...);
60 * Encoding type of a fingerprint/private-/public-key.
62 * Fingerprints have have the KEY_ID_*, public keys the KEY_PUB_* and
63 * private keys the KEY_PRIV_* prefix.
65 enum key_encoding_type_t
{
66 /** SHA1 fingerprint over subjectPublicKeyInfo */
67 KEY_ID_PUBKEY_INFO_SHA1
= 0,
68 /** SHA1 fingerprint over subjectPublicKey */
70 /** PGPv3 fingerprint */
72 /** PGPv4 fingerprint */
75 /** PKCS#1 and similar ASN.1 key encoding */
78 /** subjectPublicKeyInfo encoding */
79 KEY_PUB_SPKI_ASN1_DER
,
80 /** PEM oncoded PKCS#1 key */
83 /** PGP key encoding */
91 * Parts of a key to encode.
93 enum key_encoding_part_t
{
94 /** modulus of a RSA key, n */
96 /** public exponent of a RSA key, e */
98 /** private exponent of a RSA key, d */
99 KEY_PART_RSA_PRIV_EXP
,
100 /** prime1 a RSA key, p */
102 /** prime2 a RSA key, q */
104 /** exponent1 a RSA key, exp1 */
106 /** exponent1 a RSA key, exp2 */
108 /** coefficient of RSA key, coeff */
110 /** a DER encoded RSA public key */
111 KEY_PART_RSA_PUB_ASN1_DER
,
112 /** a DER encoded RSA private key */
113 KEY_PART_RSA_PRIV_ASN1_DER
,
114 /** a DER encoded ECDSA public key */
115 KEY_PART_ECDSA_PUB_ASN1_DER
,
116 /** a DER encoded ECDSA private key */
117 KEY_PART_ECDSA_PRIV_ASN1_DER
,
123 * Private/Public key encoding and fingerprinting facility.
125 struct key_encoding_t
{
128 * Encode a key into a format using several key parts, optional caching.
130 * The variable argument list takes key_encoding_part_t, followed by part
131 * specific arguments, terminated by KEY_PART_END.
132 * If a cache key is given, the returned encoding points to internal data:
133 * do not free or modify. If no cache key is given, the encoding is
134 * allocated and must be freed by the caller.
136 * @param type format the key should be encoded to
137 * @param cache key to use for caching, NULL to not cache
138 * @param encoding encoding result, allocated if caching disabled
139 * @param ... list of (key_encoding_part_t, data)
140 * @return TRUE if encoding successful
142 bool (*encode
)(key_encoding_t
*this, key_encoding_type_t type
, void *cache
,
143 chunk_t
*encoding
, ...);
146 * Clear all cached encodings of a given cache key.
148 * @param cache key used in encode() for caching
150 void (*clear_cache
)(key_encoding_t
*this, void *cache
);
153 * Check for a cached encoding.
155 * @param type format of the key encoding
156 * @param cache key to use for caching, as given to encode()
157 * @param encoding encoding result, internal data
158 * @return TRUE if cache entry found
160 bool (*get_cache
)(key_encoding_t
*this, key_encoding_type_t type
,
161 void *cache
, chunk_t
*encoding
);
164 * Cache a key encoding created externally.
166 * After calling cache(), the passed encoding is owned by the key encoding
169 * @param type format of the key encoding
170 * @param cache key to use for caching, as given to encode()
171 * @param encoding encoding to cache, gets owned by this
173 void (*cache
)(key_encoding_t
*this, key_encoding_type_t type
, void *cache
,
177 * Register a key encoder function.
179 * @param encoder key encoder function to add
181 void (*add_encoder
)(key_encoding_t
*this, key_encoder_t encoder
);
184 * Unregister a previously registered key encoder function.
186 * @param encoder key encoder function to remove
188 void (*remove_encoder
)(key_encoding_t
*this, key_encoder_t encoder
);
191 * Destroy a key_encoding_t.
193 void (*destroy
)(key_encoding_t
*this);
197 * Create a key_encoding instance.
199 key_encoding_t
*key_encoding_create();
201 #endif /* KEY_ENCODING_ @}*/