Public Key Acceleration Library Reference Guide
1.0
|
#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 | 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... | |
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.
For example to use this module to do a single RSA encryption, one could do the following:
#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 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.
enum pka_cmp_code_t |
enum pka_flags_t |
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.
|
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. |
enum pka_opcode_t |
PKA Command Code Values.
enum pka_result_code_t |
PKA Result Code Values.
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | One of the two big integers whose sum is requested. |
addend | The other of the two big integers whose sum is requested. |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The LARGEST of the three big integers whose addition and subtraction are requested. |
addend | The other of the three big integers whose sum is requested. |
subtrahend | The SMALLEST of the three big integers whose difference is requested. |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The big integer whose quotient and remainder is desired. |
divisor | The big integer divisor. Must not be zero. |
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:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
p | A big prime number. |
q | A big prime number that divides 'p-1'. |
g | A big integer, also refered to as the generator. |
private_key | A big integer used as the private key. Refered to as alpha in the FIPS-186 spec. |
hash | The hash (using one of SHA hash algorithms) of the message. Also called the message digest. |
k | A big integer used an additional random number secret value in the algorithm, |
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:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
p | A big prime number. |
q | A big prime number that divides 'p-1'. |
g | A big integer, also refered to as the generator. |
public_key | A big integer used as the public key. Refered to as alpha in the FIPS-186 spec. |
hash | The hash (using one of SHA hash algorithms) of the message. Also called the message digest. |
rcvd_signature | A pointer to a dsa_signature object containing two large integers, called r and s in the standard, representing a cryptographically secure digital signature. |
no_write | if 0 process signature verification with write-back, else process signature verfication without write-back. |
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.
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:
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.
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.
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
curve | A pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime. |
pointA | A pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the first point. |
pointB | A pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the second point. |
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).
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
curve | A pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime. |
pointA | A pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the first point. |
multiplier | A big integer indicating the number of times that pointA should be added to itself. |
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:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
curve | A pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime. |
base_pt | A pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the base point. |
base_pt_order | The 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_key | The big integer used as the private key. Refered to as alpha in the FIPS-186 spec. |
hash | The hash (using one of SHA hash algorithms) of the message. Also called the message digest. |
k | A big integer used an additional random number secret value in the algorithm, |
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:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
curve | A pointer to an ecc_curve_t object, which supplies the curve parameters a, b, and p where p must be prime. |
base_pt | A pointer to an ecc_point_t object, which supplies the x and y coordinates (as big integer) for the base point. |
base_pt_order | The big integer number such that when base_pt is multiplied by this number (i.e. using pka_process_ecc_pt_mult above) |
public_key | A pointer to an ecc_point_t object, which represents the public key of this crypto system. |
hash | The hash (using one of SHA hash algorithms) of the message. Also called the message digest. |
rcvd_signature | A pointer to a dsa_signature object containing two large integers, called r and s in the standard, representing a cryptographically secure digital signature. |
no_write | if 0 process signature verification with write-back, else process signature verfication without write-back. |
int pka_get_result | ( | pka_handle_t | handle, |
pka_results_t * | results | ||
) |
Return results pending in queue.
handle | An initialized PKA handle. |
results | The results structure to store the PK results. |
uint32_t pka_get_rings_bitmask | ( | pka_instance_t | instance | ) |
Return the bitmask of HW rings allocated to a PK instance.
instance | A PK instance handle. |
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.
handle | An initialized PKA handle. |
uint32_t pka_get_rings_count | ( | pka_instance_t | instance | ) |
Return the number of rings allocated to a PK instance.
instance | A PK instance handle. |
bool pka_has_avail_result | ( | pka_handle_t | handle | ) |
Return if there is pending results in queue.
handle | An initialized PKA handle. |
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.
name | Name of the PK instance. Also specifies the shared memory object to be created. |
flags | Flags used to select the processing mode and the synchronization mechanism. See pka_flags_t above. |
ring_cnt | Number of HW rings requested. |
queue_cnt | Number 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_size | Size of a software request queue (in bytes). |
result_queue_size | Size of a software reply queue (in bytes). |
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.
instance | A PK instance handle. |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
exponent | The big integer exponent. |
modulus | The big integer modulus. Must be an odd prime (i.e. the LSB must be ONE). Must be larger than 2^32 (5 bytes). |
value | The big integer whose modular power is requested. Must be inferior to the 'modulus'. |
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.
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | A big integer representing the message to be decrypted. |
p | A big integer prime number. |
q | A big integer prime number. |
d_p | The big integer value 'd mod (p-1)' where d is the private key. |
d_q | The big integer value 'd mod (q-1)' where d is the private key. |
qinv | The big integer value 'q^-1 mod p' - i.e. the modular inverse of q, using modulus p. |
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.
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The big integer whose modular inverse is requested. |
modulus | The big integer modulus. Must be odd (i.e. the least significant bit must be ONE). May not have value 1. |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The big integer whose mod is desired. |
modulus | The big integer modulus. Must be odd and be larger than 2^32 (5 bytes). |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | One of the two big integers whose product is requested. |
multiplier | The other of the two big integers whose product is requested. |
uint32_t pka_request_count | ( | pka_handle_t | handle | ) |
Return the number of outstanding command requests.
handle | An initialized PKA handle. |
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:
where the encryption and decryption operations are defined as:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
exponent | The big integer exponent. For RSA, this exponent could be either the e or d part of the public or private key. |
modulus | The big integer modulus. Must be odd. Must be the product of two big prime numbers. |
value | The big integer whose modular power is requested. |
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.
In addition, it is assumed that the following values have been precomputed:
Specifically this function implements the mathematical expression "c^d mod p*q" by doing the following computation:
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
p | A big integer prime number. RSA modulus = 'p*q', where p is larger than q. |
q | A big integer prime number. RSA modulus = 'p*q', where q is smaller than p. |
c | A big integer representing the message to be decrypted. |
d_p | The big integer value 'd mod (p-1)' where d is the private key. |
d_q | The big integer value 'd mod (q-1)' where d is the private key. |
qinv | The big integer value 'q^-1 mod p' - i.e. the modular inverse of q, using modulus p. |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The big integer that is to be shifted left. |
shift_cnt | The amount that the big integer 'value' is to be shifted by (range 0...31 bits). |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The big integer that is to be shifted right. |
shift_cnt | The amount that the big integer 'value' is to be shifted by (range 0...31 bits). |
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".
handle | An initialized PKA handle to use for this command. |
user_data | Opaque user pointer that is returned with the result. |
value | The LARGEST of the two big integers whose difference is requested. |
subtrahend | The SMALLEST of the two big integers whose difference is requested. |
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.
instance | A 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().
handle | An initialized PKA handle. |