Main Page | Data Structures | File List | Data Fields | Globals

WFU.h File Reference

This is the public interface to the libwfu escrow system. More...

#include "libwfu.h"
#include "common_parameters.h"
#include "common_error.h"

Go to the source code of this file.

Data Structures

struct  wfu_data
 A data package used by many functions. More...
struct  wfu_uvid
 Structure that uniquely identifies a volume. More...

Functions

wfu_uvid * WFU_lib_prepare_uvid (unsigned char *username, unsigned char *salt, unsigned char *timestamp)
 Creates a Unique Volume IDentifier (UVID) used to uniquely identifier this volume.
int WFU_lib_escrow (char *username, char *password, struct wfu_uvid *uvid, struct wfu_data *crypto)
 This function will escrow the Crypto information indexed by the Unique Volume IDentifyer for the Username.
int WFU_lib_verify_uvid (struct wfu_uvid *uvid)
 Will indicate whether a volume on escrow is indexed by the Unique Volume IDentifier.
wfu_data * WFU_lib_reclaim_keys (char *username, char *passwd, int pk)
 This function will return the key information for the volume having the specified escrow key value.
wfu_line_array * WFU_lib_query_salt (char *username, char *password, struct wfu_data *salt)
 Will return a list of key information for the volumes having the specified salt.
wfu_line_array * WFU_lib_query_user (char *username, char *password, char *query_user)
 This function will return the key information for the volumes with the specified username.
int WFU_lib_test_ssl ()
 The function should only be used by developers for testing purposes.

Detailed Description

This is the public interface to the libwfu escrow system.

The WFU.h file contains the essential interface functions used for the key escrow and restore process.

The Linux client will also require the WFU_parse_config(const char*) and WFU_get_config_path() to aid with the configuration of library parameters.

Additional functions potentially used by an escrow client: WFU_is_error(), WFU_error_first(), WFU_error_next() and WFU_get_hello_message()

Function Documentation

int WFU_lib_escrow (  char *  username,
char *  password,
struct wfu_uvid *  uvid,
struct wfu_data *  crypto
) 
 

This function will escrow the Crypto information indexed by the Unique Volume IDentifyer for the Username.

Parameters:
username is the username of the individual escrowing the information.
password for the username.
uvid is pointer to a wfu_uvid struct containing the Unique Volume IDentifier.
crypto is a pointer to a wfu_data structure containing the crypto info data.
See also:
WFU_lib_prepare_uvid()
Return values:
0 A value of 0 indicates the escrow was unsuccessful.
<0 A negative value indicates a fatal error such as network connectivity or SSL issue.
>0 Indicates success. The return value indicates the key number given to this entry.
Note:
wfu_error_no will be set under the following conditions:

WFU_ERR_NULL_PTR, WFU_ERR_PARAMETER will indicate problems with the parameters.

WFU_ERR_SSL will indicate a problem with the SSL connection.

WFU_ERR_LOGIN will indicate the login process was unsucessful.

WFU_ERR_CRYPT will indicate a problem with encryption routines.

WFU_ERR_KEY_STORAGE will indicate a problem with the storage of the keys.

See also:
Other functions called by this function: WFU_client_ssl_connect(), WFU_client_authenticate(), WFU_SSL_read_int(), WFU_SSL_write_int(), WFU_client_public_key(), WFU_client_store_keys(), WFU_rsa_encrypt(), WFU_SSL_write_wfu_data()
Example:
 struct wfu_data src;

 src.text = (unsigned char*) cryptInfo;
 src.len = sizeof(CRYPTO_INFO);

 pk_value = WFU_lib_escrow(username, password, uvid, &src);

struct wfu_uvid* WFU_lib_prepare_uvid (  unsigned char *  username,
unsigned char *  salt,
unsigned char *  timestamp
) 
 

Creates a Unique Volume IDentifier (UVID) used to uniquely identifier this volume.

The combination of timestamp, username and salt is considered to be sufficient for a unique identifier. (An MD5 of the salt can also be used.)

In order for this to be non-unique, the same user would have to create two filesystems during the same second. Both of these will have to be created with the identical random 64 bytes.

Note:
In order to improve security, the server can be compiled with the MD5SALT macro defined. This will cause only an MD5 sum of the salt to be stored in the database. This will increase the probability of a "collision", but this is not likely. You can choose to use the salt or the MD5 sum.
Parameters:
username is the username of the individual for whom the query is made.
salt The salt is the first 64 bytes of the TrueCrypt volume. The salt parameter should point to an array of at lease 64 bytes. Exactly 64 bytes will be read from this memory reference.
timestamp The timestamp is a pointer to an unsigned long long structure containing the header creation time. Exactly 8 bytes will be read from this memory reference.
Return values:
Pointer A pointer to a dynamically allocated wfu_uvid structure is returned upon success.
NULL A NULL value is returned upon failure.
Note:
The the memory referenced by the return value must be freed.

wfu_error_no will be set under the following conditions:

WFU_ERR_PARAMETER will indicate either the username is too long, the salt is null or if the timestamp pointer is null.

WFU_ERR_MEMORY will indicate a call to malloc failed.

struct wfu_line_array* WFU_lib_query_salt (  char *  username,
char *  password,
struct wfu_data *  salt
) 
 

Will return a list of key information for the volumes having the specified salt.

This function will authenticate against the server and send the server a wfu_data structure containing a salt. The server will constructs a list of possible escrow entries associated with this salt. Each entry of the list includes the escrow date, key escrow number and username. This function will return a pointer to a wfu_line_array structure containing this list.

The user must also be granted access to use this function. The use of this call is restrictd by WFU_get_admin_subnet_mask().

