Public Key Acceleration Library Reference Guide  1.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros
Classes | Macros | Typedefs | Enumerations | Functions
pka.h File Reference
#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Classes

struct  pka_operand_t
 
struct  pka_results_t
 
struct  ecc_point_t
 
struct  ecc_curve_t
 
struct  ecc_mont_curve_t
 
struct  dsa_signature_t
 

Macros

#define PKA_INSTANCE_INVALID   0
 Define value for invalid PK instance. More...
 
#define PKA_HANDLE_INVALID   NULL
 Define value for invalid PK handle. More...
 
#define MAX_OPERAND_CNT   11
 
#define MAX_RESULT_CNT   2
 
#define MAX_BYTE_LEN   520
 
#define OTHER_MAX_BYTE_LEN   264
 
#define MAX_RESULT_CNT   2
 

Typedefs

typedef uint64_t pka_instance_t
 PK instance type. More...
 
typedef struct pka_local_info_t * pka_handle_t
 PK handle (opaque) type that encapsulates local information. More...
 

Enumerations

enum  pka_flags_t { PKA_F_PROCESS_MODE_SINGLE = 0x1, PKA_F_PROCESS_MODE_MULTI = 0x2, PKA_F_SYNC_MODE_DISABLE = 0x4, PKA_F_SYNC_MODE_ENABLE = 0x8 }
 PK flags that are supplied during PK instance initialization. More...
 
enum  pka_opcode_t {
  CC_ADD = 0x01, CC_SUBTRACT = 0x02, CC_ADD_SUBTRACT = 0x03, CC_MULTIPLY = 0x04,
  CC_DIVIDE = 0x05, CC_MODULO = 0x06, CC_SHIFT_LEFT = 0x07, CC_SHIFT_RIGHT = 0x08,
  CC_COMPARE = 0x09, CC_COPY = 0xA0, CC_MODULAR_EXP = 0x10, CC_MOD_EXP_CRT = 0x11,
  CC_MODULAR_INVERT = 0x12, CC_MONT_ECDH_MULTIPLY = 0x13, CC_ECC_PT_ADD = 0x14, CC_ECC_PT_MULTIPLY = 0x15,
  CC_ECDSA_GENERATE = 0x20, CC_ECDSA_VERIFY = 0x21, CC_DSA_GENERATE = 0x22, CC_DSA_VERIFY = 0x23,
  CC_ECDSA_VERIFY_NO_WRITE = 0x25, CC_DSA_VERIFY_NO_WRITE = 0x27
}
 PKA Command Code Values. More...
 
enum  pka_result_code_t {
  RC_NO_ERROR = 0x00, RC_EVEN_MODULUS = 0x81, RC_ZERO_EXPONENT = 0x82, RC_SHORT_MODULUS = 0x83,
  RC_ONE_EXPONENT = 0x84, RC_BAD_ODD_POWERS = 0x85, RC_RESULT_IS_PAI = 0x86, RC_UNKNOWN_COMMAND = 0x87,
  RC_INTERMEDIATE_PAI = 0x89, RC_NO_MODULAR_INVERSE = 0x8B, RC_ECC_RESULT_OFF_CURVE = 0x8D, RC_OPERAND_LENGTH_ERR = 0x8F,
  RC_UNDEFINED_TRIGGER = 0x90, RC_INVALID_ARGUMENT = 0x91, RC_OPERAND_VALUE_ERR = 0xA0, RC_CALCULATION_ERR = 0xA1,
  RC_INVALID_ADDRESS = 0xA2, RC_ENCRYPTED_PARAM_ERR = 0xA3, RC_TOO_LITTLE_MEMORY = 0xC0, RC_MEMORY_DEADLOCK = 0xC1
}
 PKA Result Code Values. More...
 
enum  pka_cmp_code_t { RC_COMPARE_EQUAL = 0x1, RC_LEFT_IS_SMALLER = 0x2, RC_RIGHT_IS_SMALLER = 0x4 }
 PKA Compare Result Code Values. More...
 
enum  pka_mont_curve_t { PKA_CURVE_NULL = 0, PKA_CURVE_25519, PKA_CURVE_448 }
 

Functions

pka_instance_t pka_init_global (const char *name, uint8_t flags, uint32_t ring_cnt, uint32_t queue_cnt, uint32_t cmd_queue_size, uint32_t result_queue_size)
 
void pka_term_global (pka_instance_t instance)
 
uint32_t pka_get_rings_count (pka_instance_t instance)
 
uint8_t * pka_get_rings_bitmask (pka_instance_t instance)
 
pka_handle_t pka_init_local (pka_instance_t instance)
 
void pka_term_local (pka_handle_t handle)
 
uint8_t pka_get_rings_byte_order (pka_handle_t handle)
 
int pka_get_result (pka_handle_t handle, pka_results_t *results)
 
bool pka_has_avail_result (pka_handle_t handle)
 
uint32_t pka_request_count (pka_handle_t handle)
 
int pka_add (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *addend)
 
int pka_subtract (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *subtrahend)
 
int pka_add_subtract (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *addend, pka_operand_t *subtrahend)
 
