struct crm_pk_capabilities {
   /** Maximum pending requests at any time. */
   int maxpending;
   /** Maximum operand size for prime field operands. 0 when not supported. */
   int max_gfp_opsz;
   /** Maximum operand size for elliptic curve operands. 0 when not supported. */
   int max_ecc_opsz;
   /** Maximum operand size for binary field operands. 0 when not supported. */
   int max_gfb_opsz;
   /** Operand size for IK operands. 0 when not supported. */
   int ik_opsz;
};

Description of the (hardware) accelerator capabilities and features

struct crm_pk_config {
    /** Maximum simultaneous requests the application will start.
     *
     * Set to 0 to use library default.
     */
    int maxpending;

    /** Device index to use.
     *
     * For special use cases with multiple independent hardware
     * accelerators. In case of doubt, leave to 0.
     */
    int devidx;

    /** User memory */
    long long *usrmem;

    /** Size of user provided memory */
    size_t usrmemsz;

    /** Personalization string for IK */
    uint32_t *personalization;

    /** Personalization string size in 32 bit words
     *
     * If the size is 0 the personalization string
     * is considered NULL and will not be used.
     */
    int personalization_sz;
};

Library configuration for CRM_PK_OPEN()

struct crm_pk_dreq
{
   /** The acquired acceleration request **/
   crm_pk_accel *req;
   /** The status of CRM_PK_ACQUIRE_REQ() **/
   int status;
};

Encapsulated acceleration request

#define PK_OP_FLAGS_EDDSA_AX_LSB (1 << 29)

Least significant bit of Ax is 1 (flag A)

#define PK_OP_FLAGS_EDDSA_RX_LSB (1 << 30)

Least significant bit of Rx is 1 (flag B)

struct crm_pk_slot
{
   /** Memory address of the operand slot **/
   char *addr;
};

Operand slot structure

struct crm_pk_dblslot
{
   /** First slot **/
   struct crm_pk_slot a;
   /** Second slot **/
   struct crm_pk_slot b;
};

Pair of slots. Used to store large values

struct crm_pk_ecurve {
    uint32_t curveflags;
    int sz;
    const char *params;
    int offset;
    struct crm_pk_cnx *cnx;
};

Elliptic curve configuration and parameters.To be used only via the functions in ec_curves.h The internal members of the structure should not be accessed directly

typedef struct crm_pk_constraints (*FUNC_CRM_PK_LIST_CONSTRAINTS)(int index, int usermemsz);
#define CRM_PK_LIST_CONSTRAINTS         ((FUNC_CRM_PK_LIST_CONSTRAINTS)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_LIST_CONSTRAINTS)))

Return CryptoPK constraints If maxpending in crm_pk_constraints is 0, than CryptoPK cannot be used with the given environment.

Constraints of CryptoPK

typedef const struct crm_pk_capabilities *(*FUNC_CRM_PK_FETCH_CAPABILITIES)(struct crm_pk_cnx *cnx);
#define CRM_PK_FETCH_CAPABILITIES         ((FUNC_CRM_PK_FETCH_CAPABILITIES)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_FETCH_CAPABILITIES)))

Return the crypto acceleration capabilities and features

Returns Capabilities of the accelator on success

typedef struct crm_pk_cnx *(*FUNC_CRM_PK_OPEN)(struct crm_pk_config *cfg);
#define CRM_PK_OPEN         ((FUNC_CRM_PK_OPEN)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_OPEN)))

Open CryptoPK and related hardware and allocate internal resources

NULL on failure Connection structure for future CryptoPK calls on success. Can be used with CryptoPK functions to run operations.

##SEE

CRM_PK_CLOSE()

typedef void (*FUNC_CRM_PK_CLOSE)(struct crm_pk_cnx *cnx);
#define CRM_PK_CLOSE         ((FUNC_CRM_PK_CLOSE)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_CLOSE)))