Parameters:
username is the username of a user authorized to perform retrievals of key information.
password is the password for this username.
salt is a pointer to a wfu_data structure that contains the salt information.
Return values:
pointer A pointer to a wfu_line_array structure containing the key information. It is indended that this list be displayed to the user. It is not formatted for parsing.
NULL An error occurred.
Note:
The the memory referenced by the return value must be freed using WFU_free_wfu_line_array().

When a return value is NULL, the wfu_error_no may be set to the following:

WFU_ERR_NULL_PTR, WFU_ERR_PARAMETER indicates a problem with the username, password or salt parameters.

WFU_ERR_SSL, WFU_ERR_SSL_RW will indicate a problem with the SSL connection.

WFU_ERR_LOGIN will indicate unsuccessful authentication.

WFU_ERR_ACCESS will indicate the user is not authorized to perform this operation.

struct wfu_line_array* WFU_lib_query_user (  char *  username,
char *  password,
char *  query_user
) 
 

This function will return the key information for the volumes with the specified username.

The function sends the server a username. The server will constructs a list of possible escrow entries associated with this username. Each entry of the list includes the escrow date, key escrow number and username. This function will return a pointer to a wfu_line_array structure containing this list.

The user must also be granted access to use this function. Furthermore, the use of this call is restrictd by WFU_get_admin_subnet_mask().

Parameters:
username is the username of a user authorized to perform retrievals of key information.
password is the password for this username.
query_user is a pointer to the username being queried.
Return values:
pointer A pointer to a wfu_line_array structure containing the key information. It is indended that this list be displayed to the user. It is not formatted for parsing.
NULL An error occurred.
Note:
The the memory referenced by the return value must be freed using WFU_free_wfu_line_array().

When a return value is NULL, the wfu_error_no may be set to the following:

WFU_ERR_NULL_PTR, WFU_ERR_PARAMETER indicates a problem with the username, password or salt parameters.

WFU_ERR_SSL, WFU_ERR_SSL_RW will indicate a problem with the SSL connection.

WFU_ERR_LOGIN will indicate unsuccessful authentication.

WFU_ERR_ACCESS will indicate the user is not authorized to perform this operation.

struct wfu_data* WFU_lib_reclaim_keys (  char *  username,
char *  passwd,
int  pk
) 
 

This function will return the key information for the volume having the specified escrow key value.

The user must authenticate over the SSL and must be granted access to use this function. The data sent from the server is encrypted, so the decryption keys must be present on the system performing this operation. Furthermore, the use of this call is restrictd by WFU_get_admin_subnet_mask().

Parameters:
username is the username of a user authorized to perform retrievals of key information.
passwd is the password for this username.
pk is the key escrow number of the keys to be retrieved. (The name pk indicates primary key)
Return values:
pointer A pointer to a wfu_data structure containing the decrypted key information.
NULL An error occurred.
Note:
The the memory referenced by the return value must be freed using WFU_free_wfu_data().

When a return value is NULL, the wfu_error_no may be set to the following:

WFU_ERR_NULL_PTR, WFU_ERR_PARAMETER indicates a problem with the username, password or pk parameters.

WFU_ERR_SSL, WFU_ERR_SSL_RW will indicate a problem with the SSL connection.

WFU_ERR_LOGIN will indicate unsuccessful authentication.

WFU_ERR_KEY_NOT_FOUND will indicate the key was not found on the server.

WFU_ERR_CRYPT Error with the decryption process (Are the keys on this system?)

WFU_ERR_ACCESS will indicate the user is not authorized to perform this operation.

See also:
Other functions called by this function: WFU_client_ssl_connect(), WFU_client_authenticate(), WFU_restore_reclaim_keys(), WFU_SSL_read_int(), WFU_SSL_write_int(), WFU_SSL_read_wfu_data(), WFU_rsa_decrypt()

int WFU_lib_verify_uvid (  struct wfu_uvid *  uvid  ) 
 

Will indicate whether a volume on escrow is indexed by the Unique Volume IDentifier.

Parameters:
uvid is pointer to a wfu_uvid struct containing the Unique Volume IDentifier.
Return values:
0 A value of 0 indicates the uvid was not found on the server.
>0 A positive return value indicates that the keys are already stored for this volume. The return value is the escrow key value. The wfu_error_no will contain the error WFU_ERR_KEY_REDUNDANT.
<0 A negative value indicates a fatal error such as network connectivity or SSL issue.
Note:
wfu_error_no will be set under the following conditions:

WFU_ERR_KEY_REDUNDANT indicates the key is already found on the server. To store it again would be redundant.

WFU_ERR_NULL_PTR, WFU_ERR_PARAMETER will indicate problems with the parameters.

WFU_ERR_SSL will indicate a problem with the SSL connection.

See also:
Other functions called by this function: WFU_client_ssl_connect(), WFU_client_verify_uvid(), WFU_SSL_read_int(), WFU_SSL_write_int(), WFU_SSL_write_wfu_data()
Example:
 struct wfu_uvid *uvid = NULL;
 int pk_value = 0;

 uvid = WFU_lib_prepare_uvid( (unsigned char*) username,
                              (unsigned char*) cryptInfo->key_salt,
                              (unsigned char*) &(cryptInfo->header_creation_time));

 pk_value = WFU_lib_verify_uvid(uvid);

 if (WFU_is_error(WFU_ERR_KEY_NOT_FOUND))
     printf("Escrow is necessary");
 else if (WFU_is_error(WFU_ERR_KEY_REDUNDANT))
     printf("The keys are already escrowed.");

Generated on Wed Oct 10 12:38:21 2007 for WFUCrypt by  doxygen 1.3.9.1