CASA/include/sscs_cache.h

/***********************************************************************
 * 
 *  Copyright (C) 2005-2006 Novell, Inc.
 *
 *  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 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, write to the Free
 *  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 ***********************************************************************/

#ifndef	_SSCS_CACHE_H
#define	_SSCS_CACHE_H

#if defined(__cplusplus) || defined(c_plusplus)
extern "C"
{
#endif

//#include <wchar.h>
#include <sscs_sdk.h>
#include <sscs_utf8.h>
#include <micasa_types.h>
#include <malloc.h>

/* Predefined Key Chains */
/* SSCS_HIDDEN_LOCAL_KEY_CHAIN_F should not be used by the applications */
#define SSCS_HIDDEN_LOCAL_KEY_CHAIN_F		0x00000001L
/*  Hidden local key chain is used only by sscs. Not visible to applications. */
#define	SSCS_SH_KC_ID  (SSCS_SESSION_KEY_CHAIN_F | SSCS_HIDDEN_KEY_CHAIN_F)	 
#if 0
static wchar_t	SSCS_HIDDEN_LOCAL_KEY_CHAIN_ID[] = 
	{'S','S','C','C','S','_','H','I','D','D','E','N','_','L','O','C','A','L','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0};

static wchar_t SSCS_RESERVED1_KEY_CHAIN_ID[] =
	{'S','S','C','C','S','_','R','E','S','E','R','V','E','D','1','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0};

static wchar_t SSCS_RESERVED2_KEY_CHAIN_ID[] =
	{'S','S','C','C','S','_','R','E','S','E','R','V','E','D','2','_','K','E','Y','_','C','H','A','I','N','_','I','D', 0};
#endif

static SS_UTF8_T SSCS_HIDDEN_LOCAL_KEY_CHAIN_ID[] = "SSCS_HIDDEN_LOCAL_KEYCHAIN_ID";

static SS_UTF8_T SSCS_RESERVED1_KEY_CHAIN_ID[] = "SSCS_RESERVED1_KEYCHAIN1_ID";
static SS_UTF8_T SSCS_RESERVED2_KEY_CHAIN_ID[] = "SSCS_RESERVED2_KEYCHAIN2_ID";

//#define SSCS_WIN32_PLAT_F		1
//#define SSCS_LINUX_PLAT_F		2

#define SSCS_PASSWORD_MP_F		1
#define SSCS_CRED_MP_F			2

#define NSSCS_MAX_ID_LEN	 		256

typedef struct _sscs_linux_ss_handle
{
	int32_t			socketID;
} SSCS_LINUX_SS_HANDLE_T;

typedef struct _sscs_win32_ss_handle
{
	int32_t		tobediceded;
} SSCS_WIN32_SS_HANDLE_T;

typedef struct _sscs_secretstore_handle
{
	int32_t		platformID;
	void		*platHandle;
} SSCS_SECRETSTORE_HANDLE_T;


typedef struct _sscs_keychain_info
{
	uint32_t		flags;
	uint32_t 		numSecrets;
	uint32_t 		numOfHiddenSecrets;
	uint32_t 		numOfDeletedSecs;
	uint32_t		enumBufsize;
	SSCS_KEYCHAIN_ID_T	keyChainID;
} SSCS_KEYCHAIN_INFO_T;

// * Secret Data type 
typedef	struct	_sscs_secret
{
	int32_t			len;
	uint8_t			*data;
} SSCS_SECRET_T;

typedef	struct _sscs_context_t
{
	int32_t								version;
	int32_t								flags;
	SSCS_SECRETSTORE_T				ssid;
	void							*ssHandle;
	SSCS_KEYCHAIN_ID_LIST_T			*kcids;
} SSCS_CONTEXT_T;



/* Starts a session with the cache and returns a handle to the cache.
 * Parametrs:
 * 		secretStoreID
 *			(IN) Points to SecretStoreID structure.
 *
 * Return Values:
 *		returns a pointer to SecretStoreHandle structure.
 */
void* sscs_CacheOpenSecretStore
(
	void 			*secretStoreID,
	uint32_t		ssFlags,
	void			*reserved

);

/* Closes the secretstore and destroys the SecretStore context for that 
 * application.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 * 
 * Return Values
 *
 */
int sscs_CacheCloseSecretStore
(
	void 			*ssHandle,
	uint32_t		ssFlags,
	void			*reserved
);

/* Removes all application defined keychains from the store. It also removes 
 * secrets stored in system defined keychains.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *
 * Return Values:
 */
int sscs_CacheRemoveSecretStore
(
	void 			*ssHandle,
	uint32_t		ssFlags,
	void			*reserved
);

/* Enumerates key chain ids available in the store.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *
 *		kcIDList
 *			(OUT) Points to the key chain id enumeration structure. Points to 
 *			KeyChainIDList structure.
 *
 *
 * Return Values:
 *
 */
int sscs_CacheEnumerateKeychainIDs
(
	void 					*ssHandle,
	uint32_t				ssFlags,
	SSCS_SRCH_KEY_T				*searchKey,
	SSCS_KEYCHAIN_ID_LIST_T 		*kcIDList,
	void					*reserved
);

/* Creates a new keychain in the store.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *		ssFlags
 *			(IN) Can be a combination of following flags:
 *				SSCS_SESSION_KEY_CHAIN_F		
 *				SSCS_LOCAL_KEY_CHAIN_F			
 *				SSCS_REMOTE_KEY_CHAIN_F			
 *		keychainID
 *			(IN) Specifies the unique keychain ID within the secretstore.
 *
 */
int sscs_CacheAddKeychain 
(
	void 				*ssHandle,
	uint32_t			ssFlags,
	SSCS_KEYCHAIN_ID_T		*keyChainID, 
	void				*reserved
);


/* Removes the specified keychain from the store.
 *
 * Parameters: 
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *		keychainID
 *			(IN) Specifies the unique keychain ID within the secretstore.
 *
 * Return Values:
 */
int sscs_CacheRemoveKeychain 
(
	void 				*ssHandle,
	uint32_t			ssFlags,
	SSCS_KEYCHAIN_ID_T		*keyChainID, 
	void				*reserved
);

/* Enumerates secret ids in a given keychain.
 *
 * Parameters:
 * 		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *		keyChainID
 *			(IN) handle obtained during sscs_CacheOpenKeychain.
 *
 *
 *		secretIDList
 *			(OUT) Points to the secret id enumeration structure. Points to 
 *			SecretIDList structure.
 *
 * Return Values:
 */
int sscs_CacheEnumerateSecretIDs
(
	void 				*ssHandle,
	uint32_t			ssFlags,
	SSCS_KEYCHAIN_ID_T		*keyChainID, 
	SSCS_SRCH_KEY_T			*searchKey, 
	SSCS_SECRET_ID_LIST_T	*secretIDList,
	void				*reserved
);


/* Reads Secret value for a given Secret ID in a given keychain.
 *
 * Parameters: 
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *		keyChainID
 *			(IN) KeyChainID where the specified SecretID stored.
 *
 *		secretID
 *			(IN) Specifies the unique secret ID within the keychain. This data is 
 *			encoded in SSCS_SECRET_ID_T.
 *
 *		secretData
 *			(IN/OUT) Specifies the information of the secret stored w.r.t the secretID. 
 *			Points to a SSCS_SECRET_T structure.
 *
 *		epPassword
 *			(IN) Points to an optional field to pass in the Enhanced Protection Password 
 *			for reading a secret.When the password is not present, you can pass in a NULL.
 *
 *		bytesRequired
 *			(OUT) Specifies the buffer requirement if it is not possible 
 * 			to copy Secret data in the buffer passed by the application.

 *
 * Return Values :
 */
int sscs_CacheReadSecret 
(
	void 				*ssHandle,
	uint32_t		ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID, 
	SSCS_SECRET_ID_T	*secretID,
	SSCS_SECRET_T		*secretData,
	SSCS_PASSWORD_T		*epPassword,
	uint32_t		*bytesRequired,
	void				*reserved
);


/* Writes Secret value for a given Secret ID in a given keychain.
 * 
 * Parameters: 
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *		ssFlags
 *			(IN) ...
 *
 *		keyChainID
 *			(IN) KeyChainID where the specified SecretID stored.
 *
 *		secretID
 *			(IN) Specifies the unique secret ID within the keychain. 			This data is 
 *			encoded in SSCS_SECRET_ID_T.
 *
 *		secretData
 *			(IN) Specifies the information of the secret stored w.r.t the secretID. 
 *			Points to a SSCS_SECRET_T structure.
 *
 *
 *		epPassword
 *			(IN) Points to an optional field to pass in the Enhanced Protection Password 
 *			for reading a secret.When the password is not present, you can pass in a NULL.
 *
 *
 *
 * Return Values:
 */
int sscs_CacheWriteSecret 
(
	void 				*ssHandle,
	uint32_t		ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID, 
	SSCS_SECRET_ID_T	*secretID,
	SSCS_SECRET_T		*secretData,
	SSCS_PASSWORD_T		*epPassword,
	void				*reserved
);


/* Removes Secret for a given Secret ID in a given keychain.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context information regarding the SecretStore.
 *
 *
 *		keyChainID
 *			(IN) KeyChainID where the specified SecretID stored.
 *
 *		secretID
 *			(IN) Specifies the unique secret ID within the keychain. 			This data is 
 *			encoded in SSCS_SECRET_ID_T.
 *
 *
 *		epPassword
 *			(IN) Points to an optional field to pass in the Enhanced Protection Password 
 *			for reading a secret.When the password is not present, you can pass in a NULL.
 *
 * Return Values:
 */
int sscs_CacheRemoveSecret 
(
	void 				*ssHandle,
	uint32_t		ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID, 
	SSCS_SECRET_ID_T	*secretID,
	SSCS_PASSWORD_T     *epPassword,
	void				*reserved
);

/* Returns statistical information regarding the SecretStore and its  Keychains.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context with respect to the instance of open cache in it. 
 *
 *
 *		ssInfo
 *			(OUT) This structure contains the statistical information regarding the 
 *			SecretStore and its  Keychains. 
 *
 * Return Values:
 */
int sscs_CacheGetSecretStoreInfo 
(
	void 					*ssHandle,
	uint32_t			ssFlags,
	SSCS_SECRETSTORE_INFO_T *ssInfo, 
	void					*reserved
);

/* Retrieves the statistical information regarding the target Keychain.
 *
 * Parameters: 
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context with respect to the instance of open cache in it. 
 *
 *		keyChainID
 *			(IN) KeyChainID where the specified SecretID stored.
 *
 *
 *		kcInfo
 *			(OUT) This structure contains the statistical information regarding the  
 *			Keychain. 
 *
 *
 * Return Values:
 */
int sscs_CacheGetKeychainInfo 
(
	void 					*ssHandle,
	uint32_t			ssFlags,
	SSCS_KEYCHAIN_ID_T		*keyChainID, 
	SSCS_KEYCHAIN_INFO_T   	*kcInfo,    
	void					*reserved
);

/* This call locks that cache to prevent access until the MasterPassword is 
 * supplied.
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context with respect to the instance of open cache in it. 
 *
 * Return Values :
 */
int sscs_LockCache 
(
	void 					*ssHandle,
	uint32_t			ssFlags,
	void					*reserved
);

/* This unlocks previously locked cache using the MasterPassword  
 *
 * Parameters:
 *		ssHandle
 *			(IN) Handle returned by sscs_CacheOpenSecretStore function. This will have 
 *			context with respect to the instance of open cache in it. 
 *      masterPassword
 *
 * Return Values :
 */
int sscs_UnlockCache 
(
	void 				*ssHandle,
	uint32_t		ssFlags,
	SSCS_PASSCODE_T		*passcode,
	void				*reserved
);

int sscs_CacheWriteKey 
(
	void 				*ssHandle,
	uint32_t			 ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID,
	SSCS_SECRET_ID_T	*secretID,
    SS_UTF8_T           *key,
    uint32_t             keyLen,
    uint8_t             *val,
    int32_t              valLen,
	SSCS_PASSWORD_T		*epPassword,
	void				*reserved
);

int sscs_CacheWriteBinaryKey 
(
	void 				*ssHandle,
	uint32_t			 ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID,
	SSCS_SECRET_ID_T	*secretID,
    SS_UTF8_T           *key,
    uint32_t             keyLen,
    uint8_t             *val,
    uint32_t            valLen,
	SSCS_PASSWORD_T		*epPassword,
	void				*reserved
);

int sscs_CacheReadBinaryKey 
(
	void 				*ssHandle,
    uint32_t	         ssFlags,
	SSCS_KEYCHAIN_ID_T	*keychainID,
	SSCS_SECRET_ID_T    *secretID,
    SS_UTF8_T           *key,
    uint32_t             keyLen,
    uint8_t             *val,
    uint32_t            *valLen,
	SSCS_PASSWORD_T		*epPassword,
	uint32_t			*bytesRequired,
	void				*reserved
);

int32_t sscs_SetMasterPasscode
(
    void *ssHandle,
    SSCS_PASSCODE_T *passcode,
    void *reserved
);

int32_t sscs_SetMasterPassword
(
    void *ssHandle,
    SSCS_PASSWORD_T *password,
    SSCS_HINT_T *hint,
    void *reserved
);

int sscs_IsSecretPersistent 
(
	void 			*ssHandle,
	uint32_t		ssFlags,
	SSCS_KEYCHAIN_ID_T	*keyChainID,
	SSCS_SECRET_ID_T	*secretID,
	void			*reserved
);



#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif	/* _SSCS_CACHE_H */