1/* 2 * Copyright (c) 2004 Apple Computer, Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/*! 25 @header SecTokend.h 26 @copyright 2004 Apple Computer, Inc. All Rights Reserved. 27 @abstract SPIs for creating a tokend. 28 */ 29 30#ifndef _SECURITYTOKEND_SECTOKEND_H_ 31#define _SECURITYTOKEND_SECTOKEND_H_ 1 32 33#include <stdint.h> 34#include <Security/cssm.h> 35#include <PCSC/winscard.h> 36#include <sys/param.h> 37 38#ifdef __cplusplus 39extern "C" { 40#endif 41 42 43// 44// Constants and fixed values 45// 46enum { 47 kSecTokendCallbackVersion = 11 // interface version for callback structure 48}; 49 50enum { 51 TOKEND_MAX_UID = 128 // max. length of token identifier string 52}; 53 54// flags to establish() 55typedef uint32 SecTokendCallbackFlags; 56typedef uint32 SecTokendProbeFlags; 57typedef uint32 SecTokendEstablishFlags; 58 59enum { 60 // flags in the callback structure passed to SecTokendMain() 61 kSecTokendCallbacksDefault = 0, // default flags in callbacks struct 62 63 // flags to probe() 64 kSecTokendProbeDefault = 0, // default flags to probe() call 65 kSecTokendProbeKeepToken = 0x0001, // may keep token connected when returning 66 67 // flags to establish() 68 kSecTokendEstablishNewCache = 0x0001, // the on-disk cache is new (and empty) 69 kSecTokendEstablishMakeMDS = 0x0002, // (must) write MDS files to cache 70 71 // test/debug flags (not for normal operation) 72 kSecTokendCallbacksTestNoServer = 0x0001, // don't start server; return after setup 73}; 74 75 76/* 77 * Common arguments for data retrieval 78 */ 79typedef struct { 80 CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes; // add attribute values here 81 CSSM_DATA *data; // store item data there unless NULL 82 CSSM_HANDLE record; // store record-id here 83 CSSM_HANDLE keyhandle; // key handle if key, 0 otherwise 84} TOKEND_RETURN_DATA; 85 86 87/*! 88 @typedef 89 @abstract Functions a particular tokend instance needs to implement 90 */ 91typedef struct 92{ 93 uint32_t version; 94 SecTokendCallbackFlags flags; 95 96 CSSM_RETURN (*initial)(); 97 CSSM_RETURN (*probe)(SecTokendProbeFlags flags, uint32 *score, char tokenUid[TOKEND_MAX_UID]); 98 CSSM_RETURN (*establish)(const CSSM_GUID *guid, uint32 subserviceId, 99 SecTokendEstablishFlags flags, const char *cacheDirectory, const char *workDirectory, 100 char mdsDirectory[PATH_MAX], char printName[PATH_MAX]); 101 CSSM_RETURN (*terminate)(uint32 reason, uint32 options); 102 103 CSSM_RETURN (*findFirst)(const CSSM_QUERY *query, TOKEND_RETURN_DATA *data, 104 CSSM_HANDLE *hSearch); 105 CSSM_RETURN (*findNext)(CSSM_HANDLE hSearch, TOKEND_RETURN_DATA *data); 106 CSSM_RETURN (*findRecordHandle)(CSSM_HANDLE hRecord, TOKEND_RETURN_DATA *data); 107 CSSM_RETURN (*insertRecord)(CSSM_DB_RECORDTYPE recordType, 108 const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes, const CSSM_DATA *data, 109 CSSM_HANDLE *hRecord); 110 CSSM_RETURN (*modifyRecord)(CSSM_DB_RECORDTYPE recordType, CSSM_HANDLE *hRecord, 111 const CSSM_DB_RECORD_ATTRIBUTE_DATA *attributes, const CSSM_DATA *data, 112 CSSM_DB_MODIFY_MODE modifyMode); 113 CSSM_RETURN (*deleteRecord)(CSSM_HANDLE hRecord); 114 CSSM_RETURN (*releaseSearch)(CSSM_HANDLE hSearch); 115 CSSM_RETURN (*releaseRecord)(CSSM_HANDLE hRecord); 116 117 CSSM_RETURN (*freeRetrievedData)(TOKEND_RETURN_DATA *data); 118 119 CSSM_RETURN (*releaseKey)(CSSM_HANDLE hKey); 120 CSSM_RETURN (*getKeySize)(CSSM_HANDLE hKey, CSSM_KEY_SIZE *size); 121 CSSM_RETURN (*getOutputSize)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 122 uint32 inputSize, CSSM_BOOL encrypting, uint32 *outputSize); 123 124 CSSM_RETURN (*generateSignature)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 125 CSSM_ALGORITHMS signOnly, const CSSM_DATA *input, CSSM_DATA *signature); 126 CSSM_RETURN (*verifySignature)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 127 CSSM_ALGORITHMS signOnly, const CSSM_DATA *input, const CSSM_DATA *signature); 128 CSSM_RETURN (*generateMac)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 129 const CSSM_DATA *input, CSSM_DATA *mac); 130 CSSM_RETURN (*verifyMac)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 131 const CSSM_DATA *input, const CSSM_DATA *mac); 132 CSSM_RETURN (*encrypt)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 133 const CSSM_DATA *clear, CSSM_DATA *cipher); 134 CSSM_RETURN (*decrypt)(const CSSM_CONTEXT *context, CSSM_HANDLE hKey, 135 const CSSM_DATA *cipher, CSSM_DATA *clear); 136 137 CSSM_RETURN (*generateKey)(const CSSM_CONTEXT *context, 138 const CSSM_ACCESS_CREDENTIALS *creds, const CSSM_ACL_ENTRY_PROTOTYPE *owner, 139 CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attrs, 140 CSSM_HANDLE *hKey, CSSM_KEY *header); 141 CSSM_RETURN (*generateKeyPair)(const CSSM_CONTEXT *context, 142 const CSSM_ACCESS_CREDENTIALS *creds, const CSSM_ACL_ENTRY_PROTOTYPE *owner, 143 CSSM_KEYUSE pubUsage, CSSM_KEYATTR_FLAGS pubAttrs, 144 CSSM_KEYUSE privUsage, CSSM_KEYATTR_FLAGS privAttrs, 145 CSSM_HANDLE *hPubKey, CSSM_KEY *pubHeader, 146 CSSM_HANDLE *hPrivKey, CSSM_KEY *privHeader); 147 148 CSSM_RETURN (*wrapKey)(const CSSM_CONTEXT *context, 149 CSSM_HANDLE hWrappingKey, const CSSM_KEY *wrappingKey, const CSSM_ACCESS_CREDENTIALS *cred, 150 CSSM_HANDLE hKeyToBeWrapped, const CSSM_KEY *keyToBeWrapped, const CSSM_DATA *descriptiveData, 151 CSSM_KEY *wrappedKey); 152 CSSM_RETURN (*unwrapKey)(const CSSM_CONTEXT *context, 153 CSSM_HANDLE hWrappingKey, const CSSM_KEY *wrappingKey, const CSSM_ACCESS_CREDENTIALS *cred, 154 const CSSM_ACL_ENTRY_PROTOTYPE *access, 155 CSSM_HANDLE hPublicKey, const CSSM_KEY *publicKey, const CSSM_KEY *wrappedKey, 156 CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attributes, 157 CSSM_DATA *descriptiveData, 158 CSSM_HANDLE *hUnwrappedKey, CSSM_KEY *unwrappedKey); 159 CSSM_RETURN (*deriveKey)(const CSSM_CONTEXT *context, 160 CSSM_HANDLE hSourceKey, const CSSM_KEY *sourceKey, const CSSM_ACCESS_CREDENTIALS *cred, 161 const CSSM_ACL_ENTRY_PROTOTYPE *access, CSSM_DATA *parameters, 162 CSSM_KEYUSE usage, CSSM_KEYATTR_FLAGS attributes, 163 CSSM_HANDLE *hKey, CSSM_KEY *key); 164 165 CSSM_RETURN (*getDatabaseOwner)(CSSM_ACL_OWNER_PROTOTYPE *owner); 166 CSSM_RETURN (*getDatabaseAcl)(const char *tag, uint32 *count, CSSM_ACL_ENTRY_INFO **entries); 167 CSSM_RETURN (*getObjectOwner)(CSSM_HANDLE hRecord, CSSM_ACL_OWNER_PROTOTYPE *owner); 168 CSSM_RETURN (*getObjectAcl)(CSSM_HANDLE hRecord, const char *tag, 169 uint32 *count, CSSM_ACL_ENTRY_INFO **entries); 170 CSSM_RETURN (*getKeyOwner)(CSSM_HANDLE hKey, CSSM_ACL_OWNER_PROTOTYPE *owner); 171 CSSM_RETURN (*getKeyAcl)(CSSM_HANDLE hKey, 172 const char *tag, uint32 *count, CSSM_ACL_ENTRY_INFO **entries); 173 174 CSSM_RETURN (*freeOwnerData)(CSSM_ACL_OWNER_PROTOTYPE *owner); 175 CSSM_RETURN (*freeAclData)(uint32 count, CSSM_ACL_ENTRY_INFO *entries); 176 177 CSSM_RETURN (*authenticateDatabase)(CSSM_DB_ACCESS_TYPE mode, 178 const CSSM_ACCESS_CREDENTIALS *cred); 179 180 CSSM_RETURN (*changeDatabaseOwner)(const CSSM_ACL_OWNER_PROTOTYPE *owner); 181 CSSM_RETURN (*changeDatabaseAcl)(const CSSM_ACCESS_CREDENTIALS *cred, const CSSM_ACL_EDIT *edit); 182 CSSM_RETURN (*changeObjectOwner)(CSSM_HANDLE hRecord, const CSSM_ACL_OWNER_PROTOTYPE *owner); 183 CSSM_RETURN (*changeObjectAcl)(CSSM_HANDLE hRecord, const CSSM_ACCESS_CREDENTIALS *cred, const CSSM_ACL_EDIT *edit); 184 CSSM_RETURN (*changeKeyOwner)(CSSM_HANDLE key, const CSSM_ACL_OWNER_PROTOTYPE *owner); 185 CSSM_RETURN (*changeKeyAcl)(CSSM_HANDLE key, const CSSM_ACCESS_CREDENTIALS *cred, const CSSM_ACL_EDIT *edit); 186 187 CSSM_RETURN (*generateRandom)(const CSSM_CONTEXT *context, CSSM_DATA *result); 188 CSSM_RETURN (*getStatistics)(CSSM_CSP_OPERATIONAL_STATISTICS *result); 189 CSSM_RETURN (*getTime)(CSSM_ALGORITHMS algorithm, CSSM_DATA *result); 190 CSSM_RETURN (*getCounter)(CSSM_DATA *result); 191 CSSM_RETURN (*selfVerify)(); 192 193 CSSM_RETURN (*cspPassThrough)(uint32 id, const CSSM_CONTEXT *context, 194 CSSM_HANDLE hKey, const CSSM_KEY *key, const CSSM_DATA *input, CSSM_DATA *output); 195 CSSM_RETURN (*dlPassThrough)(uint32 id, const CSSM_DATA *input, CSSM_DATA *output); 196 CSSM_RETURN (*isLocked)(uint32 *locked); 197 198} SecTokendCallbacks; 199 200 201/* 202 * 203 */ 204typedef struct { 205 const SCARD_READERSTATE *(*startupReaderInfo)(); // get reader information 206 const char *(*tokenUid)(); // uid string in use for this token 207 void *(*malloc)(uint32 size); // ordinary memory to interface 208 void (*free)(void *data); // free malloc'ed data 209 void *(*mallocSensitive)(uint32 size); // sensitive memory to interface 210 void (*freeSensitive)(void *data); // free mallocSensitive'ed data 211} SecTokendSupport; 212 213 214/*! 215 @function 216 @abstract call this from main in your program 217 @param argc The argc passed to main(). 218 @param argv The argv passed to main(). 219 @param callbacks Pointer to a SecTokendCallbacks struct containing pointers to all the functions this tokend instance implements. 220 @description The main of your program should look like: 221 222 int main(argc, argv) { ...Create context... return SecTokendMain(argc, argv, &callbacks, &supportCalls); } 223 */ 224int SecTokendMain(int argc, const char * argv[], const SecTokendCallbacks *callbacks, SecTokendSupport *support); 225 226#ifdef __cplusplus 227} 228#endif 229 230#endif /* _SECURITYTOKEND_SECTOKEND_H_ */ 231