int pka_multiply (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *multiplier)
 
int pka_divide (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *divisor)
 
int pka_modulo (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
 
int pka_shift_left (pka_handle_t handle, void *user_data, pka_operand_t *value, uint32_t shift_cnt)
 
int pka_shift_right (pka_handle_t handle, void *user_data, pka_operand_t *value, uint32_t shift_cnt)
 
int pka_dh (pka_handle_t handle, void *user_data, pka_operand_t *private_key, pka_operand_t *modulus, pka_operand_t *value)
 
int pka_modular_exp (pka_handle_t handle, void *user_data, pka_operand_t *exponent, pka_operand_t *modulus, pka_operand_t *value)
 
int pka_modular_exp_crt (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *p, pka_operand_t *q, pka_operand_t *d_p, pka_operand_t *d_q, pka_operand_t *qinv)
 
int pka_rsa (pka_handle_t handle, void *user_data, pka_operand_t *exponent, pka_operand_t *modulus, pka_operand_t *value)
 
int pka_rsa_crt (pka_handle_t handle, void *user_data, pka_operand_t *p, pka_operand_t *q, pka_operand_t *c, pka_operand_t *d_p, pka_operand_t *d_q, pka_operand_t *qinv)
 
int pka_modular_inverse (pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
 
int pka_mont_ecdh_mult (pka_handle_t handle, void *user_data, ecc_mont_curve_t *curve, pka_operand_t *point_x, pka_operand_t *multiplier)
 
int pka_ecc_pt_add (pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *pointA, ecc_point_t *pointB)
 
int pka_ecc_pt_mult (pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *pointA, pka_operand_t *multiplier)
 
int pka_mont_ecdh (pka_handle_t handle, void *user_data, ecc_mont_curve_t *curve, pka_operand_t *point_x, pka_operand_t *private_key)
 
int pka_ecdh (pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *point, pka_operand_t *private_key)
 
int pka_ecdsa_signature_generate (pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *base_pt, pka_operand_t *base_pt_order, pka_operand_t *private_key, pka_operand_t *hash, pka_operand_t *k)
 
int pka_ecdsa_signature_verify (pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *base_pt, pka_operand_t *base_pt_order, ecc_point_t *public_key, pka_operand_t *hash, dsa_signature_t *rcvd_signature, uint8_t no_write)
 
int pka_dsa_signature_generate (pka_handle_t handle, void *user_data, pka_operand_t *p, pka_operand_t *q, pka_operand_t *g, pka_operand_t *private_key, pka_operand_t *hash, pka_operand_t *k)
 
int pka_dsa_signature_verify (pka_handle_t handle, void *user_data, pka_operand_t *p, pka_operand_t *q, pka_operand_t *g, pka_operand_t *public_key, pka_operand_t *hash, dsa_signature_t *rcvd_signature, uint8_t no_write)
 
int pka_get_rand_bytes (pka_handle_t handle, uint8_t *buf, uint32_t buf_len)
 

Detailed Description

This file forms an interface to the BlueField PK Accelerator based on EIP-154. The API is refered to as "northbound interface" for communication between user application and PKA hardware Rings.

The PKA hardware makes available a number of basic arithmetic (e.g., add and multipy) and complex arithmetic (e.g., modular exponentiation and modular inversion) as well as high-level operations such as RSA, Diffie-Hallman, Elliptic Curve Cryptography, and the Federal Digital Signature Algorithm (DSA as documented in FIPS 186) public-private key systems.

The API consists of an interface which allows user applications to accelerate PK operations. The API allows user application to open and release a PK instance. A PK instance refers to an execution context, i.e. parameters and hardware configuration which allows to process PK operations. It then encapsulates the PK global information structure.

Note
Almost all functions are asynchronous and require a 'handle' argument to be passed to them. Typically, a 'handle' encapsulates all the parameters, status of an execution context of a given user application.
An application running multiple threads has as many handles as threads.

For example to use this module to do a single RSA encryption, one could do the following:

* // 64-bit RSA encryption example.
* //
* // Note that the following code does not provide application's function
* // definition (e.g., from_hex_string(), to_hex_string()). It also omits
* // macros definition and error checking.
*
* pka_instance_t instance;
* pka_handle_t handle;
* pka_operand_t encrypt_key, n, msg;
* pka_results_t results;
* uint8_t result_buf[8];
* char* key_string = "0x633649F8F2228670";
* char* modulus_string = "0x87C1F8442909789F";
* char* plaintext = "0x4869207468657265"; // hex "Hi there"
* char ciphertext[20];
*
* memset(&encrypt_key, 0, sizeof(pka_operand_t));
* memset(&n, 0, sizeof(pka_operand_t));
* memset(&msg, 0, sizeof(pka_operand_t));
* memset(&results, 0, sizeof(pka_results_t));
* results.results[0].buf_ptr = result_buf;
* results.results[0].buf_len = sizeof(result_buf);
*
* from_hex_string(key_string, &encrypt_key);
* from_hex_string(modulus_string, &n);
* from_hex_string(plaintext, &msg);
*
* // Global PKA initialization. This function must be called once per
* // instance before calling any other PKA API functions.
* instance = pka_init_global(“pka_app”,
* PKA_F_PROCESS_MODE_SINGLE | PKA_F_SYNC_MODE_NONE,
* PKA_RING_CNT, PKA_QUEUE_CNT,
* CMD_QUEUE_SIZE, RSLT_QUEUE_SIZE);
*
* // Thread local PKA initialization. The instance parameter specifies which
* // PKA instance the thread joins. It Returns a valid handle for it.
* handle = pka_init_local(instance);
*
* pka_rsa(handle, NULL, &encrypt_key, &n, &msg);
*
* //
* // Here we can do other stuff
* //
*
* pka_get_rslt(handle, &results);
*
* //
* // Here we can process other PK commands
* //
*
* // Release the given handle.
* pka_term_local(handle);
* // Release the PK instance
* pka_term_global(instance);
*
* to_hex_string(&results.results[0], ciphertext, 20);
* printf("plaintext='%s'\nciphertext='%s'\n", plaintext, ciphertext);
*
* // ciphertext should be '9F5E3B6F177E25B6'
*

Macro Definition Documentation

#define MAX_BYTE_LEN   520

The MAX_BYTE_LEN constant defines the byte length of the largest operand that the current PKA hardware supports.

#define MAX_OPERAND_CNT   11

MAX_OPERAND_CNT defines the largest number of big integer operands used by any operation in this API.

#define MAX_RESULT_CNT   2

MAX_RESULT_CNT defines the largest number of big integers returned by any operation in this API. In particular, a given asynchronous request function always returns the same number of result big integers, but depending on the operation this can be either 0, 1 or 2 big integers.

Defines the largest number of big integers returned by any operation in this API. In particular, a given asynchronous request function always returns the same number of result big integers, but depending on the operation this can be either 0, 1 or 2 big integers.

#define MAX_RESULT_CNT   2

MAX_RESULT_CNT defines the largest number of big integers returned by any operation in this API. In particular, a given asynchronous request function always returns the same number of result big integers, but depending on the operation this can be either 0, 1 or 2 big integers.

Defines the largest number of big integers returned by any operation in this API. In particular, a given asynchronous request function always returns the same number of result big integers, but depending on the operation this can be either 0, 1 or 2 big integers.

#define OTHER_MAX_BYTE_LEN   264

The OTHER_MAX_BYTE_LEN constant defines the byte length of the largest operand supported for certain operations like "modular exponentiation using the chinese remainder theorem".

#define PKA_HANDLE_INVALID   NULL

Define value for invalid PK handle.

#define PKA_INSTANCE_INVALID   0

Define value for invalid PK instance.

Typedef Documentation

typedef struct pka_local_info_t* pka_handle_t

PK handle (opaque) type that encapsulates local information.

typedef uint64_t pka_instance_t

PK instance type.

Enumeration Type Documentation

PKA Compare Result Code Values.

Enumerator
RC_COMPARE_EQUAL 

Both operands are equal ('A' = 'B').

RC_LEFT_IS_SMALLER 

Left operand is smaller than right operand ('A' < 'B').

RC_RIGHT_IS_SMALLER 

Right operand is smaller than left operand ('A' > 'B').

PK flags that are supplied during PK instance initialization.

Enumerator
PKA_F_PROCESS_MODE_SINGLE 

Single process mode: A PK instance runs over one process. The process ID is stored as PK global information. A single process instance might create as many worker threads as needed to process PK operations.

PKA_F_PROCESS_MODE_MULTI 

Multi process mode: A PK instance runs over mult-processes. The main process ID is stored as PK global information. Each process might create as many worker threads as needed to process PK operations. Only the main process should call the pka_init_global() and pka_term_global() functions.

Note
Currently multi_process_mode is not fully supported.
PKA_F_SYNC_MODE_DISABLE 

None of the PK operations are synchronized : The application will make sure that only one thread will make a PK call at a given time. These calls could come from threads at different times. PK library will ignore synchronization issues.

PKA_F_SYNC_MODE_ENABLE 

All PK operations are synchronized : The PK library uses internal lock to ensure that multiple threads making PK calls are properly synchronized.

Enumerator
PKA_CURVE_NULL 
PKA_CURVE_25519 
PKA_CURVE_448 

PKA Command Code Values.

Enumerator
CC_ADD 

Add (basic arithmetic).

CC_SUBTRACT 

Subtract (basic arithmetic).

CC_ADD_SUBTRACT 

Add/Subtract combination (basic arithmetic).

CC_MULTIPLY 

Multiply/Square (basic arithmetic).

Note
The Square operation is a Multiply where the inputs 'A' and 'B' point to the same.
CC_DIVIDE 

Divide (basic arithmetic).

CC_MODULO 

Modulo (basic arithmetic).

CC_SHIFT_LEFT 

Shift left (basic arithmetic).

CC_SHIFT_RIGHT 

Shift right (basic arithmetic).

CC_COMPARE 

Compare (basic arithmetic).

CC_COPY 

Copy (basic arithmetic).

CC_MODULAR_EXP 

Modular Exponentiation without CRT (complex arithmetic).

CC_MOD_EXP_CRT 

Modular Exponentiation with CRT (complex arithmetic).

CC_MODULAR_INVERT 

Modular Inversion (complex arithmetic).

CC_MONT_ECDH_MULTIPLY 

ECC point multiplication on Montgomery Curves (complex arithmetic)

CC_ECC_PT_ADD 

ECC point addition/doubling (complex arithmetic).

CC_ECC_PT_MULTIPLY 

ECC point multiplication (complex arithmetic).

CC_ECDSA_GENERATE 

ECDSA signature generation (high-level PKA operations).

CC_ECDSA_VERIFY 

ECDSA signature verification with r'' write-back (high-level PKA operations).

CC_DSA_GENERATE 

DSA signature generation (high-level PKA operations).

CC_DSA_VERIFY 

DSA signature verification with r'' write-back (high-level PKA operations).

CC_ECDSA_VERIFY_NO_WRITE 

ECDSA signature verification without r'' write-back (high-level PKA operations).

CC_DSA_VERIFY_NO_WRITE 

DSA signature verification without r'' write-back (high-level PKA operations).

PKA Result Code Values.

Enumerator
RC_NO_ERROR 

No error – Normal command completion.

RC_EVEN_MODULUS 

Modulus was even.

RC_ZERO_EXPONENT 

Exponent was 0 (for a modular exponentiation).

RC_SHORT_MODULUS 

Modulus was too short (less than 9 significant bits).

RC_ONE_EXPONENT 

Exponent was 1 (for a modular exponentiation).

RC_BAD_ODD_POWERS 

Odd powers not in range 1 … 16.

RC_RESULT_IS_PAI 

Result point of ECC operation is 'at infinity' -not a real error.

RC_UNKNOWN_COMMAND 

Unknown command.

RC_INTERMEDIATE_PAI 

Intermediate result of ECC operation is 'at infinity' -not a real error.

RC_NO_MODULAR_INVERSE 

Modular inverse does not exist.

RC_ECC_RESULT_OFF_CURVE 

Result of ECC operation is not on the curve.

RC_OPERAND_LENGTH_ERR 

Operand length error.

RC_UNDEFINED_TRIGGER 

Host used undefined trigger.

RC_INVALID_ARGUMENT 

Invalid argument.

RC_OPERAND_VALUE_ERR 

Operand value error.

RC_CALCULATION_ERR 

Calculated value error.

RC_INVALID_ADDRESS 

Address is invalid.

RC_ENCRYPTED_PARAM_ERR 

Illegal encrypted parameter use.

RC_TOO_LITTLE_MEMORY 

Farm memory too small for operation.

RC_MEMORY_DEADLOCK 

Memory deadlock error.

Function Documentation

int pka_add ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t addend 
)

Big Integer Add function.

This function computes "value + addend".

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueOne of the two big integers whose sum is requested.
addendThe other of the two big integers whose sum is requested.
Returns
0 on success, a negative error code on failure.
int pka_add_subtract ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t addend,
pka_operand_t subtrahend 
)

