src/libstrongswan/plugins/pkcs11/pkcs11_library.h

   1 /*
   2  * Copyright (C) 2010 Martin Willi
   3  * Copyright (C) 2010 revosec AG
   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 pkcs11_library pkcs11_library
  18  * @{ @ingroup pkcs11
  19  */
  20
  21 #ifndef PKCS11_LIBRARY_H_
  22 #define PKCS11_LIBRARY_H_
  23
  24 typedef enum pkcs11_feature_t pkcs11_feature_t;
  25 typedef struct pkcs11_library_t pkcs11_library_t;
  26
  27 #include "pkcs11.h"
  28
  29 #include <enum.h>
  30 #include <utils/enumerator.h>
  31
  32 /**
  33  * Optional PKCS#11 features some libraries support, some not
  34  */
  35 enum pkcs11_feature_t {
  36         /** CKA_TRUSTED attribute supported for certificate objects */
  37         PKCS11_TRUSTED_CERTS = (1<<0),
  38         /** CKA_ALWAYS_AUTHENTICATE attribute supported for private keys */
  39         PKCS11_ALWAYS_AUTH_KEYS = (1<<1),
  40 };
  41
  42 /**
  43  * A loaded and initialized PKCS#11 library.
  44  */
  45 struct pkcs11_library_t {
  46
  47         /**
  48          * PKCS#11 function list, as returned by C_GetFunctionList
  49          */
  50         CK_FUNCTION_LIST_PTR f;
  51
  52         /**
  53          * Get the name this instance was created with.
  54          *
  55          * @return                      name, as passed to constructor
  56          */
  57         char* (*get_name)(pkcs11_library_t *this);
  58
  59         /**
  60          * Get the feature set supported by this library.
  61          *
  62          * @return                      ORed set of features supported
  63          */
  64         pkcs11_feature_t (*get_features)(pkcs11_library_t *this);
  65
  66         /**
  67          * Create an enumerator over CK_OBJECT_HANDLE using a search template.
  68          *
  69          * An optional attribute array is automatically filled in with the
  70          * objects associated attributes. If the value of an output attribute
  71          * is NULL, the value gets allocated/freed during enumeration.
  72          *
  73          * @param session       session to use
  74          * @param tmpl          search template
  75          * @param tcount        number of attributes in the search template
  76          * @param attr          attributes to read from object
  77          * @param acount        number of attributes to read
  78          */
  79         enumerator_t* (*create_object_enumerator)(pkcs11_library_t *this,
  80                         CK_SESSION_HANDLE session, CK_ATTRIBUTE_PTR tmpl, CK_ULONG tcount,
  81                         CK_ATTRIBUTE_PTR attr, CK_ULONG acount);
  82
  83         /**
  84          * Create an enumerator over supported mechanisms of a token.
  85          *
  86          * The resulting enumerator enumerates over the mechanism type, and if
  87          * a non-NULL pointer is given, over the mechanism info details.
  88          *
  89          * @param slot          slot of the token
  90          * @return                      enumerator over (CK_MECHANISM_TYPE, CK_MECHANISM_INFO)
  91          */
  92         enumerator_t* (*create_mechanism_enumerator)(pkcs11_library_t *this,
  93                                                                                                  CK_SLOT_ID slot);
  94
  95         /**
  96          * Destroy a pkcs11_library_t.
  97          */
  98         void (*destroy)(pkcs11_library_t *this);
  99 };
 100
 101 /**
 102  * Enum names for CK_RV return values
 103  */
 104 extern enum_name_t *ck_rv_names;
 105
 106 /**
 107  * Enum names for CK_MECHANISM_TYPE values
 108  */
 109 extern enum_name_t *ck_mech_names;
 110
 111 /**
 112  * Trim/null terminate a string returned by the varius PKCS#11 functions.
 113  *
 114  * @param str           string to trim
 115  * @param len           max length of the string
 116  */
 117 void pkcs11_library_trim(char *str, int len);
 118
 119 /**
 120  * Create a pkcs11_library instance.
 121  *
 122  * @param name          an arbitrary name, for debugging
 123  * @param file          pkcs11 library file to dlopen()
 124  * @param os_lock       enforce OS Locking for this library
 125  * @return                      library abstraction
 126  */
 127 pkcs11_library_t *pkcs11_library_create(char *name, char *file, bool os_lock);
 128
 129 #endif /** PKCS11_LIBRARY_H_ @}*/