Finish using any public key acceleration. No other hardware acceleration function can be called after this.

None

typedef struct crm_pk_dreq (*FUNC_CRM_PK_ACQUIRE_REQ)(struct crm_pk_cnx *cnx, const struct crm_pk_cmd_def *cmd);
#define CRM_PK_ACQUIRE_REQ         ((FUNC_CRM_PK_ACQUIRE_REQ)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_ACQUIRE_REQ)))

Get a CryptoPK request instance locked to perform the given operation. The returned crm_pk_dreq structure contains a status and a pointer to a reserved hardware accelerator instance. That pointer is only valid and usable if status is non-zero.

None

##SEE CRM_PK_RELEASE_REQ()

typedef unsigned int (*FUNC_CRM_PK_GET_REQ_ID)(crm_pk_accel *req);
#define CRM_PK_GET_REQ_ID         ((FUNC_CRM_PK_GET_REQ_ID)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_REQ_ID

Return the instance number of the hardware accelerator for this request

| cmd | The command definition (for example ::CRM_PK_CMD_MOD_EXP) |

Instance number of the hardware accelerator for this request

typedef void (*FUNC_CRM_PK_SET_USER_CONTEXT)(crm_pk_accel *req, void *context);
#define CRM_PK_SET_USER_CONTEXT         ((FUNC_CRM_PK_SET_USER_CONTEXT)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_SET_USER_CONTEXT)))

Add the context pointer to an acceleration request. The attached pointer can be retrieved by CRM_PK_GET_USER_CONTEXT(). After CRM_PK_RELEASE_REQ(), the context pointer is not available anymore. The context can represent any content the user may associate with the PK request.

Context pointer from an acceleration request

CRM_PK_GET_USER_CONTEXT()

typedef void *(*FUNC_CRM_PK_GET_USER_CONTEXT)(crm_pk_accel *req);
#define CRM_PK_GET_USER_CONTEXT         ((FUNC_CRM_PK_GET_USER_CONTEXT)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_USER_CONTEXT)))

Get the context pointer from an acceleration request

None

CRM_PK_SET_USER_CONTEXT()

typedef int (*FUNC_CRM_PK_GET_OPSIZE)(crm_pk_accel *req);
#define CRM_PK_GET_OPSIZE         ((FUNC_CRM_PK_GET_OPSIZE)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_OPSIZE)))

Return the global operands size detected for the request

Operand size for the request

typedef int (*FUNC_CRM_PK_LIST_ECC_INSLOTS)(crm_pk_accel *req, const struct crm_pk_ecurve *curve, int flags, struct crm_pk_slot *inputs);
#define CRM_PK_LIST_ECC_INSLOTS         ((FUNC_CRM_PK_LIST_ECC_INSLOTS)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_LIST_ECC_INSLOTS)))

List slots for input operands for an ECC operation. Once the function completes with ::CRM_OK, write each operand to the address found in the corresponding slot. That applies to all ECC operations.

CRM_OK CRM_ERR_OPERAND_TOO_LARGE CRM_ERR_BUSY

typedef int (*FUNC_CRM_PK_LIST_GFP_INSLOTS)(crm_pk_accel *req, const int *opsizes, struct crm_pk_slot *inputs);
#define CRM_PK_LIST_GFP_INSLOTS         ((FUNC_CRM_PK_LIST_GFP_INSLOTS)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_LIST_GFP_INSLOTS)))

List slots for input operands for an GF(p) modular operation. Once the function completes with ::CRM_OK, write each operands to the address found in the corresponding slot. That applies to all operation except ECC.

CRM_OK CRM_ERR_OPERAND_TOO_LARGE CRM_ERR_BUSY

typedef void (*FUNC_CRM_PK_RUN)(crm_pk_accel *req);
#define CRM_PK_RUN         ((FUNC_CRM_PK_RUN)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_RUN)))

Run the operation request in hardware