Big Integer Add/Substract combination.

This functions computes "value + addend - subtrahend".

Note
The result of this function must be positive, so the value plus the addend MUST be >= than the subtrahend.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe LARGEST of the three big integers whose addition and subtraction are requested.
addendThe other of the three big integers whose sum is requested.
subtrahendThe SMALLEST of the three big integers whose difference is requested.
Returns
0 on success, a negative error code on failure.
int pka_dh ( pka_handle_t  handle,
void *  user_data,
pka_operand_t private_key,
pka_operand_t modulus,
pka_operand_t value 
)

Traditional Diffie-Hellman(DH).

This function provide Diffie-Hellman algorithm implementation, which is essentially nothing but Modular Exponentiation without CRT.

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
private_keyThe big integer exponent, which is always the local private key in case of DH.
modulusThe big integer modulus. Must be an odd prime (i.e. the LSB must be ONE). Must be larger than 2^32 (5 bytes).
valueThe big integer whose modular power is requested. Must be inferior to the 'modulus'.
Returns
0 on success, a negative error code on failure.
int pka_divide ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t divisor 
)

Big Integer Divide function.

This function computes BOTH "value / divisor", and "value mod divisor".

Note
the final results returned will always have result_cnt = 2.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe big integer whose quotient and remainder is desired.
divisorThe big integer divisor. Must not be zero.
Returns
0 on success, a negative error code on failure.
int pka_dsa_signature_generate ( pka_handle_t  handle,
void *  user_data,
pka_operand_t p,
pka_operand_t q,
pka_operand_t g,
pka_operand_t private_key,
pka_operand_t hash,
pka_operand_t k 
)

