/***********************************************************************
*
* Copyright (C) 2005-2006 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
* Library 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, Novell, Inc.
*
* To contact Novell about this file by physical or electronic mail,
* you may find current contact information at www.novell.com.
*
***********************************************************************/
#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 0x00010000L // client version Major 04 Minor 00 Revision 01
// the final release will be 1.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
{
uint32_t pwordType;
uint32_t 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)
miCASAWriteBinaryKey
(
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)
miCASAReadBinaryKey
(
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,
uint32_t * bytesRequired,
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 */