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         /** PKCS#1 and similar ASN.1 key encoding */
  76         KEY_PUB_ASN1_DER,
  77         KEY_PRIV_ASN1_DER,
  78         /** subjectPublicKeyInfo encoding */
  79         KEY_PUB_SPKI_ASN1_DER,
  80         /** PEM oncoded PKCS#1 key */
  81         KEY_PUB_PEM,
  82         KEY_PRIV_PEM,
  83         /** PGP key encoding */
  84         KEY_PUB_PGP,
  85         KEY_PRIV_PGP,
  86
  87         KEY_ENCODING_MAX,
  88 };
  89
  90 /**
  91  * Parts of a key to encode.
  92  */
  93 enum key_encoding_part_t {
  94         /** modulus of a RSA key, n */
  95         KEY_PART_RSA_MODULUS,
  96         /** public exponent of a RSA key, e */
  97         KEY_PART_RSA_PUB_EXP,
  98         /** private exponent of a RSA key, d */
  99         KEY_PART_RSA_PRIV_EXP,
 100         /** prime1 a RSA key, p */
 101         KEY_PART_RSA_PRIME1,
 102         /** prime2 a RSA key, q */
 103         KEY_PART_RSA_PRIME2,
 104         /** exponent1 a RSA key, exp1 */
 105         KEY_PART_RSA_EXP1,
 106         /** exponent1 a RSA key, exp2 */
 107         KEY_PART_RSA_EXP2,
 108         /** coefficient of RSA key, coeff */
 109         KEY_PART_RSA_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,
 118
 119         KEY_PART_END,
 120 };
 121
 122 /**
 123  * Private/Public key encoding and fingerprinting facility.
 124  */
 125 struct key_encoding_t {
 126
 127         /**
 128          * Encode a key into a format using several key parts, optional caching.
 129          *
 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.
 135          *
 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
 141          */
 142         bool (*encode)(key_encoding_t *this, key_encoding_type_t type, void *cache,
 143                                    chunk_t *encoding, ...);
 144
 145         /**
 146          * Clear all cached encodings of a given cache key.
 147          *
 148          * @param cache                 key used in encode() for caching
 149          */
 150         void (*clear_cache)(key_encoding_t *this, void *cache);
 151
 152         /**
 153          * Check for a cached encoding.
 154          *
 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
 159          */
 160         bool (*get_cache)(key_encoding_t *this, key_encoding_type_t type,
 161                                           void *cache, chunk_t *encoding);
 162
 163         /**
 164          * Cache a key encoding created externally.
 165          *
 166          * After calling cache(), the passed encoding is owned by the key encoding
 167          * facility.
 168          *
 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
 172          */
 173         void (*cache)(key_encoding_t *this, key_encoding_type_t type, void *cache,
 174                                   chunk_t encoding);
 175
 176         /**
 177          * Register a key encoder function.
 178          *
 179          * @param encoder               key encoder function to add
 180          */
 181         void (*add_encoder)(key_encoding_t *this, key_encoder_t encoder);
 182
 183         /**
 184          * Unregister a previously registered key encoder function.
 185          *
 186          * @param encoder               key encoder function to remove
 187          */
 188         void (*remove_encoder)(key_encoding_t *this, key_encoder_t encoder);
 189
 190         /**
 191          * Destroy a key_encoding_t.
 192          */
 193         void (*destroy)(key_encoding_t *this);
 194 };
 195
 196 /**
 197  * Create a key_encoding instance.
 198  */
 199 key_encoding_t *key_encoding_create();
 200
 201 #endif /* KEY_ENCODING_ @}*/