DSA - Signature Generation.

This function implements the original Digital Signature Generation Algorithm. Specifically, it implements the following equations:

* k_inv = k^-1 mod q;
* signature.r = (g^k mod p) mod q;
* signature.s = (k_inv * (hash + private_key * signature.r) mod q;
*
Note
The final result of this operation is a dsa_signature_t object containing two big integers (hence the result_cnt will be 2) called r and s by the standard.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
pA big prime number.
qA big prime number that divides 'p-1'.
gA big integer, also refered to as the generator.
private_keyA big integer used as the private key. Refered to as alpha in the FIPS-186 spec.
hashThe hash (using one of SHA hash algorithms) of the message. Also called the message digest.
kA big integer used an additional random number secret value in the algorithm,
Returns
0 on success, a negative error code on failure.
int pka_dsa_signature_verify ( pka_handle_t  handle,
void *  user_data,
pka_operand_t p,
pka_operand_t q,
pka_operand_t g,
pka_operand_t public_key,
pka_operand_t hash,
dsa_signature_t rcvd_signature,
uint8_t  no_write 
)

DSA - Signature Verification.

This function implements the original Digital Signature Verification Algorithm. Specifically it implements the following equations:

* // Note that public_key = g^private_key mod p
* // Check that 0 < r < q and 0 < s < q
* s_inv = signature.s^(-1) mod q;
* u1 = (hash * s_inv) mod q;
* u2 = (signature.r * s_inv) mod q;
* v = (((g^u1) * (public_key^u2)) mod p) mod q;
* // Check that v == signtaure.r
*
Note
The final result of this operation is a boolean - result_code - and so the result_cnt will be 0.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
pA big prime number.
qA big prime number that divides 'p-1'.
gA big integer, also refered to as the generator.
public_keyA big integer used as the public key. Refered to as alpha in the FIPS-186 spec.
hashThe hash (using one of SHA hash algorithms) of the message. Also called the message digest.
rcvd_signatureA pointer to a dsa_signature object containing two large integers, called r and s in the standard, representing a cryptographically secure digital signature.
no_writeif 0 process signature verification with write-back, else process signature verfication without write-back.
Returns
0 on success, a negative error code on failure.
int pka_ecc_pt_add ( pka_handle_t  handle,
void *  user_data,
ecc_curve_t curve,
ecc_point_t pointA,
ecc_point_t pointB 
)

Elliptic Curve Cryptography (ECC) point addition.

Implements modular elliptic curve addition. In particular, given two points on an elliptic curve defined using a finite field defined by a large prime number, determine their sum.

Note
Elliptic curves using a modulus of 2^m (a.k.a binary fields) are NOT supported.

The elliptic curve is assumed to be defined by the set of all points '(x,y)' such that x and y are integers in the range 0..p-1 and such that they satisfy the equation:

* y^2 = x^3 + a*x + b mod p;
* // where x and y are in the range 0..p-1 and p is a big prime number.
*

The elliptic curve is then defined by the three big integer parameters, a, b and p. These three parameters are not completely independent. In particular, the discriminant defined below must be non-zero.

* // Definition of the discriminant. Must be non-zero.
* discriminant = -16 * ((4 * a^3) + (27 * b^2));
*

The definition of elliptic curve point addition leads to the following equations for computing the result point. Notice that the result from this operation has a result_cnt of 2 because it returns two large integers, namely the x and y coordinate of the result point.

* if pointA.x == pointB.x then
* s = (3 * pointA.x^2 + curve.a) / (2 * pointA.y) mod curve.p;
* result.x = s * s - 2 * pointA.x mod curve.p;
* else
* s = ((pointA.y - pointB.y) / (pointA.x - pointB.x)) mod curve.p;
* result.x = s * s - (pointA.x + pointB.x) mod curve.p;
* endif
* result.y = pointA.y + s * (result.x - pointA.x) mod curve.p;
*
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime.
pointAA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the first point.
pointBA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the second point.
Returns
0 on success, a negative error code on failure.
int pka_ecc_pt_mult ( pka_handle_t  handle,
void *  user_data,
ecc_curve_t curve,
ecc_point_t pointA,
pka_operand_t multiplier 
)

Elliptic Curve Cryptography (ECC) point multiplication.

Implements modular elliptic curve multiplication. In particular, given a point on an elliptic curve and a 'scalar' m, multiply the point by the scalar giving a new result point. Scalar multiplication is defined to be equivalent to repeated elliptic curve addition (see pka_ecc_pt_add above for details of elliptic curve addition).

Note
Elliptic curves using a modulus of 2^m are NOT supported.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime.
pointAA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the first point.
multiplierA big integer indicating the number of times that pointA should be added to itself.
Returns
0 on success, a negative error code on failure.
int pka_ecdh ( pka_handle_t  handle,
void *  user_data,
ecc_curve_t curve,
ecc_point_t point,
pka_operand_t private_key 
)

Elliptic Curve Diffie-Hellman (ECDH).

ECDH is based on ECC point multiplication and essentially uses the API of the same.

Note
Elliptic curves using a modulus of 2^m are NOT supported.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime.
pointA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the first point. This is either a base point for the curve or remote public key.
private_keybig integer indicating the number of times that point should be added to itself. In case of ECDH this the local private key.
Returns
0 on success, a negative error code on failure.
int pka_ecdsa_signature_generate ( pka_handle_t  handle,
void *  user_data,
ecc_curve_t curve,
ecc_point_t base_pt,
pka_operand_t base_pt_order,
pka_operand_t private_key,
pka_operand_t hash,
pka_operand_t k 
)

Elliptic Curve DSA (ECSDA) Signature Generation.

This function implements the Elliptic Curve DSA Signature Generation algorithm. Specifically, it implements the following equations:

* k_inv = k^-1 mod base_pt_order; // Modular inverse of k.
* KG = k * base_pt; // This is an ECC point multiplication.
* r = KG.x mod base_pt_order;
* s = (k_inv * (hash + private_key * r) mod base_pt_order;
*
Note
The final result of this operation is a dsa_signature_t object containing two big integers (hence the result_cnt will be 2) called r and s by the standard.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime.
base_ptA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the base point.
base_pt_orderThe big integer number such that when base_pt is multiplied by this number (i.e. using pka_ecc_multiply above) the result is 1.
private_keyThe big integer used as the private key. Refered to as alpha in the FIPS-186 spec.
hashThe hash (using one of SHA hash algorithms) of the message. Also called the message digest.
kA big integer used an additional random number secret value in the algorithm,
Returns
0 on success, a negative error code on failure.
int pka_ecdsa_signature_verify ( pka_handle_t  handle,
void *  user_data,
ecc_curve_t curve,
ecc_point_t base_pt,
pka_operand_t base_pt_order,
ecc_point_t public_key,
pka_operand_t hash,
dsa_signature_t rcvd_signature,
uint8_t  no_write 
)

Elliptic Curve DSA (ECSDA) Signature Verification

This function implements the Elliptic Curve DSA Signature Verification algorithm. Specifically, it implements the following equations:

* // Note that public_key = g^private_key mod p
* // Check that 0 < r < base_pt_order and 0 < s < base_pt_order
* s_inv = s^(-1) mod base_pt_order;
* u1 = (hash * s_inv) mod base_pt_order;
* u2 = (signature.r * s_inv) mod base_pt_order;
* sum_pt = (u1 * base_pt) + (u2 * public_key); // ECC adds and mults.
* // Check that signature.r == sum_pt.x mod base_pt_order;
*
Note
The final result of this operation is a boolean - result_code - and so the result_cnt will be 0.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime.
base_ptA pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the base point.
base_pt_orderThe big integer number such that when base_pt is multiplied by this number (i.e. using pka_process_ecc_pt_mult above)
public_keyA pointer to an ecc_point_t object, which represents the public key of this crypto system.
hashThe hash (using one of SHA hash algorithms) of the message. Also called the message digest.
rcvd_signatureA pointer to a dsa_signature object containing two large integers, called r and s in the standard, representing a cryptographically secure digital signature.
no_writeif 0 process signature verification with write-back, else process signature verfication without write-back.
Returns
0 on success, a negative error code on failure.
int pka_get_rand_bytes ( pka_handle_t  handle,
uint8_t *  buf,
uint32_t  buf_len 
)

RANDOM NUMBER GENERATION.

This function implements the random number generation. Random number generation is carried out by generating random bytes.

Parameters
handleAn initialized PKA handle to use for this command.
bufBuffer to hold the randomly generated bytes.
buf_lenLength/Number of bytes to be filled in the buffer.
Returns
Length/Number of random bytes generated.
int pka_get_result ( pka_handle_t  handle,
pka_results_t results 
)

Return results pending in queue.

Parameters
handleAn initialized PKA handle.
resultsThe results structure to store the PK results.
Returns
0 on success, and 1 on failure.
uint8_t* pka_get_rings_bitmask ( pka_instance_t  instance)

Return the bitmask of HW rings allocated to a PK instance.

Parameters
instanceA PK instance handle.
Returns
The bitmask(array of uint8_t) of allocated HW rings.
uint8_t pka_get_rings_byte_order ( pka_handle_t  handle)

Return Rings byte order, whether BE(1) or LE(0). This function returns PKA_RING_BYTE_ORDER if the PKA handle is invalid.

Parameters
handleAn initialized PKA handle.
uint32_t pka_get_rings_count ( pka_instance_t  instance)

Return the number of rings allocated to a PK instance.

Parameters
instanceA PK instance handle.
Returns
The number of allocated HW rings.
bool pka_has_avail_result ( pka_handle_t  handle)

Return if there is pending results in queue.

Parameters
handleAn initialized PKA handle.
Returns
Whether there is an available result.
pka_instance_t pka_init_global ( const char *  name,
uint8_t  flags,
uint32_t  ring_cnt,
uint32_t  queue_cnt,
uint32_t  cmd_queue_size,
uint32_t  result_queue_size 
)

Global PKA initialization. This function must be called once (per instance) before calling any other PKA API functions. A successful call creates a new PKA instance into the system and outputs a pointer to it. The pointer is used in other calls (e.g. pka_init_local()) and holds a reference to the PK global information.

Parameters
nameName of the PK instance. Also specifies the shared memory object to be created.
flagsFlags used to select the processing mode and the synchronization mechanism. See pka_flags_t above.
ring_cntNumber of HW rings requested.
queue_cntNumber of queues that will be assigned to the worker threads. It might also refer to the number of threads allowed to request PK operation.
cmd_queue_sizeSize of a software request queue (in bytes).
result_queue_sizeSize of a software reply queue (in bytes).
Returns
A valid PK instance on success, PKA_INSTANCE_INVALID on failure.
pka_handle_t pka_init_local ( pka_instance_t  instance)

Thread local PKA initialization. All threads must call this function before calling any other PKA API functions. The instance parameter specifies which PKA instance the thread joins. A thread may be part of at most one PKA instance at any given time.

Parameters
instanceA PK instance handle.
Returns
A valid PK handle on success, PKA_HANDLE_INVALID on failure.
int pka_modular_exp ( pka_handle_t  handle,
void *  user_data,
pka_operand_t exponent,
pka_operand_t modulus,
pka_operand_t value 
)

Modular Exponentiation function without Chinese Remainder Theorem (CRT).

This function implements the mathematical expression "value^exponent mod modulus".

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
exponentThe big integer exponent.
modulusThe big integer modulus. Must be an odd prime (i.e. the LSB must be ONE). Must be larger than 2^32 (5 bytes).
valueThe big integer whose modular power is requested. Must be inferior to the 'modulus'.
Returns
0 on success, a negative error code on failure.
int pka_modular_exp_crt ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t p,
pka_operand_t q,
pka_operand_t d_p,
pka_operand_t d_q,
pka_operand_t qinv 
)

Modular Exponentiation with Chinese Remainder Theorem (CRT).

The function makes use of the Chinese Remainder Theorem in order to implement a modular exponentiation using two smaller (half-sized) modular exponentiation, plus a big integer subtraction, multiplication and addition.

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueA big integer representing the message to be decrypted.
pA big integer prime number.
qA big integer prime number.
d_pThe big integer value 'd mod (p-1)' where d is the private key.
d_qThe big integer value 'd mod (q-1)' where d is the private key.
qinvThe big integer value 'q^-1 mod p' - i.e. the modular inverse of q, using modulus p.
Returns
0 on success, a negative error code on failure.
int pka_modular_inverse ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t modulus 
)

