src/libstrongswan/credentials/cred_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 cred_encoding cred_encoding
  18  * @{ @ingroup credentials
  19  */
  20
  21 #ifndef CRED_ENCODING_H_
  22 #define CRED_ENCODING_H_
  23
  24 typedef struct cred_encoding_t cred_encoding_t;
  25 typedef enum cred_encoding_type_t cred_encoding_type_t;
  26 typedef enum cred_encoding_part_t cred_encoding_part_t;
  27
  28 #include <library.h>
  29
  30 /**
  31  * Credential encoder function implementing encoding/fingerprinting.
  32  *
  33  * The variable argument list takes cred_encoding_part_t, followed by part
  34  * specific arguments, terminated by KEY_PART_END.
  35  *
  36  * @param type          format to encode the credential to
  37  * @param args          list of (cred_encoding_part_t, data)
  38  * @param encoding      encoding result, allocated
  39  * @return                      TRUE if encoding successful
  40  */
  41 typedef bool (*cred_encoder_t)(cred_encoding_type_t type, chunk_t *encoding,
  42                                                            va_list args);
  43
  44 /**
  45  * Helper function for cred_encoder_t implementations to parse argument list.
  46  *
  47  * Credential encoder functions get a variable argument list to parse. To
  48  * simplify the job, this function reads the arguments and returns chunks for
  49  * each part.
  50  * The argument list of this function takes a cred_encoding_part_t, followed
  51  * by a data pointer receiving the value, terminated by CRED_PART_END.
  52  *
  53  * @param args          argument list passed to credential encoder function
  54  * @param ...           list of (cred_encoding_part_t, data*)
  55  * @return                      TRUE if all parts found, FALSE otherwise
  56  */
  57 bool cred_encoding_args(va_list args, ...);
  58
  59 /**
  60  * Encoding type of a fingerprint/credential.
  61  *
  62  * Fingerprints have the KEYID_*, public keys the PUBKEY_* and
  63  * private keys the PRIVKEY_* prefix.
  64  */
  65 enum cred_encoding_type_t {
  66         /** SHA1 fingerprint over subjectPublicKeyInfo */
  67         KEYID_PUBKEY_INFO_SHA1 = 0,
  68         /** SHA1 fingerprint over subjectPublicKey */
  69         KEYID_PUBKEY_SHA1,
  70         /** PGPv3 fingerprint */
  71         KEYID_PGPV3,
  72         /** PGPv4 fingerprint */
  73         KEYID_PGPV4,
  74
  75         KEYID_MAX,
  76
  77         /** PKCS#1 and similar ASN.1 key encoding */
  78         PUBKEY_ASN1_DER,
  79         PRIVKEY_ASN1_DER,
  80         /** subjectPublicKeyInfo encoding */
  81         PUBKEY_SPKI_ASN1_DER,
  82         /** PEM encoded PKCS#1 key */
  83         PUBKEY_PEM,
  84         PRIVKEY_PEM,
  85         /** PGP key encoding */
  86         PUBKEY_PGP,
  87         PRIVKEY_PGP,
  88
  89         /** ASN.1 DER encoded certificate */
  90         CERT_ASN1_DER,
  91         /** PEM encoded certificate */
  92         CERT_PEM,
  93         /** PGP Packet encoded certificate */
  94         CERT_PGP_PKT,
  95
  96         CRED_ENCODING_MAX,
  97 };
  98
  99 /**
 100  * Parts of a credential to encode.
 101  */
 102 enum cred_encoding_part_t {
 103         /** modulus of a RSA key, n */
 104         CRED_PART_RSA_MODULUS,
 105         /** public exponent of a RSA key, e */
 106         CRED_PART_RSA_PUB_EXP,
 107         /** private exponent of a RSA key, d */
 108         CRED_PART_RSA_PRIV_EXP,
 109         /** prime1 a RSA key, p */
 110         CRED_PART_RSA_PRIME1,
 111         /** prime2 a RSA key, q */
 112         CRED_PART_RSA_PRIME2,
 113         /** exponent1 a RSA key, exp1 */
 114         CRED_PART_RSA_EXP1,
 115         /** exponent1 a RSA key, exp2 */
 116         CRED_PART_RSA_EXP2,
 117         /** coefficient of RSA key, coeff */
 118         CRED_PART_RSA_COEFF,
 119         /** a DER encoded RSA public key */
 120         CRED_PART_RSA_PUB_ASN1_DER,
 121         /** a DER encoded RSA private key */
 122         CRED_PART_RSA_PRIV_ASN1_DER,
 123         /** a DER encoded ECDSA public key */
 124         CRED_PART_ECDSA_PUB_ASN1_DER,
 125         /** a DER encoded ECDSA private key */
 126         CRED_PART_ECDSA_PRIV_ASN1_DER,
 127         /** a DER encoded X509 certificate */
 128         CRED_PART_X509_ASN1_DER,
 129         /** a DER encoded X509 CRL */
 130         CRED_PART_X509_CRL_ASN1_DER,
 131         /** a DER encoded X509 OCSP request */
 132         CRED_PART_X509_OCSP_REQ_ASN1_DER,
 133         /** a DER encoded X509 OCSP response */
 134         CRED_PART_X509_OCSP_RES_ASN1_DER,
 135         /** a DER encoded X509 attribute certificate */
 136         CRED_PART_X509_AC_ASN1_DER,
 137         /** a DER encoded PKCS10 certificate request */
 138         CRED_PART_PKCS10_ASN1_DER,
 139         /** a PGP encoded certificate */
 140         CRED_PART_PGP_CERT,
 141
 142         CRED_PART_END,
 143 };
 144
 145 /**
 146  * Credential encoding and fingerprinting facility.
 147  */
 148 struct cred_encoding_t {
 149
 150         /**
 151          * Encode a credential in a format using several parts, optional caching.
 152          *
 153          * The variable argument list takes cred_encoding_part_t, followed by part
 154          * specific arguments, terminated by CRED_PART_END.
 155          * If a cache key is given, the returned encoding points to internal data:
 156          * do not free or modify. If no cache key is given, the encoding is
 157          * allocated and must be freed by the caller.
 158          *
 159          * @param type                  format the credential should be encoded to
 160          * @param cache                 key to use for caching, NULL to not cache
 161          * @param encoding              encoding result, allocated if caching disabled
 162          * @param ...                   list of (cred_encoding_part_t, data)
 163          * @return                              TRUE if encoding successful
 164          */
 165         bool (*encode)(cred_encoding_t *this, cred_encoding_type_t type, void *cache,
 166                                    chunk_t *encoding, ...);
 167
 168         /**
 169          * Clear all cached encodings of a given cache key.
 170          *
 171          * @param cache                 key used in encode() for caching
 172          */
 173         void (*clear_cache)(cred_encoding_t *this, void *cache);
 174
 175         /**
 176          * Check for a cached encoding.
 177          *
 178          * @param type                  format of the credential encoding
 179          * @param cache                 key to use for caching, as given to encode()
 180          * @param encoding              encoding result, internal data
 181          * @return                              TRUE if cache entry found
 182          */
 183         bool (*get_cache)(cred_encoding_t *this, cred_encoding_type_t type,
 184                                           void *cache, chunk_t *encoding);
 185
 186         /**
 187          * Cache a credential encoding created externally.
 188          *
 189          * After calling cache(), the passed encoding is owned by the cred encoding
 190          * facility.
 191          *
 192          * @param type                  format of the credential encoding
 193          * @param cache                 key to use for caching, as given to encode()
 194          * @param encoding              encoding to cache, gets owned by this
 195          */
 196         void (*cache)(cred_encoding_t *this, cred_encoding_type_t type, void *cache,
 197                                   chunk_t encoding);
 198
 199         /**
 200          * Register a credential encoder function.
 201          *
 202          * @param encoder               credential encoder function to add
 203          */
 204         void (*add_encoder)(cred_encoding_t *this, cred_encoder_t encoder);
 205
 206         /**
 207          * Unregister a previously registered credential encoder function.
 208          *
 209          * @param encoder               credential encoder function to remove
 210          */
 211         void (*remove_encoder)(cred_encoding_t *this, cred_encoder_t encoder);
 212
 213         /**
 214          * Destroy a cred_encoding_t.
 215          */
 216         void (*destroy)(cred_encoding_t *this);
 217 };
 218
 219 /**
 220  * Create a cred_encoding instance.
 221  */
 222 cred_encoding_t *cred_encoding_create();
 223
 224 #endif /** CRED_ENCODING_H_ @}*/