|
|
//+----------------------------------------------------------------------------
//
// Copyright (C) 1996, Microsoft Corporation
//
// File: cacheapi.h
//
// Contents: The definitions of functions and structures which are used
// external to the core of this library.
//
// Functions:
//
// History: 8/28/96 JayH created
//
// Todo:
//
// Bugs:
//
//-----------------------------------------------------------------------------
#ifdef __cplusplus
extern "C" {#endif //__cplusplus
typedef DWORD HCACHE;typedef HCACHE FAR * LPHCACHE;typedef DWORD HFORMAT;//
// CACHE_TYPE is used to identify the type of cache entry being stored. Currently
// the only cache entry type is USERNAME_PASSWORD. This type uses a secret blob
// to hold the password, and does not store anything in the nonsecret blob.
//
typedef enum _CACHE_TYPE { CT_NONE, CT_USERNAME_PASSWORD} CACHE_TYPE;
//
// HFORMAT's for hashes are derived by concating two words which represent the
// authentication algorithm they are used for and the version of the hash algorithm
//
#define HFORMAT_DPA_HASH_1 0x00010001
#define HFORMAT_RPA_HASH_1 0x00020001
#define CR_SAVE_SECRET 0x00000001
#define CR_DELETE_PEERS 0x00000002
#define CL_STORED_CACHE 0x00000010
#define CL_CONFIRMED_CACHE 0x00000020
//+------------------------------------------------------------
//
// Function: OpenCommonCache
//
// Synopsis: This function opens the common cache and performs
// everything necessary to get it to work. That means if this
// is the first time it is being called, it will call
// InitCacheLibrary. This keeps a ref count.
//
// Arguments: szUserName -- Presently unused. This can be used to support
// the sharing of the cache between users.
// phCache -- The handle to the opened common cache is
// returned here.
// Returns: Nothing.
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT OpenCommonCache(LPTSTR szUserName, LPHCACHE phCache);
//+------------------------------------------------------------
//
// Function: CloseCommonCache
//
// Synopsis: This function closes the cache and decrements the ref count on
// it. If the reference count reaches zero, the library will be
// closed.
//
// Arguments: szUserName -- Presently unused. This can be used to support
// the sharing of the commmon cache between users.
// phCache -- The handle to the opened common cache is
// returned here.
// Returns: Nothing.
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT CloseCommonCache(HCACHE hCache);
//+------------------------------------------------------------
//
// Function: SetCacheEntry
//
// Synopsis: This function sets an entry in the cache. If the entry does
// not already exist, it will create the entry. It sets the entry
// in the persistent cache and the non-persistent cache, and it
// creates hashed versions of the secret for every hash secret
// format that it knows about.
//
// Arguments: hCache Handle of a valid, opened cache
//
// szEntryName The name of the entry, currently this must be
// this must be the username since that is the
// only supported form of cache entry.
//
// szListName This list of entries which that entry is valid
// within. Currently this must be the domain name
//
// ctCacheType The type of cache entry being used. This must
// be CT_USERNAME_PASSWORD.
//
// lpbSecretOpaque The secret information to be hashed before
// it is stored (Sssshhh!)
//
// dwSizeSecretOpaque The size of the secret information
//
// lpbOpaque The information which doesn't need to be hashed
//
// dwSizeOpaque The size of the opaque info
//
// fCacheReq The flags about how this should be cached. The
// only defined flag currently is CR_SAVE_SECRET
//
// fCacheLoc Allows the caller to specify where the cache
// should be saved to. It is a bitmask of
// CL_PERSISTENT and CL_NONPERSISTENT
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT SetCacheEntry(HCACHE hCache, LPTSTR szEntryName, LPTSTR szListName, CACHE_TYPE ctCacheType, LPBYTE lpbSecretOpaque, DWORD dwSizeSecretOpaque, LPBYTE lpbOpaque, DWORD dwSizeOpaque, DWORD fCacheReq, DWORD fCacheLoc);
//+------------------------------------------------------------
//
// Function: DeleteCacheEntry
//
// Synopsis: This function gets an entry in the cache. If the entry does
// not already exist, it returns failure. If the username
// entered into the function is null, the default user will be
// returned. Currently the default user is the only one in the
// cache. You can only get secret information in the hashed
// format.
//
// Arguments: hCache Handle of a valid, opened cache
//
// szEntryName The name of the entry to delete
//
// szListName The name of the list that entry is in
//
// ctCacheType The type of the entry
//
// fCacheLoc Allows the caller to specify where the cache
// should be deleted from. It is a bitmask of
// CL_PERSISTENT and CL_NONPERSISTENT
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT DeleteCacheEntry(HCACHE hCache, LPTSTR szEntryName, LPTSTR szListName, CACHE_TYPE ctCacheType, DWORD fCacheLoc);
//+------------------------------------------------------------
//
// Function: GetCacheEntry
//
// Synopsis: This function gets an entry in the cache. If the entry does
// not already exist, it returns failure. If the username
// entered into the function is null, the default user will be
// returned. Currently the default user is the only one in the
// cache. You can only get secret information in the hashed
// format.
//
// Arguments: hCache Handle of a valid, opened cache
//
// hFormat Handle of the format we wish to use
//
// szEntryName The name of the entry, currently this must be
// this must be the username since that is the
// only supported form of cache entry.
//
// szListName This list of entries which that entry is valid
// within. Currently this must be the domain name
//
// ctCacheType The type of cache entry being used. This must
// be CT_USERNAME_PASSWORD.
//
// lppbSecretOpaque Used to return the hashed secret. The
// caller must free this by calling the
// ReleaseBuffer function.
//
// lpdwSizeSecretOpaque returns he size of the secret data
//
// lppbOpaque Used to return the insecure information. The
// caller must free this by calling the
// ReleaseBuffer fucntion
//
// lpdwSizeOpaque Returns the size of the opaque info
//
// pfCacheReq Returns the flags about how this should be
// cached. The only defined flag currently is
// CR_SAVE_SECRET
//
// fCacheLoc Allows the caller to specify where the cache
// should be loaded from. It is a bitmask of
// CL_PERSISTENT and CL_NONPERSISTENT
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT GetCacheEntry(HCACHE hCache, HFORMAT hFormat, LPTSTR szEntryName, LPTSTR szListName, CACHE_TYPE ctCacheType, LPBYTE FAR *lppbSecretOpaque, LPDWORD lpdwSizeSecretOpaque, LPBYTE FAR *lppbOpaque, LPDWORD lpdwSizeOpaque, LPTSTR FAR *lpszEntryName, LPDWORD pfCacheReq, DWORD fCacheLoc);
//+------------------------------------------------------------
//
// Function: AllocateBuffer
//
// Synopsis: This function is used to allocate all memory in the cache
// library. This gives us a centralized way to optimize memory
// allocation. Note that classes might use a cpool.
//
// Arguments: dwSizeBuffer The size of the buffer to be allocated
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
LPBYTE AllocateBuffer(DWORD dwSizeBuffer);
//+------------------------------------------------------------
//
// Function: ReleaseBuffer
//
// Synopsis: This function will release the buffer. This API is exposed
// to the world so that we can allocate and return buffers and
// have some way to be rid of them.
//
// Arguments: lpbBuffer The buffer to be released
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT ReleaseBuffer(LPBYTE lpbBuffer);
//+------------------------------------------------------------
//
// Function: HashSecret
//
// Synopsis: This function will hash the secret for the caller. This
// is done so that the hashing funciton will not be implemented
// in multiple files.
//
// Arguments: lpbBuffer The buffer to be released
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT HashSecret(HFORMAT hFormat, CACHE_TYPE ctCacheType, LPBYTE lpbSecretBlob, DWORD dwSizeSecret, LPBYTE FAR * lppbHashedBlob, LPDWORD lpdwSizeHashedBlob);
//+------------------------------------------------------------
//
// Function: ChangeEntryName
//
// Synopsis: This function will change the name of an entry in a given
// list of a given cache type, for all formats in which it exists
//
// Arguments: lpbBuffer The buffer to be released
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT ChangeEntryName(HCACHE hCache, CACHE_TYPE ctCacheType, LPTSTR szStartEntryName, LPTSTR szEndEntryName, LPTSTR szListName, DWORD fCacheReq);
//+------------------------------------------------------------
//
// Function: ConfirmCacheEntry
//
// Synopsis: This function will copy an entry in the stored cache to
// the confirmed cache, for all hashed secret formats that
// the cache type supports.
//
// Arguments: hCache Handle of a valid, opened cache
//
// szEntryName The name of the entry, currently this must be
// this must be the username since that is the
// only supported form of cache entry.
//
// szListName This list of entries which that entry is valid
// within. Currently this must be the domain name
//
// ctCacheType The type of cache entry being used. This must
// be CT_USERNAME_PASSWORD.
//
// History: Jayhoo Created 8/28/1996
//
//-------------------------------------------------------------
HRESULT ConfirmCacheEntry(HCACHE hCache, LPTSTR szEntryName, LPTSTR szListName, CACHE_TYPE ctCacheType, DWORD fCacheReq);
#ifdef __cplusplus
}#endif //__cplusplus
|