Modular Inversion Function.

Implements "value^(-1) mod modulus", i.e. finds a big integer such that when it is multiplied by 'value mod modulus' results in the value 1. If the modulus is a prime, then such an inverse value must exist (as long as value != 0) and must be unique.

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe big integer whose modular inverse is requested.
modulusThe big integer modulus. Must be odd (i.e. the least significant bit must be ONE). May not have value 1.
Returns
0 on success, a negative error code on failure.
int pka_modulo ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t modulus 
)

Big Integer Modulo function.

The function implements the modulo function on big integers, i.e. computes "value mod modulus".

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe big integer whose mod is desired.
modulusThe big integer modulus. Must be odd and be larger than 2^32 (5 bytes).
Returns
0 on success, a negative error code on failure.
int pka_mont_ecdh ( pka_handle_t  handle,
void *  user_data,
ecc_mont_curve_t curve,
pka_operand_t point_x,
pka_operand_t private_key 
)

Elliptic Curve Diffie-Hellman (ECDH) on Montgomery curves.

ECDH is based on ECC point multiplication and essentially uses the API of the same.

Note
: The curve parameter passed in currently MUST be one of curve25519 or curve448!
Elliptic curves using a modulus of 2^m are NOT supported.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_mont_curve_t object, which supplies the curve parameters A and p where p must be prime. MUST be a pointer to either the curve25519 or the curve448 object.
point_xThe x coordinate of a point on a Montgomery ECC curve. This is either a base point for the curve or a remote public key.
private_keybig integer indicating the number of times that point should be added to itself. In case of ECDH this the local private key.
Returns
0 on success, a negative error code on failure.
int pka_mont_ecdh_mult ( pka_handle_t  handle,
void *  user_data,
ecc_mont_curve_t curve,
pka_operand_t point_x,
pka_operand_t multiplier 
)

