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 currently supports USB 2.0 memory devices only. Hybrid USB devices that use the USB 2.0, 3.0, and 3.1 standards are not supported at this time.

This chapter contains the following sections:

>USB File System

>Data Structures

>Example Usage

Functions included in this reference are:

>USBFS_Close

>USBFS_Destroy

>USBFS_Finalize

>USBFS_GetInfo

>USBFS_Init

>USBFS_New

>USBFS_Open

>USBFS_ReadData

>USBFS_WriteData

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

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.