/************************************************************************** Copyright (c) [2005] Novell, Inc. All Rights Reserved. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; version 2.1 of the License. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, if not, contact Novell, Inc. To contact Novell about this file by physical or electronic mail, you may find current contact information at www.novell.com. **************************************************************************/ /*************************************************************************** * This is the SecretStore Client Service IDK Interfaces ***************************************************************************/ #ifndef _MICASA_H_ #define _MICASA_H_ #if defined(__cplusplus) || defined(c_plusplus) extern "C" { #endif #include "micasa_mgmd.h" /*************************************************************************** *** All strings are length preceeded and the lengths include the NULL. ***************************************************************************/ /*************************************************************************** *** most apis use a parameter called ssFlags, defined here ***************************************************************************/ #define SSFLAG_DESTROY_SESSION_F 0x00000001L // used with miCASACloseSecretStoreCache #define SSCS_SESSION_KEY_CHAIN_F 0x00000002L #define SSCS_LOCAL_KEY_CHAIN_F 0x00000004L #define SSCS_REMOTE_KEY_CHAIN_F 0x00000008L // ######################### FIRST RELEASE ############################ // Session key chain is maintained only in only in cache during the usr session */ /* FLAGS: (SSCS_SESSION_KEY_CHAIN_F) */ #define SSCS_S_KC_ID_F (SSCS_SESSION_KEY_CHAIN_F) #define SSCS_S_KC_ID_CHARS 26 static SS_UTF8_T SSCS_SESSION_KEY_CHAIN_ID[] = {"SSCS_SESSION_KEY_CHAIN_ID"}; // {'S','S','C','S','_','S','E','S','S','I','O','N','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0}; // ######################### FIRST RELEASE ############################ // ######################### FUTURE RELEASE ############################ // Persistent Private Keychain: // A Local keychain that is cached and is persistent */ #define SSCS_PPV_KC_ID_F SSCS_SL_KC_ID_F #define SSCS_PPV_KC_CHARS 24 #define SSCS_PERSISTENT_PRIVATE_KEYCHAIN_ID SSCS_LOCAL_KEY_CHAIN_ID // Public Keychain: // A Remote keychain that is cached locally only for the user session #define SSCS_PB_KC_F SSCS_SR_KC_ID_F #define SSCS_PB_KC_ID_CHARS 25 #define SSCS_PUBLIC_KEYCHAIN_ID SSCS_REMOTE_KEY_CHAIN_ID // Persistent Public Keychain: // A Remote keychain that is cached locally and is persistent */ #define SSCS_PPB_KC_F SSCS_SLR_KC_ID_F #define SSCS_PPB_KC_ID_CHARS 31 #define SSCS_PERSISTENT_PUBLIC_KEYCHAIN_ID SSCS_LOCAL_REMOTE_KEY_CHAIN_ID // ######################### FUTURE RELEASE ############################ // Default SecretID static SS_UTF8_T SECRET_ID_DEFAULT[] = {"Default_Credential"}; #define SECRET_ID_DEFAULT_LEN 19 // Known keys for Shared Secret format // =============================================== static SS_UTF8_T SHS_PASSWORD[] = {"Password"}; // {'P','a','s','s','s','w','o','r','d','=',0}; #define SHS_PASSWORD_LEN 9 static SS_UTF8_T SHS_USERNAME[] = {"Username"}; // {'U','s','e','r','n','a','m','e','=',0}; #define SHS_USER_NAME_LEN 9 static SS_UTF8_T SHS_OTHER[] = {"Other"}; //{'O','t','h','e','r','=',0}; #define SHS_OTHER_LEN 6 static SS_UTF8_T SHS_BINARY[] = {"Binary"}; //{'B','i','n','a','r','y','=',0}; #define SHS_BINARY_LEN 7 // Common Name static SS_UTF8_T SHS_CN[] = {"CN"}; //{'C','N','=',0}; #define SHS_CN_LEN 3 // LDAP DN static SS_UTF8_T SHS_DN_LDAP[] = {"DN_LDAP"}; //{'D','N','L','D','A','P','=',0}; #define SHS_DNLDAP_LEN 8 // NDAP DN static SS_UTF8_T SHS_DN_NDAP[] = {"DN_NDAP"}; //{'D','N','N','D','A','P','=',0}; #define SHS_DNNDAP_LEN 8 // NDAP FDN static SS_UTF8_T SHS_FDN_NDAP[] = {"FDN_NDAP"}; #define SHS_FDNNDAP_LEN 9 // EMAIL NAME static SS_UTF8_T SHS_EMAIL[] = {"EMAIL"}; //{'E','M','A','I','L','=',0}; #define SHS_EMAIL_LEN 6 /* STANDARD KEYCHAIN IDs */ /* Persistent local keychain that is cached */ /* FLAGS: (SSCS_SESSION_KEY_CHAIN_F | SSCS_LOCAL_KEY_CHAIN_F) */ #define SSCS_SL_KC_ID_F (SSCS_SESSION_KEY_CHAIN_F | SSCS_LOCAL_KEY_CHAIN_F) #define SSCS_SL_KC_ID_CHARS 24 // #define SSCS_SL_KC_LEN 48 static SS_UTF8_T SSCS_LOCAL_KEY_CHAIN_ID[] = {"SSCS_LOCAL_KEY_CHAIN_ID"}; // {'S','S','C','S','_','L','O','C','A','L','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0}; // /* A Remote keychain that is cached locally only for the user session /* FLAGS: (SSCS_SESSION_KEY_CHAIN_F | SSCS_REMOTE_KEY_CHAIN_F) */ #define SSCS_SR_KC_ID_F (SSCS_SESSION_KEY_CHAIN_F | SSCS_REMOTE_KEY_CHAIN_F) #define SSCS_SR_KC_ID_CHARS 25 // #define SSCS_SR_KC_ID_LEN 50 static SS_UTF8_T SSCS_REMOTE_KEY_CHAIN_ID[] = {"SSCS_REMOTE_KEY_CHAIN_ID"}; // {'S','S','C','S','_','R','E','M','O','T','E','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0}; /* A Remote keychain that is cached locally and is persistent */ /* FLAGS: (SSCS_SESSION_KEY_CHAIN_F | SSCS_REMOTE_KEY_CHAIN_F | SSCS_LOCAL_KEY_CHAIN_F) */ #define SSCS_SLR_KC_ID_F (SSCS_SESSION_KEY_CHAIN_F | SSCS_REMOTE_KEY_CHAIN_F | SSCS_LOCAL_KEY_CHAIN_F) #define SSCS_SLR_KC_ID_CHARS 31 // #define SSCS_SLR_KC_ID_LEN 62 static SS_UTF8_T SSCS_LOCAL_REMOTE_KEY_CHAIN_ID[] = {"SSCS_LOCAL_REMOTE_KEY_CHAIN_ID"}; // {'S','S','C','S','_','L','O','C','A','L','_','R','E','M','O','T','E','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0}; #define NSSCS_VERSION_NUMBER 0x00040000L // client version Major 04 Minor 00 Revision 01 // the final release will be 4.0.0 #define NSSCS_MIN_SECRET_BUF_LEN 3968 //* (4K-128)to match server #define NSSCS_MID_SECRET_BUF_LEN 32768 //* (4K-128)to match server #define NSSCS_MAX_SECRET_BUF_LEN 60416 //* (59K)to match server #define NSSCS_MAX_PWORD_HINT_LEN 128 //* maximum hint (bytes) #define NSSCS_MAX_KEYCHAIN_ID_LEN 256 //* in bytes including NULL #define NSSCS_MAX_NUM_OF_DEFAULT_KEYCHAINS 6 #define NSSCS_MIN_IDLIST_BUF_LEN 16384 //* (16K) #define NSSCS_MID_IDLIST_BUF_LEN 32768 //* (32K) #define NSSCS_MAX_IDLIST_BUF_LEN 65536 //* (64kK) #define NSSCS_JUMBO_IDLIST_BUF_LEN 131072 //* (128K) #define NSSCS_JUMBO_ENUM_BUF_LEN 131072 //* (128K) #define NSSCS_ENUM_BUFFER_GUESS 32768 //* (32K) #define NSSCS_ENUM_DELIM ((SS_UTF8_T)'*') //* immutable #define NSSCS_MAX_SRCH_KEY_LEN 128 //* maximum hint (bytes) #define SSCS_APPLICATION_TYPE_F 0x00000001L #define SSCS_CREDENTIAL_TYPE_F 0x00000002L #define NSSCS_MAX_PASSCODE_LEN 256 static SS_UTF8_T SSCS_DEFAULT_SECRETSTORE_ID[] = {"SecretStore"}; //{'S','e','c','r','e','t','S','t','o','r','e', 0}; #define SSCS_DEFAULT_SECRETSTORE_ID_LEN 12 static SS_UTF8_T SSCS_CRED_SET[] = {"SS_CredSet"}; //{'S','S','_','C','r','e','d','S','e','t', 0}; #define SSCS_CRED_SET_LEN 10 static SS_UTF8_T SSCS_BINARY_SECRET[] = {"SS_Binary"}; //{'S','S','_','B','i','n','a','r','y', 0}; #define SSCS_BINARY_CHARS 9 static SS_UTF8_T APP_DELIMITER[] = {":"}; #define APP_DELIMITER_LEN 2 static SS_UTF8_T CREDSET_DELIMITER[] = {"="}; #define CREDSET_DELIMITER_LEN 2 static SS_UTF8_T BINARY_DELIMITER[] = {"="}; #define BINARY_DELIMITER_LEN 2 #define SSCS_MASTER_PASSWORD 1 #define SSCS_ENHANCED_PROTECTION_PASSWORD 2 #define SSCS_DIRECTORY_PASSWORD 1 typedef struct _sscs_password { unsigned long pwordType; unsigned long pwordLen; // enhanced protection len & pword to set SS_UTF8_T pword[NSSCS_MAX_PWORD_LEN]; // * should be passed in # of chars } SSCS_PASSWORD_T; typedef struct _sscs_sh_secret_id { uint32_t type; // The shared secret type i.e. SS_App or SS_CredSet uint32_t len; // except that it excludes the header and is not escaped. SS_UTF8_T name[NSSCS_MAX_SECRET_ID_LEN]; // The shared secret name. This is the same as the identifier } SSCS_SH_SECRET_ID_T; typedef struct _sscs_passcode { uint32_t passcodeType; void *passcodeHandle; // can be password structure or other types of structures. } SSCS_PASSCODE_T; typedef struct _sscs_secretstore { uint32_t version; SS_UTF8_T ssName[NSSCS_MAX_SECRET_ID_LEN]; } SSCS_SECRETSTORE_T; typedef struct _ssscs_read_extension { uint32_t statFlags; //* OUT - return flags on the secret uint32_t crtStamp; //* OUT - secret creation time stamp uint32_t latStamp; //* OUT - last accessed time stamp (optional) uint32_t lmtStamp; //* OUT - last modified time stamp } SSCS_READEXT_T; typedef struct _sscs_hint { uint32_t hintLen; SS_UTF8_T hint[NSSCS_MAX_PWORD_HINT_LEN]; //* should be passed in # of chars } SSCS_HINT_T; typedef struct _sscs_secretstore_info { uint32_t numKeyChains; uint32_t enumBufsize; } SSCS_SECRETSTORE_INFO_T; typedef struct _sscs_srch_key { uint32_t srchKeyLen; SS_UTF8_T srchKey[NSSCS_MAX_SRCH_KEY_LEN]; //* should be passed in # of chars } SSCS_SRCH_KEY_T; typedef struct _sscs_sh_secret_ID_List { uint32_t enumHandle; // set to 0 to begin with uint32_t returnedIDs; // to be initialized by the caller to the array size SSCS_SH_SECRET_ID_T *secIDList; //* an array of secret IDs structures. } SSCS_SH_SECRET_ID_LIST_T; typedef struct _sscs_keychain_id { uint32_t len; SS_UTF8_T keychainID[NSSCS_MAX_SECRET_ID_LEN]; } SSCS_KEYCHAIN_ID_T; typedef struct _sscs_keychain_id_list { uint32_t enumHandle; // set to 0 to begin with uint32_t returnedIDs; // to be initialized by the caller to the array size SSCS_KEYCHAIN_ID_T *keyChainIDList; //* an array of keychainID structures } SSCS_KEYCHAIN_ID_LIST_T; // ************************************************************** // * The following functions will be exposed as exported API: // ************************************************************** // * SSCS APIs below export the interface for applications. // * Support APIs are needed for populating or extracting data // * from a Shared Secret. // ************************************************************** SSCS_EXTERN_LIBCALL_PTR(void) miCASAOpenSecretStoreCache ( SSCS_SECRETSTORE_T * ssid, uint32_t ssFlags, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASACloseSecretStoreCache ( void * context, uint32_t ssFlags, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAReadSecret ( void * context, SSCS_KEYCHAIN_ID_T * keyChainID, uint32_t ssFlags, void * secretHandle, SSCS_SH_SECRET_ID_T * sharedSecretID, SSCS_PASSWORD_T * epPassword, SSCS_READEXT_T * readData, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASARemoveSecret ( void * context, SSCS_KEYCHAIN_ID_T * keyChainID, uint32_t ssFlags, SSCS_SH_SECRET_ID_T * sharedSecretID, SSCS_PASSWORD_T * epPassword, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAWriteSecret ( void * context, SSCS_KEYCHAIN_ID_T * keyChainID, uint32_t ssFlags, void * secretHandle, SSCS_SH_SECRET_ID_T * sharedSecretID, SSCS_PASSWORD_T * epPassword, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAGetStoreInformation ( void * context, uint32_t ssFlags, SSCS_SECRETSTORE_INFO_T * ssInfo, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAEnumerateSecretIDs ( void * context, SSCS_KEYCHAIN_ID_T * keyChainID, uint32_t ssFlags, SSCS_SRCH_KEY_T * searchKey, SSCS_SH_SECRET_ID_LIST_T * secretIDList, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASARemoveSecretStore ( void * context, uint32_t ssFlags, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASASetMasterPassword ( uint32_t ssFlags, SSCS_PASSWORD_T * password, SSCS_HINT_T * hint, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAUnlockSecrets ( void * context, uint32_t ssFlags, SSCS_PASSWORD_T * password, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASALockStore ( void * context, uint32_t ssFlags, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAUnlockStore ( void * context, uint32_t ssFlags, SSCS_PASSCODE_T * passcode, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAEnumerateKeyChainIDs ( void * context, uint32_t ssFlags, SSCS_SRCH_KEY_T * searchKey, SSCS_KEYCHAIN_ID_LIST_T * kcIDList, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAAddKeyChain ( void * context, uint32_t ssFlags, SSCS_KEYCHAIN_ID_T * keyChainID, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASARemoveKeyChain ( void * context, uint32_t ssFlags, SSCS_KEYCHAIN_ID_T * keyChainID, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASAWriteKey ( void * context, uint32_t ssFlags, SSCS_KEYCHAIN_ID_T * keyChainID, SSCS_SECRET_ID_T * sharedSecretID, SS_UTF8_T *key, uint32_t keyLen, uint8_t *val, uint32_t valLen, SSCS_PASSWORD_T * epPassword, SSCS_EXT_T * ext ); SSCS_EXTERN_LIBCALL(int32_t) miCASASetMasterPasscode ( uint32_t ssFlags, SSCS_PASSCODE_T *passcode, SSCS_EXT_T *ext ); //************************************************************** //* Support Functions for processing (populating or extracting) //* data components from Shared Secrets //************************************************************** SSCS_EXTERN_LIBCALL_PTR(void) miCASA_CreateSHSHandle(); SSCS_EXTERN_LIBCALL(int32_t) miCASA_DestroySHSHandle(void *secretHandle); // in SSCS_EXTERN_LIBCALL(int32_t) miCASA_GetNextSHSEntry ( int32_t restart, void *secretHandle, uint32_t *keyLen, SS_UTF8_T *key, uint32_t *valLen, uint8_t *value ); SSCS_EXTERN_LIBCALL(int32_t) miCASA_AddSHSEntry ( void *secretHandle, SS_UTF8_T *key, uint32_t valueLen, uint8_t *value ); SSCS_EXTERN_LIBCALL(int32_t) miCASA_RemoveSHSEntry ( void *secretHandle, SS_UTF8_T *key, uint32_t valueLen, uint8_t *value ); #if defined(__cplusplus) || defined(c_plusplus) } #endif #endif /* _miCASA_H */