Montgomery Elliptic Curve Cryptography (ECC) point multiplication.

Implements modular elliptic curve multiplication for points on a Montgomery curve like Curve25519 and Curve448. In particular, given a point on a Montgomery elliptic curve and a 'scalar' m, multiply the point by the scalar giving a new result point. Scalar multiplication is defined to be equivalent to repeated elliptic curve addition. Note that this specific function is ONLY given the x-coordinate of the point, and ONLY returns the x-coordinate of the result point!

Note
: The curve parameter passed in currently MUST be one of curve25519 or curve448!
: The multiplier is subsequently modified according to RFC7748. For curve25519 the two MSB bits are set to "0b01" and the three LSB bits are cleared. For curve448 the MSB bit is set and the two LSB bits are cleared. This is done internally and does not change the value the user passed in.
Elliptic curves using a modulus of 2^m are NOT supported.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
curveA pointer to an ecc_mont_curve_t object, which supplies the curve parameters A and p where p must be prime.
point_xA pointer to the x coordinate of an ecc_point_t object.
multiplierA big integer indicating the number of times that point_x should be added to itself.
Returns
0 on success, a negative error code on failure.
int pka_multiply ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t multiplier 
)

Big Integer Multiply function.

This function computes "value * multiplier".

Note
To compute a square operation, the inputs, value and multiplier must to the same data.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueOne of the two big integers whose product is requested.
multiplierThe other of the two big integers whose product is requested.
Returns
0 on success, a negative error code on failure.
uint32_t pka_request_count ( pka_handle_t  handle)

