Public Key Acceleration Library Reference Guide  1.0
pka.h
Go to the documentation of this file.
1 //
2 // BSD LICENSE
3 //
4 // Copyright(c) 2016 Mellanox Technologies, Ltd. All rights reserved.
5 // All rights reserved.
6 //
7 // Redistribution and use in source and binary forms, with or without
8 // modification, are permitted provided that the following conditions
9 // are met:
10 //
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above copyright
14 // notice, this list of conditions and the following disclaimer in
15 // the documentation and/or other materials provided with the
16 // distribution.
17 // * Neither the name of Mellanox Technologies nor the names of its
18 // contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
20 //
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 //
33 
127 
128 #ifndef __PKA_H__
129 #define __PKA_H__
130 
131 #ifdef __KERNEL__
132 #include <linux/types.h>
133 #else
134 #include <stdint.h>
135 #include <stdbool.h>
136 #endif
137 
139 typedef uint64_t pka_instance_t;
140 
142 #define PKA_INSTANCE_INVALID 0
143 
145 typedef struct pka_local_info_t* pka_handle_t;
146 
148 #define PKA_HANDLE_INVALID NULL
149 
151 typedef enum
152 {
179 
200  uint8_t flags,
201  uint32_t ring_cnt,
202  uint32_t queue_cnt,
203  uint32_t cmd_queue_size,
204  uint32_t result_queue_size);
205 
211 
218 
225 
236 
242 
248 
251 #define MAX_OPERAND_CNT 11
252 
257 #define MAX_RESULT_CNT 2
258 
261 #define MAX_BYTE_LEN 520 // 130 * 4 bytes
262 
266 #define OTHER_MAX_BYTE_LEN 264 // 66 * 4 bytes
267 
272 #define MAX_RESULT_CNT 2
273 
277 typedef struct // 16 bytes long
278 {
279  uint16_t buf_len;
280  uint16_t actual_len;
281  uint8_t is_encrypted;
282  uint8_t big_endian;
283  uint8_t internal_use;
284  uint8_t pad;
285  uint8_t* buf_ptr;
286 } pka_operand_t;
287 
289 typedef enum
290 {
292  CC_ADD = 0x01,
294  CC_SUBTRACT = 0x02,
300  CC_MULTIPLY = 0x04,
302  CC_DIVIDE = 0x05,
304  CC_MODULO = 0x06,
310  CC_COMPARE = 0x09,
312  CC_COPY = 0xA0,
341 } pka_opcode_t;
342 
344 typedef enum
345 {
347  RC_NO_ERROR = 0x00,
359  RC_RESULT_IS_PAI = 0x86, // Not a real error?
363  RC_INTERMEDIATE_PAI = 0x89, // PAI = Point At Infinity
385  RC_MEMORY_DEADLOCK = 0xC1
387 
389 typedef enum
390 {
396  RC_RIGHT_IS_SMALLER = 0x4
398 
403 typedef struct // 50 bytes long
404 {
405  void* user_data;
407  uint8_t result_cnt;
411 } pka_results_t;
412 
420 
427 
434 
447  void* user_data,
448  pka_operand_t* value,
449  pka_operand_t* addend);
450 
467  void* user_data,
468  pka_operand_t* value,
469  pka_operand_t* subtrahend);
470 
489  void* user_data,
490  pka_operand_t* value,
491  pka_operand_t* addend,
492  pka_operand_t* subtrahend);
493 
509  void* user_data,
510  pka_operand_t* value,
511  pka_operand_t* multiplier);
512 
526  void* user_data,
527  pka_operand_t* value,
528  pka_operand_t* divisor);
529 
543  void* user_data,
544  pka_operand_t* value,
545  pka_operand_t* modulus);
546 
559  void* user_data,
560  pka_operand_t* value,
561  uint32_t shift_cnt);
562 
575  void* user_data,
576  pka_operand_t* value,
577  uint32_t shift_cnt);
578 
594 int pka_dh(pka_handle_t handle,
595  void* user_data,
596  pka_operand_t* private_key,
597  pka_operand_t* modulus,
598  pka_operand_t* value);
599 
615  void* user_data,
616  pka_operand_t* exponent,
617  pka_operand_t* modulus,
618  pka_operand_t* value);
619 
641  void* user_data,
642  pka_operand_t* value,
643  pka_operand_t* p,
644  pka_operand_t* q,
645  pka_operand_t* d_p,
646  pka_operand_t* d_q,
647  pka_operand_t* qinv);
648 
685  void* user_data,
686  pka_operand_t* exponent,
687  pka_operand_t* modulus,
688  pka_operand_t* value);
689 
739  void* user_data,
740  pka_operand_t* p,
741  pka_operand_t* q,
742  pka_operand_t* c,
743  pka_operand_t* d_p,
744  pka_operand_t* d_q,
745  pka_operand_t* qinv);
746 
762  void* user_data,
763  pka_operand_t* value,
764  pka_operand_t* modulus);
765 
766 
769 typedef struct
770 {
773 } ecc_point_t;
774 
787 typedef struct
788 {
792 } ecc_curve_t;
793 
794 typedef enum
795 {
800 
818 typedef struct
819 {
824 
855  void* user_data,
856  ecc_mont_curve_t* curve,
857  pka_operand_t* point_x,
858  pka_operand_t* multiplier);
859 
915  void* user_data,
916  ecc_curve_t* curve,
917  ecc_point_t* pointA,
918  ecc_point_t* pointB);
919 
941  void* user_data,
942  ecc_curve_t* curve,
943  ecc_point_t* pointA,
944  pka_operand_t* multiplier);
945 
970  void* user_data,
971  ecc_mont_curve_t* curve,
972  pka_operand_t* point_x,
973  pka_operand_t* private_key);
974 
995  void* user_data,
996  ecc_curve_t* curve,
997  ecc_point_t* point,
998  pka_operand_t* private_key);
999 
1035  void* user_data,
1036  ecc_curve_t* curve,
1037  ecc_point_t* base_pt,
1038  pka_operand_t* base_pt_order,
1039  pka_operand_t* private_key,
1040  pka_operand_t* hash,
1041  pka_operand_t* k);
1042 
1046 typedef struct
1047 {
1050 } dsa_signature_t;
1051 
1094  void* user_data,
1095  ecc_curve_t* curve,
1096  ecc_point_t* base_pt,
1097  pka_operand_t* base_pt_order,
1098  ecc_point_t* public_key,
1099  pka_operand_t* hash,
1100  dsa_signature_t* rcvd_signature,
1101  uint8_t no_write);
1102 
1132  void* user_data,
1133  pka_operand_t* p,
1134  pka_operand_t* q,
1135  pka_operand_t* g,
1136  pka_operand_t* private_key,
1137  pka_operand_t* hash,
1138  pka_operand_t* k);
1139 
1176  void* user_data,
1177  pka_operand_t* p,
1178  pka_operand_t* q,
1179  pka_operand_t* g,
1180  pka_operand_t* public_key,
1181  pka_operand_t* hash,
1182  dsa_signature_t* rcvd_signature,
1183  uint8_t no_write);
1184 
1195  uint8_t *buf,
1196  uint32_t buf_len);
1197 
1198 #endif // __PKA_H__
int pka_divide(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *divisor)
void pka_term_local(pka_handle_t handle)
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_ecc_pt_add(pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *pointA, ecc_point_t *pointB)
pka_cmp_code_t
PKA Compare Result Code Values.
Definition: pka.h:390
@ RC_RIGHT_IS_SMALLER
Right operand is smaller than left operand ('A' > 'B').
Definition: pka.h:396
@ RC_COMPARE_EQUAL
Both operands are equal ('A' = 'B').
Definition: pka.h:392
@ RC_LEFT_IS_SMALLER
Left operand is smaller than right operand ('A' < 'B').
Definition: pka.h:394
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_shift_left(pka_handle_t handle, void *user_data, pka_operand_t *value, uint32_t shift_cnt)
uint64_t pka_instance_t
PK instance type.
Definition: pka.h:139
pka_mont_curve_t
Definition: pka.h:795
@ PKA_CURVE_448
Definition: pka.h:798
@ PKA_CURVE_NULL
Definition: pka.h:796
@ PKA_CURVE_25519
Definition: pka.h:797
uint8_t pka_get_rings_byte_order(pka_handle_t handle)
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_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_add(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *addend)
pka_flags_t
PK flags that are supplied during PK instance initialization.
Definition: pka.h:152
@ PKA_F_SYNC_MODE_DISABLE
Definition: pka.h:172
@ PKA_F_SYNC_MODE_ENABLE
Definition: pka.h:177
@ PKA_F_PROCESS_MODE_SINGLE
Definition: pka.h:157
@ PKA_F_PROCESS_MODE_MULTI
Definition: pka.h:166
pka_opcode_t
PKA Command Code Values.
Definition: pka.h:290
@ CC_SHIFT_LEFT
Shift left (basic arithmetic).
Definition: pka.h:306
@ CC_MODULAR_EXP
Modular Exponentiation without CRT (complex arithmetic).
Definition: pka.h:314
@ CC_DSA_VERIFY_NO_WRITE
Definition: pka.h:340
@ CC_SHIFT_RIGHT
Shift right (basic arithmetic).
Definition: pka.h:308
@ CC_ECC_PT_ADD
ECC point addition/doubling (complex arithmetic).
Definition: pka.h:322
@ CC_ECDSA_VERIFY_NO_WRITE
Definition: pka.h:337
@ CC_ECC_PT_MULTIPLY
ECC point multiplication (complex arithmetic).
Definition: pka.h:324
@ CC_ECDSA_GENERATE
ECDSA signature generation (high-level PKA operations).
Definition: pka.h:326
@ CC_COPY
Copy (basic arithmetic).
Definition: pka.h:312
@ CC_DIVIDE
Divide (basic arithmetic).
Definition: pka.h:302
@ CC_COMPARE
Compare (basic arithmetic).
Definition: pka.h:310
@ CC_MOD_EXP_CRT
Modular Exponentiation with CRT (complex arithmetic).
Definition: pka.h:316
@ CC_ADD
Add (basic arithmetic).
Definition: pka.h:292
@ CC_DSA_VERIFY
Definition: pka.h:334
@ CC_SUBTRACT
Subtract (basic arithmetic).
Definition: pka.h:294
@ CC_MODULO
Modulo (basic arithmetic).
Definition: pka.h:304
@ CC_MODULAR_INVERT
Modular Inversion (complex arithmetic).
Definition: pka.h:318
@ CC_MONT_ECDH_MULTIPLY
ECC point multiplication on Montgomery Curves (complex arithmetic)
Definition: pka.h:320
@ CC_ADD_SUBTRACT
Add/Subtract combination (basic arithmetic).
Definition: pka.h:296
@ CC_ECDSA_VERIFY
Definition: pka.h:329
@ CC_DSA_GENERATE
DSA signature generation (high-level PKA operations).
Definition: pka.h:331
@ CC_MULTIPLY
Definition: pka.h:300
uint8_t * pka_get_rings_bitmask(pka_instance_t instance)
uint32_t pka_get_rings_count(pka_instance_t instance)
int pka_get_result(pka_handle_t handle, pka_results_t *results)
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_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)
struct pka_local_info_t * pka_handle_t
PK handle (opaque) type that encapsulates local information.
Definition: pka.h:145
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)
void pka_term_global(pka_instance_t instance)
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_rsa(pka_handle_t handle, void *user_data, pka_operand_t *exponent, pka_operand_t *modulus, pka_operand_t *value)
pka_result_code_t
PKA Result Code Values.
Definition: pka.h:345
@ RC_CALCULATION_ERR
Calculated value error.
Definition: pka.h:377
@ RC_EVEN_MODULUS
Modulus was even.
Definition: pka.h:349
@ RC_NO_MODULAR_INVERSE
Modular inverse does not exist.
Definition: pka.h:365
@ RC_NO_ERROR
No error – Normal command completion.
Definition: pka.h:347
@ RC_ENCRYPTED_PARAM_ERR
Illegal encrypted parameter use.
Definition: pka.h:381
@ RC_UNDEFINED_TRIGGER
Host used undefined trigger.
Definition: pka.h:371
@ RC_RESULT_IS_PAI
Result point of ECC operation is 'at infinity' -not a real error.
Definition: pka.h:359
@ RC_INVALID_ADDRESS
Address is invalid.
Definition: pka.h:379
@ RC_MEMORY_DEADLOCK
Memory deadlock error.
Definition: pka.h:385
@ RC_SHORT_MODULUS
Modulus was too short (less than 9 significant bits).
Definition: pka.h:353
@ RC_ECC_RESULT_OFF_CURVE
Result of ECC operation is not on the curve.
Definition: pka.h:367
@ RC_ONE_EXPONENT
Exponent was 1 (for a modular exponentiation).
Definition: pka.h:355
@ RC_OPERAND_VALUE_ERR
Operand value error.
Definition: pka.h:375
@ RC_INVALID_ARGUMENT
Invalid argument.
Definition: pka.h:373
@ RC_ZERO_EXPONENT
Exponent was 0 (for a modular exponentiation).
Definition: pka.h:351
@ RC_TOO_LITTLE_MEMORY
Farm memory too small for operation.
Definition: pka.h:383
@ RC_OPERAND_LENGTH_ERR
Operand length error.
Definition: pka.h:369
@ RC_UNKNOWN_COMMAND
Unknown command.
Definition: pka.h:361
@ RC_INTERMEDIATE_PAI
Intermediate result of ECC operation is 'at infinity' -not a real error.
Definition: pka.h:363
@ RC_BAD_ODD_POWERS
Odd powers not in range 1 … 16.
Definition: pka.h:357
#define MAX_RESULT_CNT
Definition: pka.h:272
int pka_modular_inverse(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
int pka_ecdh(pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *point, pka_operand_t *private_key)
pka_handle_t pka_init_local(pka_instance_t instance)
int pka_modulo(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
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_get_rand_bytes(pka_handle_t handle, uint8_t *buf, uint32_t buf_len)
uint32_t pka_request_count(pka_handle_t handle)
bool pka_has_avail_result(pka_handle_t handle)
int pka_multiply(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *multiplier)
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_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)
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)
Definition: pka.h:1047
pka_operand_t r
big integer value called 'r' in the standard
Definition: pka.h:1048
pka_operand_t s
big integer value called 's' in the standard
Definition: pka.h:1049
Definition: pka.h:788
pka_operand_t b
constant coefficient in defining equation
Definition: pka.h:791
pka_operand_t p
large integer prime defining the finite field
Definition: pka.h:789
pka_operand_t a
coefficient of x in the defining equation
Definition: pka.h:790
Definition: pka.h:819
pka_operand_t p
large integer prime defining the finite field
Definition: pka.h:820
pka_mont_curve_t type
type to depict curve.
Definition: pka.h:822
pka_operand_t A
coefficient of u^2 in the defining equation
Definition: pka.h:821
Definition: pka.h:770
pka_operand_t x
big integer x coordinate of a point on a EC curve
Definition: pka.h:771
pka_operand_t y
big integer y coordinate of a point on a EC curve
Definition: pka.h:772
Definition: pka.h:278
uint16_t buf_len
Size of the buffer holding the big integer.
Definition: pka.h:279
uint16_t actual_len
Actual minimum # of bytes used by the operand.
Definition: pka.h:280
uint8_t * buf_ptr
Pointer to the buffer holding the big integer.
Definition: pka.h:285
uint8_t big_endian
Indicates byte order of the big integer operand.
Definition: pka.h:282
uint8_t internal_use
Internal use. Must be set to 0 by users.
Definition: pka.h:283
uint8_t is_encrypted
Reserved for future use.
Definition: pka.h:281
uint8_t pad
Reserved for future use.
Definition: pka.h:284
Definition: pka.h:404
pka_cmp_code_t compare_result
Result of a comparison.
Definition: pka.h:409
pka_result_code_t status
Same as result_code.
Definition: pka.h:408
pka_opcode_t opcode
Opcode of the associated request.
Definition: pka.h:406
uint8_t result_cnt
Result cnt must be 0, 1 or 2.
Definition: pka.h:407
void * user_data
Opaque data pointer.
Definition: pka.h:405