|
|
/* NO_MAPI - defined for lhutil to get some apis that
* do not use mapi -scousens */
#ifndef __AWSEC_H__
#define __AWSEC_H__
#ifdef __cplusplus
extern "C" {#endif
#ifndef __FAXOPT_H__
/* **** Special return values for functions below **** */
#define KEY_ADD 1
#define KEY_DEL 2
#define KEY_LOC 3
#define KEY_FND 4
/* The following are return codes from functions which say they return SIG_* as
return values */
#define SIG_SUCCESS 0 /* Operation succeeded */
#define SIG_BADINFILE 1 /* Bad input file */
#define SIG_BADOUTFILE 2 /* Bad output file */
#define SIG_FORGED 3 /* Signature does not match keyset */
#define SIG_AUTHENTIC 4 /* Signature matches keyset */
#define SIG_NOTVERIFIED 5 /* No key found, so can not verify signature */
#define SIG_BADPASS 6 /* Bad password or incorrect session handle */
#define SIG_NOMEM 7 /* Out of memory error */
#define SIG_ABORT 8 /* Callback caused abort */
#define SIG_BUSY 9 /* Concurrent job already running */
/* The following are return codes from functions which say they return SEC_* as
return values */
#define SEC_SUCCESS 0 /* Operation succeeded */
#define SEC_BADFILE 1 /* File cannot be opened */
#define SEC_KEYTOOSMALL 2 /* Keybuffer too small */
#define SEC_NOMATCH 3 /* No key of requested type found for
specified keyholder */#define SEC_FILECORRUPT 4 /* File integrity check failed */
#define SEC_NOMEMORY 5 /* Aborted due to low memory conditions */
#define SEC_BADPTR 6 /* An invalid pointer was passed in */
#define SEC_USERABORT 7 /* User aborted operation */
#define SEC_BADPASS 8 /* Invalid password */
#define SEC_ABORT 9 /* Callback caused abort */
#define SEC_BUSY 10 /* Concurrent job already running */
#define SEC_WRONGKEY 11 /* Wrong key used in decryption */
#define SEC_NEWERVERSION 12 /* File generated by newer version of software,
and we cannot decrypt it */#define SEC_NODISKSPACE 13 /* Cannot allocate neccessary disk space for
main or temporary file */#define SEC_ALREADYLOGGED 14 /* User is already logged in, so certain
account changes cannot be made */#define SEC_UNDERPRIV 15 /* User does not have sufficient priviledge */
#define SEC_INITFAIL 16 /* Can't init the security system */
#define SEC_ALREADYTHERE 17 /* Key already exists on add or rename */
#endif
/* **** Callback parameter definitions for functions below **** */
/* return values: 0 = success, 1 = End of Job, 2 = failure *//* A function of type ReadCB allocates a buffer (of arbitrary size), and then
fills it from handle hf (passed in when the callback was set up) */typedef WORD CALLBACK ReadCB(DWORD hf, LPBUFFER FAR *buf);
/* return values: 0 = success, 2 = failure *//* A function of type WriteCB writes the buffer passed in (arbitrary size) out
to handle hf, and then frees the buffer */typedef WORD CALLBACK WriteCB(DWORD hf, LPBUFFER buf);
/* return values: 0 = continue, 1 = abort *//* A function of type SigCB is called with information about a signature on a
file. Each time it is called, it is passed the handle it gave when the callback was set up (hf), a username (username), and a result (result). The result can be SIG_FORGED (key found, but signature does not match key), SIG_AUTHENTIC (key found, and signature matches key), or SIG_NOTVERIFIED (key not found, and therefore cannot be authenticated) */typedef WORD CALLBACK SigCB(DWORD hf, LPSTR username, WORD result);
/* return 0 for continue, 1 for abort. *//* A function of type listcallback is called with information about a key. For
each key, a pointer to the key is returned (key), along with its size (keysize), and the userid for whom the key is for. Also, a handle is passed back which was passed in when the callback was set up originally */typedef WORD (CALLBACK *listcallback)(BYTE FAR *key, WORD keysize, LPSTR userid, DWORD handle);
/* **** Special Purpose API's **** */
/* To be called by UISHELL whenever the machine phone number has changed */void WINAPI SecNewPhoneNumber(void);
#ifndef __AWGLOBAL_H__
/* **** Linearize/Delinarize API's **** */
/* Calls to encrypt and decrypt messages - for the linearizer only */
#ifndef NO_MAPI
/* Initializes key encryption. Takes userid and mapi session handle of user
to encrypt for. Also takes userid of destination user. Returns instance, which should be used on calls to EncryptData, as well as fills in buf with header information. EncryptInit should be called with buf NULL first, and it will return the minimum needed size for the buffer. Buf should then be allocated to be at least this size. Returns value of type SEC_* if buf is not NULL. */WORD WINAPI EncryptInit(LPSTR userid, LPSOSSESSION lpSess, LPSTR destuser, LPDWORD instance, LPBUFFER buf);
/* Takes current lpSess and inst from an EncryptInit call. Fills in a pointer
(buf) and a length (len) of an IFMemAlloc'ed block of memory. This memory can be cached and restored via EncryptRestore for delayed encryption where the user can log out. The header from EncryptInit should be stored, along with the Mapi session handle and the buffer returned. Returns value of type SEC_* */WORD WINAPI EncryptSave(LPSOSSESSION lpSess, DWORD inst, LPBYTE FAR *buf, LPWORD len);
/* Takes a pointer to a buffer and the buffer's length, as returned from
EncryptSave, along with a (now possibly expired/invalid) lpSess. Returns an inst suitable for passing to EncryptData. Returns value of type SEC_* */WORD WINAPI EncryptRestore(LPDWORD inst, LPSOSSESSION lpSess, LPBYTE buf, WORD len);
/* Encrypts data using key encryption. Takes a mapi session handle of user to
encrypt for, as well as instance (inst) returned by EncryptInit. Converts buf in place from plaintext to encrypted text. After the final packet, a buffer of metatype END_OF_JOB should be passed in. Returns value of type SEC_* */WORD WINAPI EncryptData(LPSOSSESSION lpSess, DWORD inst, LPBUFFER buf);
/* Initializes key decryption. Takes userid and mapi session handle of user
to decrypt for. Also takes userid of source user. Returns instance, which should be used on calls to DecryptData. Takes a buffer which should be at least 8K (from message to decrypt), or the whole message if it is less than 8K, and returns a smaller buffer (of size >= 0, since header is stripped off). Note that the buffer is the same, but the valid data area will be smaller. Returns value of type SEC_* */WORD WINAPI DecryptInit(LPSTR userid, LPSOSSESSION lpSess, LPSTR srcuser, LPDWORD instance, LPBUFFER buf);
/* Decrypts data using key encryption. Takes a mapi session handle of user to
decrypt for, as well as instance (inst) returned by DecryptInit. Converts buf in place from encrypted to plaintext. After the final packet, a buffer of metatype END_OF_JOB should be passed in. Returns value of type SEC_*. */WORD WINAPI DecryptData(LPSOSSESSION lpSess, DWORD inst, LPBUFFER buf);#endif /* NO_MAPI */
/* Initializes password encryption. Takes pwd as the password to encrypt with.
Returns instance, which should be used on calls to SimpleEncryptData, as well as fills in buf with header information. SimpleEncryptInit should be called with buf NULL first, and it will return the minimum needed size for the buffer. Buf should then be allocated to be at least this size. Returns value of type SEC_* if buf is not NULL. */WORD WINAPI SimpleEncryptInit(LPSTR pwd, LPDWORD instance, LPBUFFER buf);
/* Takes inst from a SimpleEncryptInit call. Fills in a pointer (buf) and a
length (len) of an IFMemAlloc'ed block of memory. This memory can be cached and restored via SimpleEncryptRestore for delayed encryption where the user can log out. The header from EncryptInit should be stored, along with the returned buffer. Returns value of type SEC_* */WORD WINAPI SimpleEncryptSave(DWORD inst, LPBYTE FAR *buf, LPWORD len);
/* Takes a pointer to a buffer and the buffer's length, as returned from
SimpleEncryptSave, along with a (now possibly expired/invalid) lpSess. Returns an inst suitable for passing to SimpleEncryptData. Returns value of type SEC_* */WORD WINAPI SimpleEncryptRestore(LPDWORD inst, LPBYTE buf, WORD len);
/* Encrypts data using password encryption. Takes an instance (inst) returned
by EncryptInit. Converts buf in place from plaintext to encrypted text. After the final packet, a buffer of metatype END_OF_JOB should be passed in. Returns a value of type SEC_*. */WORD WINAPI SimpleEncryptData(DWORD inst, LPBUFFER buf);
/* Initializes password decryption. Takes password to use for decryption.
Returns instance, which should be used on calls to SimpleDecryptData. Takes a buffer which should be used on calls to DecryptData. Takes a buffer which should be at least 8K (from message to decrypt), or the whole message if it is less than 8K, and returns a smaller buffer (of size >= 0, since header is stripped off). Note that the buffer is the same, but the valid data area will be smaller. Returns value of type SEC_* */WORD WINAPI SimpleDecryptInit(LPSTR pwd, LPDWORD instance, LPBUFFER buf);
/* Decrypts data using password decryption. Takes an instance (inst) returned
by SimpleDecryptInit. Converts buf in place from encrypted to plaintext. After the final packet, a buffer of metatype END_OF_JOB should be passed in. Returns value of type SEC_*. */WORD WINAPI SimpleDecryptData(DWORD inst, LPBUFFER buf);
/* Call to start hashing bft header. Returns 0 for failure, or non-zero
context for passing to SendBFTHash and DoneBFTHash */DWORD WINAPI StartBFTHash(void);
/* Pass in context from StartBFTHash, and buffer with length */void WINAPI SendBFTHash(DWORD Context, LPBYTE buf, WORD len);
/* Pass in context after done calling SendBFTHash. If salt points to 3 bytes
which are 0, a salt is generated and returned, else the salt is used. Key must be 5 bytes, from which the actual key is derived. Res must be 16 bytes long to receive hashed encrypted result. */void WINAPI DoneBFTHash(DWORD Context, LPBYTE salt, LPBYTE res);
/* **** Signature API's **** */
#ifndef NO_MAPI
/* Takes a read and write callback, and handles to pass them. If the file is
already signed (YOU MUST CHECK THE EXTENSION), you must pass the size of the header (from SignFileHeaderSize) in the HeaderSize field. This value will currently always be changed to 0 upon return. The new header will be written out to the callback. To make the signed file, you prepend the data written to the callback to the original file, unless it was already signed, in which case you prepend it to the file inside the signed file (based on SignFileHeaderSize). Also takes a session handle for the user who is signing the file, along with the username. Returns SIG_*. */WORD WINAPI SignFile(ReadCB *readCB, DWORD readHand, WriteCB *writeCB, DWORD writeHand, LPSTR userid, LPSOSSESSION lpSess, LPSTR filename, LPWORD HeaderSize);
/* Extracts file from signed file. Takes a read and write callback and handles
for them. Reads the file from the read callback, and writes it out to the write callback. Returns SIG_*. */WORD WINAPI UnSignFile(ReadCB *readCB, DWORD readHand, WriteCB *writeCB, DWORD writeHand);
/* Obtains the headersize and filename of a signed file. Sets headersize to be
the size of the header of signed file, and fills filename with 8.3 filename from a signed file obtained by reading from the callback. Returns 0 for success, 1 for failure, 2 for not a signed file. */WORD WINAPI SignFileHeaderSize(ReadCB *readCB, DWORD readHand, LPWORD headersize, LPSTR filename);
/* Calls signature callback for each signature in the file obtained by the
read callback. Reads file from the read callback (SEE NOTE), and then calls the sig callback once for each signature (or until the callback signals to stop through its return value. If filename is non-null, also returns the 8.3 filename in the buffer pointed to by filename. Returns SIG_*. */
/* NOTE: Unlike the usual semantics, the read callback should not simply return 1
to indicate EOF. Instead, it should allocate an empty buffer and return 0, then return 1 on the next call. -RajeevD */WORD WINAPI GetSignatures(LPSTR userid, LPSOSSESSION lpSess, ReadCB *readCB, DWORD readHand, SigCB *sigCB, DWORD sigHand, LPSTR filename);
/* **** Public key API's **** */
/* Lists all public keys in an exported file, given that the read callback
returns data from the unsigned portion of a signed key file, or from an unsigned key file. Calls the read callback to read the file, and then calls the listcallback to enumerate the keys, passing it the listhandle with each key. Returns SEC_*. */WORD WINAPI ListKeysInFile(ReadCB FAR *readCB, DWORD readHand, listcallback lcb, DWORD listhandle);
/* Lists all keys in user database for having mapi session lpSess for user
userid. Calls the listcallback to enumerate the keys, also passing the listhandle with each key. Passing in a NULL for lpSess returns keys in the global key list (userid is ignored). Returns SEC_*. */WORD WINAPI ListKeys(LPSTR userid, LPSOSSESSION lpSess, listcallback lcb, DWORD listhandle);
/* Creates a file header for an unsigned key file of numkeys public keys.
Writes the header appropriate for a keyfile of numkeys keys out to the write callback, passing it writeHand as well. Should be called in order to create a key file, before using AddPubKeyToFile to actually add the keys. Returns SEC_*. */WORD WINAPI CreatePubKeyFile(WriteCB FAR *writeCB, DWORD writeHand, WORD numkeys);
/* Appends a key to keyfile created with KeyFileHeader. Must be called exactly
the number of times specified by the numkeys parameter to CreatePubKeyFile. Takes a key and a keysize, as well as the userid of the user corresponding to the key. Calls the writecallback to write to append to a file that key. After all keys are written to the file, it can be closed and is now a valid public key file. This file can be signed to create a signed key file. Returns SEC_*. */WORD WINAPI AddPubKeyToFile(WriteCB FAR *writeCB, DWORD writeHand, BYTE FAR *key, WORD keysize, LPSTR userid);
/* Retrieves public key from a unsigned key file. Returns key and size of key
for user corresponding to userid, if it can be found. Reads through read callback. Key must point to at least 1024 bytes of memory. If file is signed, callback should return bytes starting from offset in file after signed header size (from SignFileHeaderSize). Returns SEC_*. */WORD WINAPI GetPubKeyFromFile(ReadCB *readCB, DWORD readHand, BYTE FAR *key, WORD FAR *keysize, LPSTR userid);
/* Adds key for targetuserid into registry of userid with session handle
lpSess. Key should point to a key of size keysize, for user specified by userid. Returns SEC_*. */WORD WINAPI AddPubKey(LPSTR userid, LPSOSSESSION lpSess, BYTE FAR *key, WORD keysize, LPSTR targetuserid);
/* Adds key for targetuserid into global key list. lpSess must be the session
handle for superuser userid. Key should point to a key of size keysize, for user specified by targetuserid. Returns SEC_*. */WORD WINAPI AddGlobalPubKey(LPSTR userid, LPSOSSESSION lpSess, BYTE FAR *key, WORD keysize, LPSTR targetuserid);
/* Retrieves key for searchuserid from registry of userid with session handle
lpSess. Key must point to at least 1024 bytes of memory. Actual size is returned in keysize. If lpSess is NULL, reads from the global key list (userid is ignored). Returns SEC_*. */WORD WINAPI GetPubKey(LPSTR userid, LPSOSSESSION lpSess, BYTE FAR *key, WORD FAR *keysize, LPSTR searchuserid);
/* Deletes key of targetuserid from registry of userid with session handle
lpSess. Returns SEC_*. */WORD WINAPI DelPubKey(LPSTR userid, LPSOSSESSION lpSess, LPSTR targetuserid);
/* Deletes key of targetuseri from global key list. Userid must be a superuser
with session handle lpSess. Returns SEC_*. */WORD WINAPI DelGlobalPubKey(LPSTR userid, LPSOSSESSION lpSess, LPSTR targetuserid);
/* Returns 1 if a public key exists for 'name' in key registry belonging to
user 'userid' with session handle 'lpSess', or 0 otherwise. If NULL is passed in for lpSess, checks the global key list (and userid is ignored). */BOOL WINAPI ExistsPubKey(LPSTR userid, LPSOSSESSION lpSess, LPSTR name);
/* Returns 1 if a public key can be found using fuzzy matching as used in
decrypt and encrypt for 'name' in key registry belonging to user 'userid' with session handle 'lpSess', or 0 otherwise. If NULL is passed in for lpSess, checks the global key list (and userid is ignored). */BOOL WINAPI ExistsFuzzyPubKey(LPSTR userid, LPSOSSESSION lpSess, LPSTR name);
/* Creates new key set (public and private) for userid logged in with 'lpSess'.
Returns SEC_*. */WORD WINAPI MakeNewKeySet(LPSTR userid, LPSOSSESSION lpSess);
/* For use when a user forgets his password. Takes lpSess of userid who is a
superuser, and the username of the user who has forgotten his password (targetuser). Sets their password to be newuserpwd, and gives them a new set of keys. targetuser should not be logged in. Returns SEC_*. */WORD WINAPI ReinitKeyAndPassword(LPSTR userid, LPSOSSESSION lpSess, LPSTR targetuser, LPSTR newuserpwd);
/* For use when a user wants to change his password. Takes lpSess of userid
who wants to change his password, along with old and new password. Returns SEC_*. */WORD WINAPI ChangePassword(LPSTR userid, LPSOSSESSION lpSess, LPSTR oldpass, LPSTR newpass);
/* Exports private key set (password encrypted) through callbacks. Writes out
encrypted (with login password) file through write callback, which contains the user's private and public keys. This file can be read back with ImportPrivateKeys. Returns SEC_*. */WORD WINAPI ExportPrivateKeys(LPSTR userid, LPSOSSESSION lpSess, WriteCB FAR *writeCB, DWORD writeHand);
/* Attemps to import private and public key for userid with session lpSess,
using password passed in to decrypt, reading file through read callback. Returns SEC_*. */WORD WINAPI ImportPrivateKeys(LPSTR userid, LPSOSSESSION lpSess, ReadCB FAR *readCB, DWORD readHand, LPSTR password);
/* Removes keyset for a user */WORD WINAPI DeleteKeySet(LPSTR userid, LPSOSSESSION lpSess);
/* Returns 1 if a user has a key set, else returns 0 */WORD WINAPI HasPrivateKey(LPSTR userid, LPSOSSESSION lpSess);
/* Places 154 bytes into screendata array for displaying key passed in.
screendata should be displayed as 14 groups of 11 characters. Only alphanumerical characters will be returned in screendata. It is not null-terminated, or delimited in any way - just 154 characters. Returns 0 on success, or 1 if the key is invalid. */WORD WINAPI GetDisplayableKey(BYTE FAR *key, BYTE FAR *screendata);
/* Converts keyinput into key for userid. Keyinput is 154 bytes (only valid
characters are 2..9, A..H, J..N, P..Z). Returns 0 for success, or group which is invalid if the key is not valid (ie: 1 for 1st 11 characters, etc...). If 15 is returned, there is an error, but the box number cannot be determined (should never happen, barring a malicious user trying to make it happen). If 0 is returned, fills in key and keysize. Key must point to at least 1024 bytes of memory. */WORD WINAPI BuildKey(BYTE FAR *keyinput, BYTE FAR *key,WORD FAR *keysize);
/* **** Generic API's **** */
/* Returns a random DWORD */DWORD WINAPI RandDWord(void);
/* **** Mapi API's **** */
HRESULTSOS WINAPI ValidateUserLogin(LPSTR lpszname, LPSTR lpszPassword, DWORD FAR *lpdwSecurityHandle);
HRESULTSOS WINAPI UnvalidateUserLogin(LPSOSSESSION lpSess);
HRESULTSOS WINAPI CreateSecureUser(LPSTR lpszName, LPSTR lpszPassword);
HRESULTSOS WINAPI DeleteSecureUser(LPSTR lpszName);
#endif /* NO_MAPI */
#endif
#ifdef __cplusplus
} /* extern "C" */#endif
#endif /* __AWSEC_H__ */
|