Return the number of outstanding command requests.

Parameters
handleAn initialized PKA handle.
Returns
The number of outstanding requests.
int pka_rsa ( pka_handle_t  handle,
void *  user_data,
pka_operand_t exponent,
pka_operand_t modulus,
pka_operand_t value 
)

RSA - Modular Exponentiation function.

This function implements the mathematical expression "value^exponent mod modulus".

It is the basis for both RSA encryption and decryption. For example RSA is defined by:

* // Pick two large distinct random prime numbers p and q.
* // Pick a random integer e such that 1 < e < (p-1)*(q-1) AND
* // gcd(e, (p-1)*(q-1)) = 1.
* n = p * q;
* d = (e^-1) mod ((p-1)*(q-1));
* // I.e. find d such that '(e * d) mod ((p-1)*(q-1)) = 1'.
* // Then publish (e, n) as the public key. (d, n) is the private key.
*

where the encryption and decryption operations are defined as:

* ciphertext = (plaintext^e) mod n; // encryption
* plaintext = (ciphertext^e) mod n; // decryption
*
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
exponentThe big integer exponent. For RSA, this exponent could be either the e or d part of the public or private key.
modulusThe big integer modulus. Must be odd. Must be the product of two big prime numbers.
valueThe big integer whose modular power is requested.
Returns
0 on success, a negative error code on failure.
int pka_rsa_crt ( pka_handle_t  handle,
void *  user_data,
pka_operand_t p,
pka_operand_t q,
pka_operand_t c,
pka_operand_t d_p,
pka_operand_t d_q,
pka_operand_t qinv 
)

