src/libstrongswan/credential_store.h

   1 /**
   2  * @file credential_store.h
   3  *
   4  * @brief Interface credential_store_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005-2006 Martin Willi
  10  * Copyright (C) 2005 Jan Hutter
  11  * Hochschule fuer Technik Rapperswil
  12  *
  13  * This program is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by the
  15  * Free Software Foundation; either version 2 of the License, or (at your
  16  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21  * for more details.
  22  */
  23
  24 #ifndef CREDENTIAL_STORE_H_
  25 #define CREDENTIAL_STORE_H_
  26
  27 typedef struct credential_store_t credential_store_t;
  28
  29 #include <library.h>
  30 #include <crypto/x509.h>
  31 #include <crypto/ca.h>
  32 #include <crypto/rsa/rsa_private_key.h>
  33 #include <crypto/rsa/rsa_public_key.h>
  34 #include <utils/identification.h>
  35
  36
  37 /**
  38  * @brief The interface for a credential_store backend.
  39  *
  40  * @b Constructors:
  41  *  - stroke_create()
  42  *
  43  * @ingroup config
  44  */
  45 struct credential_store_t {
  46
  47         /**
  48          * @brief Returns the secret shared by two specific IDs.
  49          *
  50          * The returned chunk must be destroyed by the caller after usage.
  51          *
  52          * @param this                                  calling object
  53          * @param my_id                                 my ID identifiying the secret.
  54          * @param other_id                              peer ID identifying the secret.
  55          * @param[out] secret                   the pre-shared secret will be written there.
  56          * @return
  57          *                                                              - NOT_FOUND     if no preshared secrets for specific ID could be found
  58          *                                                              - SUCCESS
  59          *
  60          */
  61         status_t (*get_shared_key) (credential_store_t *this, identification_t *my_id,
  62                                                                 identification_t *other_id, chunk_t *shared_key);
  63
  64         /**
  65          * @brief Returns the EAP secret for two specified IDs.
  66          *
  67          * The returned chunk must be destroyed by the caller after usage.
  68          *
  69          * @param this                                  calling object
  70          * @param my_id                                 my ID identifiying the secret.
  71          * @param other_id                              peer ID identifying the secret.
  72          * @param[out] eap_key                  the EAP secret will be written here
  73          * @return
  74          *                                                              - NOT_FOUND     if no preshared secrets for specific ID could be found
  75          *                                                              - SUCCESS
  76          *
  77          */
  78         status_t (*get_eap_key) (credential_store_t *this, identification_t *my_id,
  79                                                          identification_t *other_id, chunk_t *eap_key);
  80
  81         /**
  82          * @brief Returns the RSA public key of a specific ID.
  83          *
  84          * @param this                                  calling object
  85          * @param id                                    identification_t object identifiying the key.
  86          * @return                                              public key, or NULL if not found
  87          */
  88         rsa_public_key_t* (*get_rsa_public_key) (credential_store_t *this, identification_t *id);
  89
  90         /**
  91          * @brief Returns the RSA private key belonging to an RSA public key
  92          *
  93          * The returned rsa_private_key_t must be destroyed by the caller after usage.
  94          *
  95          * @param this                                  calling object
  96          * @param pubkey                                public key
  97          * @return                                              private key, or NULL if not found
  98          */
  99         rsa_private_key_t* (*get_rsa_private_key) (credential_store_t *this, rsa_public_key_t *pubkey);
 100
 101         /**
 102          * @brief Is there a matching RSA private key belonging to an RSA public key?
 103          *
 104          * @param this                                  calling object
 105          * @param pubkey                                public key
 106          * @return                                              TRUE if matching private key was found
 107          */
 108         bool (*has_rsa_private_key) (credential_store_t *this, rsa_public_key_t *pubkey);
 109
 110         /**
 111          * @brief Returns the certificate of a specific ID.
 112          *
 113          * @param this                                  calling object
 114          * @param id                                    identification_t object identifiying the cert.
 115          * @return                                              certificate, or NULL if not found
 116          */
 117         x509_t* (*get_certificate) (credential_store_t *this, identification_t *id);
 118
 119         /**
 120          * @brief Returns the auth certificate of a specific subject distinguished name.
 121          *
 122          * @param this                                  calling object
 123          * @param auth_flags                    set of allowed authority types
 124          * @param id                                    identification_t object identifiying the cacert.
 125          * @return                                              certificate, or NULL if not found
 126          */
 127         x509_t* (*get_auth_certificate) (credential_store_t *this, u_int auth_flags, identification_t *id);
 128
 129         /**
 130          * @brief Returns the ca certificate of a specific keyID.
 131          *
 132          * @param this                                  calling object
 133          * @param keyid                                 identification_t object identifiying the cacert.
 134          * @return                                              certificate, or NULL if not found
 135          */
 136         x509_t* (*get_ca_certificate_by_keyid) (credential_store_t *this, chunk_t keyid);
 137
 138         /**
 139          * @brief Returns the issuing ca of a given certificate.
 140          *
 141          * @param this                                  calling object
 142          * @param cert                                  certificate for which issuer ca info is required
 143          * @return                                              ca info, or NULL if not found
 144          */
 145         ca_info_t* (*get_issuer) (credential_store_t *this, x509_t* cert);
 146
 147         /**
 148          * @brief Verify an RSA signature given the ID of the signer
 149          *
 150          * @param this                                  calling object
 151          * @param hash                                  hash value to be verified.
 152          * @param sig                                   signature to be verified.
 153          * @param id                                    identification_t object identifiying the signer.
 154          * @param issuer_p                              issuer of the signer's certificate (if not self-signed).
 155          * @return                                              status of the verification - SUCCESS if successful
 156          */
 157         status_t (*verify_signature) (credential_store_t *this, chunk_t hash, chunk_t sig, identification_t *id, ca_info_t **issuer_p);
 158
 159         /**
 160          * @brief Verify an X.509 certificate up to trust anchor without any status checks
 161          *
 162          * @param this          calling object
 163          * @param cert          certificate to be verified
 164          * @return                      TRUE if trusted
 165          */
 166         bool (*is_trusted) (credential_store_t *this, x509_t *cert);
 167
 168         /**
 169          * @brief Verify an X.509 certificate up to trust anchor including status checks
 170          *
 171          * @param this          calling object
 172          * @param cert          certificate to be verified
 173          * @param found         found a certificate copy in the credential store
 174          * @return                      TRUE if valid, trusted, and current status is good
 175          */
 176         bool (*verify) (credential_store_t *this, x509_t *cert, bool *found);
 177
 178         /**
 179          * @brief If an end certificate does not already exists in the credential store then add it.
 180          *
 181          * @param this          calling object
 182          * @param cert          certificate to be added
 183          * @return                      pointer to the added or already existing certificate
 184          */
 185         x509_t* (*add_end_certificate) (credential_store_t *this, x509_t *cert);
 186
 187         /**
 188          * @brief If an authority certificate does not already exists in the credential store then add it.
 189          *
 190          * @param this                  calling object
 191          * @param cert                  authority certificate to be added
 192          * @param auth_flag             authority flags to add to the certificate
 193          * @return                              pointer to the added or already existing certificate
 194          */
 195         x509_t* (*add_auth_certificate) (credential_store_t *this, x509_t *cert, u_int auth_flag);
 196
 197         /**
 198          * @brief If a ca info record does not already exists in the credential store then add it.
 199          *
 200          * @param this          calling object
 201          * @param ca_info       ca info record to be added
 202          * @return                      pointer to the added or already existing ca_info_t record
 203          */
 204         ca_info_t* (*add_ca_info) (credential_store_t *this, ca_info_t *ca_info);
 205
 206         /**
 207          * @brief Release a ca info record with a given name.
 208          *
 209          * @param this          calling object
 210          * @param name          name of the ca info record to be released
 211          * @return
 212          *                                                      - SUCCESS, or
 213          *                                                      - NOT_FOUND
 214          */
 215         status_t (*release_ca_info) (credential_store_t *this, const char *name);
 216
 217         /**
 218          * @brief Create an iterator over all end certificates.
 219          *
 220          * @param this          calling object
 221          * @return                      iterator
 222          */
 223         iterator_t* (*create_cert_iterator) (credential_store_t *this);
 224
 225         /**
 226          * @brief Create an iterator over all authority certificates.
 227          *
 228          * @param this          calling object
 229          * @return                      iterator
 230          */
 231         iterator_t* (*create_auth_cert_iterator) (credential_store_t *this);
 232
 233         /**
 234          * @brief Create an iterator over all CA info records
 235          *
 236          * @param this          calling object
 237          * @return                      iterator
 238          */
 239         iterator_t* (*create_cainfo_iterator) (credential_store_t *this);
 240
 241         /**
 242          * @brief Loads ca certificates from a default directory.
 243          *
 244          * Certificates in both DER and PEM format are accepted
 245          *
 246          * @param this          calling object
 247          */
 248         void (*load_ca_certificates) (credential_store_t *this);
 249
 250         /**
 251          * @brief Loads authorization authority certificates from a default directory.
 252          *
 253          * Certificates in both DER and PEM format are accepted
 254          *
 255          * @param this          calling object
 256          */
 257         void (*load_aa_certificates) (credential_store_t *this);
 258
 259         /**
 260          * @brief Loads attribute certificates from a default directory.
 261          *
 262          * Certificates in both DER and PEM format are accepted
 263          *
 264          * @param this          calling object
 265          */
 266         void (*load_attr_certificates) (credential_store_t *this);
 267
 268         /**
 269          * @brief Loads ocsp certificates from a default directory.
 270          *
 271          * Certificates in both DER and PEM format are accepted
 272          *
 273          * @param this          calling object
 274          */
 275         void (*load_ocsp_certificates) (credential_store_t *this);
 276
 277         /**
 278          * @brief Loads CRLs from a default directory.
 279          *
 280          * Certificates in both DER and PEM format are accepted
 281          *
 282          * @param this          calling object
 283          * @param path          directory to load crls from
 284          */
 285         void (*load_crls) (credential_store_t *this);
 286
 287         /**
 288          * @brief Loads secrets in ipsec.secrets
 289          *
 290          * Currently, all RSA private key files must be in unencrypted form
 291      * either in DER or PEM format.
 292          *
 293          * @param this          calling object
 294          */
 295         void (*load_secrets) (credential_store_t *this);
 296
 297         /**
 298          * @brief Destroys a credential_store_t object.
 299          *
 300          * @param this          calling object
 301          */
 302         void (*destroy) (credential_store_t *this);
 303 };
 304
 305 /**
 306  * @brief Creates a credential_store_t instance.
 307  *
 308  * @param  strict               enforce a strict crl policy
 309  * @return                              credential store instance.
 310  *
 311  * @ingroup config
 312  */
 313 credential_store_t *credential_store_create(bool strict);
 314
 315
 316 #endif /*CREDENTIAL_STORE_H_*/