USB API Reference

You can use the USB API to write applications that can interact with the HSM via the card USB port:

This functionality can include:

>wrapping of PKCS objects and storing them on a USB flash memory drive

>Performing backup of SMFS stored key (non-PKCS keys)

The USB API works with your custom FM to enable the desired functionality.

NOTE The ProtectServer USB API has been tested and validated with a representative sample of common USB memory drives. Thales cannot guarantee compatibility with all available brands/models.

This chapter contains the following sections:

>USB File System

>Data Structures

>Example Usage

>Function Descriptions

USB File System

The file system that the API creates on the USB memory drive is structured as follows:

The memory block size is determined automatically and has the most common value of 512 octets.

><DataLen> and <LabelLen>: These fields have a uint32 data type and they are stored in the USB memory as Big Endian values.

><FSLabel>: a 0-terminated string with a maximum length of 32 bytes.

Data Structures

The following two data structures are used in the FM USB API:

typedef struct _capacity {
        uint32_t max_lba_msb;    //used for 'Read Capacity 16'. Contains MSB of max block number.
        uint32_t max_lba;        //max number of logical block on the device for 'Read Capacity 10' or LSB of max number of logical block for 'Read Capacity 16'.
        uint32_t block_size;
        uint32_t device_size;    //Contains device size in Gb. 32 bits are capable to hold the capacity of 4 Gb.
} capacity_t;



typedef struct _dev_properties {
        uint16_t vendorId;
        uint16_t productId;
        uint8_t endpoint_in;
        uint8_t endpoint_out;
} dev_properties_t;

Example Usage

Currently, one application of the USB API is supported. The following scenario assumes that cryptographic object A exists on the HSM token.

To wrap object A from the HSM token to a USB memory drive

1.Create wrapping key B using BPE.

2.Wrap object A with wrapping key B.

3.Copy wrapped key to USB memory drive using the FM USB API calls.

4.[Optional] Destroy wrapping key B and object A on the HSM token.

To restore the source object A to the token

1.Read wrapped object A from the USB memory drive.

2.Create a new wrapping key B with BPE (or use existing key if it was never deleted).

3.Unwrap wrapped object A on the HSM token.

Function Descriptions

Functions included in this reference are:

This chapter also contains a list of vendor-defined error codes that can be produced by the USB API:

>USB API Vendor-Defined Error Codes

USBFS_Close

Writes the header from the HSM memory back to the USB file system.

Synopsis

int USBFS_Close(
    void *handlev, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`dp`	Structure
`handlev`	Device handle
`header`	Pointer to file system block 0

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_Destroy

Destroys the existing USB file system, including label and size.

Synopsis

int USBFS_Destroy(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`dp`	Structure
`handlev`	Device handle
`header`	Pointer to file system block 0

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_Finalize

Finalizes the USB API sequence.

This is the last function required in any sequence of USB-related calls. It frees context, device handler, attaches the kernel driver if required, and frees any memory that was allocated for the FS header.

Synopsis

int USBFS_Finalize(
    void *ctx, 
    void *handlev, 
    int *kernelDriverAttachedFlag, 
    uint8_t **header
);

Input Parameters

Parameter	Description
`ctx`	Current context
`handlev`	Device handle
`header`	Header string
`kernelDriverAttachedFlag`	If the kernel driver was attached before running the operation, this value will be TRUE.

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_GetInfo

Returns the USB file system label and the length of the stored data in bytes.

Synopsis

int USBFS_GetInfo(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint32_t *dataLen, 
    uint8_t *label, 
    uint8_t *header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`dataLen`	Length of the data string to follow
`dp`	Structure
`handle`	Device handle
`header`	Pointer to file system block 0
`label`	File system label

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_Init

Initializes the USB sub-system and returns the USB handle.

This is the first function required in any sequence of USB-related calls. It returns context, USB handler, properties and capacity structures, and the "Kernel Driver attached" flag (which indicates whether the kernel driver should be attached at the end of the execution).

Synopsis

int USBFS_Init(
    void *ctxv, 
    void **handlev, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    int *kernelDriverAttachedFlag
);

Input Parameters

Parameter	Description
`cap`	Capacity
`ctxv`	Current context
`dp`	Structure
`handlev`	Device handle
`kernelDriverAttachedFlag`	If the kernel driver was attached before running the operation, this value will be TRUE.

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_New

Creates a new, empty file system.

This function allocates space for the file system header, which contains only label length and label fields.

Synopsis

int USBFS_New(
    void *handle, 
    char * label, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`dp`	Structure
`handle`	Device handle
`header`	Pointer to file system block 0
`label`	File system label

Input Requirements

The USBFS library has been initialized with USBFS_Init(), and there is no current existing file system.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes. If a file system already exists, CKR_USB_INITIALIZED is returned. Use USB_Destroy() first to erase the current file system.

USBFS_Open

Reads the header into the HSM memory.

Synopsis

int USBFS_Open(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`dp`	Structure
`handle`	Device handle
`header`	Pointer to file system block 0

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_ReadData

Reads specified number of bytes from the USB file system to the HSM memory.

Synopsis

int USBFS_ReadData(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *data, 
    uint32_t *dataLen, 
    uint8_t *header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`data`	Data string
`dataLen`	Length of the data string to follow
`dp`	Structure
`handle`	Device handle
`header`	Pointer to file system block 0

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USBFS_WriteData

Writes the specified number of bytes (dataLen) to the USB file system, starting from block 1. This will overwrite the existing contents.

Synopsis

int USBFS_WriteData(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *data, 
    uint32_t dataLen, 
    uint8_t *header
);

Input Parameters

Parameter	Description
`cap`	Capacity
`data`	Data string
`dataLen`	Length of the data string to follow
`dp`	Structure
`handle`	Device handle
`header`	Pointer to file system block 0

Input Requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return Value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API Vendor-Defined Error Codes.

USB API Vendor-Defined Error Codes

The table below lists the error codes that may be returned from USB API calls.

Name	Value	Description
`CKR_USB_OK`	0	No Error
`CKR_USB_GENERAL_ERROR`	0x80000100	Error, cause unknown.
`CKR_USB_INITIALIZED`	0x80000101	The USB device has already been initialized.
`CKR_USB_NO_DEVICES`	0x80000102	No USB device is present.
`CKR_USB_TRANSFER`	0x80000103	Error during USB read/write operations.
`CKR_USB_FS_EXISTS`	0x80000104	A USB file system already exists.
`CKR_USB_MEMORY`	0x80000105	Memory allocation error.
`CKR_USB_FS_NOT_PRESENT`	0x80000106	No USB file system has been created.
`CKR_USB_FS_NOT_OPENED`	0x80000107	The file system must be opened before continuing.