Optimized Modular Exponentiation function for RSA.

The function makes use of the Chinese Remainder Theorem in order to implement a full RSA modular exponentiation using two smaller (half-sized) modular exponentiation, plus a big integer subtraction, multiplication and addition. Since the performance of the modular exponentiation is very roughly cubic in the size of the operands, each smaller modular exponentation runs roughly 4 times faster (but there are now twice as many of them), and in total can give a 3x speed up.

Note
that this function is only useful to the side that has both the public AND private RSA keys, since it requires as input some of the intermediate values used when creating a RSA public-private key pair.

In addition, it is assumed that the following values have been precomputed:

* d_p = d mod (p-1);
* d_q = d mod (q-1);
* qinv = q^-1 mod p; // I.e. Find qinv such that '(qinv * q) mod p = 1'
*

Specifically this function implements the mathematical expression "c^d mod p*q" by doing the following computation:

* m1 = (c^d_p) mod p;
* m2 = (c^d_q) mod q;
* h = (q_inv * (m1 - m2)) mod p;
* return m2 + (h * q);
*
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
pA big integer prime number. RSA modulus = 'p*q', where p is larger than q.
qA big integer prime number. RSA modulus = 'p*q', where q is smaller than p.
cA big integer representing the message to be decrypted.
d_pThe big integer value 'd mod (p-1)' where d is the private key.
d_qThe big integer value 'd mod (q-1)' where d is the private key.
qinvThe big integer value 'q^-1 mod p' - i.e. the modular inverse of q, using modulus p.
Returns
0 on success, a negative error code on failure.
int pka_shift_left ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
uint32_t  shift_cnt 
)

Big Integer Shift Left function.

Computes "value << shift_cnt".

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe big integer that is to be shifted left.
shift_cntThe amount that the big integer 'value' is to be shifted by (range 0...31 bits).
Returns
0 on success, a negative error code on failure.
int pka_shift_right ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
uint32_t  shift_cnt 
)

Big Integer Shift Right function.

Computes "value >> shift_cnt".

Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe big integer that is to be shifted right.
shift_cntThe amount that the big integer 'value' is to be shifted by (range 0...31 bits).
Returns
0 on success, a negative error code on failure.
int pka_subtract ( pka_handle_t  handle,
void *  user_data,
pka_operand_t value,
pka_operand_t subtrahend 
)

Big Integer Subtraction function.

This functions computes "value - subtrahend".

Note
This function must yield a positive result and so the value MUST be >= than the subtrahend.
Parameters
handleAn initialized PKA handle to use for this command.
user_dataOpaque user pointer that is returned with the result.
valueThe LARGEST of the two big integers whose difference is requested.
subtrahendThe SMALLEST of the two big integers whose difference is requested.
Returns
0 on success, a negative error code on failure.
void pka_term_global ( pka_instance_t  instance)

Global PKA termination. This function MUST be the last PKA call made when terminating a PKA application in a controlled way.

Parameters
instanceA PK instance handle.
void pka_term_local ( pka_handle_t  handle)

Thread local PKA termination. This function is the last PKA call made by a given thread, other than the final call to pka_term_global().

Parameters
handleAn initialized PKA handle.