To be called after all operands have been written in the slots obtainded with CRM_PK_LIST_ECC_INSLOTS() or CRM_PK_LIST_GFP_INSLOTS(). After that the acceleration request is pending.

The caller should wait until the operation finishes with CRM_PK_WAIT() or do polling by using crm_pk_has_finished().

None

typedef int (*FUNC_CRM_PK_WAIT)(crm_pk_accel *req);
#define CRM_PK_WAIT         ((FUNC_CRM_PK_WAIT)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_WAIT)))

Wait until the current operation finishes. After the operation finishes, return the operation status code.

Any \ref CRM_PK_STATUS "status code"

typedef void (*FUNC_CRM_PK_CLEAR_IRQ)(void);
#define CRM_PK_CLEARIRQ     ((FUNC_CRM_PK_CLEAR_IRQ)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_CLEARIRQ)))

Clear the interrupt request signal

None

None

typedef crm_pk_accel *(*FUNC_CRM_PK_POP_FINISHED_REQ)(struct crm_pk_cnx *cnx);
#define CRM_PK_POP_FINISHED_REQ         ((FUNC_CRM_PK_POP_FINISHED_REQ)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_POP_FINISHED_REQ)))

Return the public key acceleration request which finished its operation. If no public key accelerator finished or none has an operation, return NULL. The results from the returned crm_pk_accel should be used as soon as possible and the instances given back with CRM_PK_RELEASE_REQ().

NULL when no public key accelerator finished The acceleration request which finished its operation

typedef int (*FUNC_CRM_PK_GET_GLOBAL_NOTIFICATION_ID)(struct crm_pk_cnx *cnx);
#define CRM_PK_GET_GLOBAL_NOTIFICATION_ID         ((FUNC_CRM_PK_GET_GLOBAL_NOTIFICATION_ID)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_GLOBAL_NOTIFICATION_ID)))

Return a platform notification that notifies when a request completed. The platform notification id is:

• -1 if not available
• a fd on POSIX systems
• an interrupt line number

When a request completes the notification will activate. The fd will become readable and the interrupt line will generate an interrupt. The returned platform notification can be used once. After the platform notification or after CRM_PK_POP_FINISHED_REQ(), the notification id shall not be used anymore. May not be used in combination with CRM_PK_WAIT().

Platform notification id

typedef int (*FUNC_CRM_PK_GET_REQ_COMPLETION_ID)(crm_pk_accel *req);
#define CRM_PK_GET_REQ_COMPLETION_ID         ((FUNC_CRM_PK_GET_REQ_COMPLETION_ID)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_REQ_COMPLETION_ID)))

Return a platform notification that notifies when a request completed. The platform notification id is:

• -1 if not available
• a fd on POSIX systems
• an interrupt line number

When a request completes the notification will activate. The fd will become readable and the interrupt line will generate an interrupt.After it was used or after CRM_PK_POP_FINISHED_REQ(), the fd or interrupt line shall not be used anymore. May not be used in combination with CRM_PK_WAIT().

Platform notification id

typedef const char **(*FUNC_CRM_PK_GET_OUTPUT_OPS)(crm_pk_accel *req);
#define CRM_PK_GET_OUTPUT_OPS         ((FUNC_CRM_PK_GET_OUTPUT_OPS)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_GET_OUTPUT_OPS)))

Fetch array of addresses to output operands

Array of addresses to output operands

typedef void (*FUNC_CRM_PK_RELEASE_REQ)(crm_pk_accel *req);
#define CRM_PK_RELEASE_REQ         ((FUNC_CRM_PK_RELEASE_REQ)(*(uint32_t *)(API_TABLE_BASE_ADDRESS + ATO_CRM_PK_RELEASE_REQ)))

Give back the public key acceleration request. Release the reserved resources

CRM_PK_ACQUIRE_REQ() should have been called before this function is called and not being in use by the hardware

None