CASA/include/micasa.h

/**************************************************************************
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	*/