Public Key Acceleration Library Reference Guide  1.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros
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 {
178 } pka_flags_t;
179 
199 pka_instance_t pka_init_global(const char* name,
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 
210 void pka_term_global(pka_instance_t instance);
211 
217 uint32_t pka_get_rings_count(pka_instance_t instance);
218 
224 uint32_t pka_get_rings_bitmask(pka_instance_t instance);
225 
236 
241 void pka_term_local(pka_handle_t handle);
242 
247 uint8_t pka_get_rings_byte_order(pka_handle_t handle);
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,
339 } pka_opcode_t;
340 
342 typedef enum
343 {
345  RC_NO_ERROR = 0x00,
357  RC_RESULT_IS_PAI = 0x86, // Not a real error?
361  RC_INTERMEDIATE_PAI = 0x89, // PAI = Point At Infinity
385 
387 typedef enum
388 {
396 
401 typedef struct // 50 bytes long
402 {
403  void* user_data;
405  uint8_t result_cnt;
409 } pka_results_t;
410 
417 int pka_get_result(pka_handle_t handle, pka_results_t* results);
418 
425 
431 uint32_t pka_request_count(pka_handle_t handle);
432 
444 int pka_add(pka_handle_t handle,
445  void* user_data,
446  pka_operand_t* value,
447  pka_operand_t* addend);
448 
464 int pka_subtract(pka_handle_t handle,
465  void* user_data,
466  pka_operand_t* value,
467  pka_operand_t* subtrahend);
468 
486 int pka_add_subtract(pka_handle_t handle,
487  void* user_data,
488  pka_operand_t* value,
489  pka_operand_t* addend,
490  pka_operand_t* subtrahend);
491 
506 int pka_multiply(pka_handle_t handle,
507  void* user_data,
508  pka_operand_t* value,
509  pka_operand_t* multiplier);
510 
523 int pka_divide(pka_handle_t handle,
524  void* user_data,
525  pka_operand_t* value,
526  pka_operand_t* divisor);
527 
540 int pka_modulo(pka_handle_t handle,
541  void* user_data,
542  pka_operand_t* value,
543  pka_operand_t* modulus);
544 
556 int pka_shift_left(pka_handle_t handle,
557  void* user_data,
558  pka_operand_t* value,
559  uint32_t shift_cnt);
560 
572 int pka_shift_right(pka_handle_t handle,
573  void* user_data,
574  pka_operand_t* value,
575  uint32_t shift_cnt);
576 
591 int pka_modular_exp(pka_handle_t handle,
592  void* user_data,
593  pka_operand_t* exponent,
594  pka_operand_t* modulus,
595  pka_operand_t* value);
596 
618  void* user_data,
619  pka_operand_t* value,
620  pka_operand_t* p,
621  pka_operand_t* q,
622  pka_operand_t* d_p,
623  pka_operand_t* d_q,
624  pka_operand_t* qinv);
625 
661 int pka_rsa(pka_handle_t handle,
662  void* user_data,
663  pka_operand_t* exponent,
664  pka_operand_t* modulus,
665  pka_operand_t* value);
666 
715 int pka_rsa_crt(pka_handle_t handle,
716  void* user_data,
717  pka_operand_t* p,
718  pka_operand_t* q,
719  pka_operand_t* c,
720  pka_operand_t* d_p,
721  pka_operand_t* d_q,
722  pka_operand_t* qinv);
723 
739  void* user_data,
740  pka_operand_t* value,
741  pka_operand_t* modulus);
742 
743 
746 typedef struct
747 {
750 } ecc_point_t;
751 
764 typedef struct
765 {
769 } ecc_curve_t;
770 
825 int pka_ecc_pt_add(pka_handle_t handle,
826  void* user_data,
827  ecc_curve_t* curve,
828  ecc_point_t* pointA,
829  ecc_point_t* pointB);
830 
851 int pka_ecc_pt_mult(pka_handle_t handle,
852  void* user_data,
853  ecc_curve_t* curve,
854  ecc_point_t* pointA,
855  pka_operand_t* multiplier);
856 
892  void* user_data,
893  ecc_curve_t* curve,
894  ecc_point_t* base_pt,
895  pka_operand_t* base_pt_order,
896  pka_operand_t* private_key,
897  pka_operand_t* hash,
898  pka_operand_t* k);
899 
903 typedef struct
904 {
908 
951  void* user_data,
952  ecc_curve_t* curve,
953  ecc_point_t* base_pt,
954  pka_operand_t* base_pt_order,
955  ecc_point_t* public_key,
956  pka_operand_t* hash,
957  dsa_signature_t* rcvd_signature,
958  uint8_t no_write);
959 
989  void* user_data,
990  pka_operand_t* p,
991  pka_operand_t* q,
992  pka_operand_t* g,
993  pka_operand_t* private_key,
994  pka_operand_t* hash,
995  pka_operand_t* k);
996 
1033  void* user_data,
1034  pka_operand_t* p,
1035  pka_operand_t* q,
1036  pka_operand_t* g,
1037  pka_operand_t* public_key,
1038  pka_operand_t* hash,
1039  dsa_signature_t* rcvd_signature,
1040  uint8_t no_write);
1041 
1042 
1043 #endif // __PKA_H__
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)
uint8_t * buf_ptr
Pointer to the buffer holding the big integer.
Definition: pka.h:285
Subtract (basic arithmetic).
Definition: pka.h:294
Modulus was even.
Definition: pka.h:347
pka_result_code_t
PKA Result Code Values.
Definition: pka.h:342
pka_flags_t
PK flags that are supplied during PK instance initialization.
Definition: pka.h:151
Definition: pka.h:172
void pka_term_global(pka_instance_t instance)
Definition: pka.h:300
Definition: pka.h:335
Modulo (basic arithmetic).
Definition: pka.h:304
uint8_t is_encrypted
Reserved for future use.
Definition: pka.h:281
Illegal encrypted parameter use.
Definition: pka.h:379
pka_opcode_t opcode
Opcode of the associated request.
Definition: pka.h:404
Definition: pka.h:177
Exponent was 1 (for a modular exponentiation).
Definition: pka.h:353
int pka_modular_exp(pka_handle_t handle, void *user_data, pka_operand_t *exponent, pka_operand_t *modulus, pka_operand_t *value)
No error – Normal command completion.
Definition: pka.h:345
pka_operand_t r
big integer value called &#39;r&#39; in the standard
Definition: pka.h:905
pka_operand_t y
big integer y coordinate of a point on a EC curve
Definition: pka.h:749
int pka_get_result(pka_handle_t handle, pka_results_t *results)
#define MAX_RESULT_CNT
Definition: pka.h:272
Modular Inversion (complex arithmetic).
Definition: pka.h:318
Definition: pka.h:746
Definition: pka.h:332
Definition: pka.h:764
uint32_t pka_request_count(pka_handle_t handle)
pka_result_code_t status
Same as result_code.
Definition: pka.h:406
Shift left (basic arithmetic).
Definition: pka.h:306
void * user_data
Opaque data pointer.
Definition: pka.h:403
uint32_t pka_get_rings_count(pka_instance_t instance)
Add (basic arithmetic).
Definition: pka.h:292
int pka_ecc_pt_add(pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *pointA, ecc_point_t *pointB)
struct pka_local_info_t * pka_handle_t
PK handle (opaque) type that encapsulates local information.
Definition: pka.h:145
Host used undefined trigger.
Definition: pka.h:369
uint8_t pka_get_rings_byte_order(pka_handle_t handle)
ECC point addition/doubling (complex arithmetic).
Definition: pka.h:320
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_ecc_pt_mult(pka_handle_t handle, void *user_data, ecc_curve_t *curve, ecc_point_t *pointA, pka_operand_t *multiplier)
Definition: pka.h:277
int pka_rsa(pka_handle_t handle, void *user_data, pka_operand_t *exponent, pka_operand_t *modulus, pka_operand_t *value)
Memory deadlock error.
Definition: pka.h:383
Add/Subtract combination (basic arithmetic).
Definition: pka.h:296
Calculated value error.
Definition: pka.h:375
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)
Invalid argument.
Definition: pka.h:371
Exponent was 0 (for a modular exponentiation).
Definition: pka.h:349
int pka_modular_inverse(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
Unknown command.
Definition: pka.h:359
pka_operand_t a
coefficient of x in the defining equation
Definition: pka.h:767
ECDSA signature generation (high-level PKA operations).
Definition: pka.h:324
uint32_t pka_get_rings_bitmask(pka_instance_t instance)
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)
pka_operand_t p
large integer prime defining the finite field
Definition: pka.h:766
Operand value error.
Definition: pka.h:373
DSA signature generation (high-level PKA operations).
Definition: pka.h:329
Shift right (basic arithmetic).
Definition: pka.h:308
Operand length error.
Definition: pka.h:367
int pka_subtract(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *subtrahend)
Farm memory too small for operation.
Definition: pka.h:381
pka_opcode_t
PKA Command Code Values.
Definition: pka.h:289
Copy (basic arithmetic).
Definition: pka.h:312
Result of ECC operation is not on the curve.
Definition: pka.h:365
uint8_t internal_use
Internal use. Must be set to 0 by users.
Definition: pka.h:283
uint16_t actual_len
Actual minimum # of bytes used by the operand.
Definition: pka.h:280
Divide (basic arithmetic).
Definition: pka.h:302
uint8_t result_cnt
Result cnt must be 0, 1 or 2.
Definition: pka.h:405
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)
uint16_t buf_len
Size of the buffer holding the big integer.
Definition: pka.h:279
Modular Exponentiation with CRT (complex arithmetic).
Definition: pka.h:316
Definition: pka.h:903
pka_cmp_code_t
PKA Compare Result Code Values.
Definition: pka.h:387
Left operand is smaller than right operand (&#39;A&#39; &lt; &#39;B&#39;).
Definition: pka.h:392
int pka_shift_right(pka_handle_t handle, void *user_data, pka_operand_t *value, uint32_t shift_cnt)
Modulus was too short (less than 9 significant bits).
Definition: pka.h:351
int pka_add(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *addend)
Intermediate result of ECC operation is &#39;at infinity&#39; -not a real error.
Definition: pka.h:361
void pka_term_local(pka_handle_t handle)
Address is invalid.
Definition: pka.h:377
Modular Exponentiation without CRT (complex arithmetic).
Definition: pka.h:314
Modular inverse does not exist.
Definition: pka.h:363
pka_operand_t x
big integer x coordinate of a point on a EC curve
Definition: pka.h:748
uint8_t big_endian
Indicates byte order of the big integer operand.
Definition: pka.h:282
pka_handle_t pka_init_local(pka_instance_t instance)
Definition: pka.h:338
uint64_t pka_instance_t
PK instance type.
Definition: pka.h:139
pka_operand_t s
big integer value called &#39;s&#39; in the standard
Definition: pka.h:906
int pka_multiply(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *multiplier)
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)
pka_operand_t b
constant coefficient in defining equation
Definition: pka.h:768
Both operands are equal (&#39;A&#39; = &#39;B&#39;).
Definition: pka.h:390
Compare (basic arithmetic).
Definition: pka.h:310
ECC point multiplication (complex arithmetic).
Definition: pka.h:322
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)
Result point of ECC operation is &#39;at infinity&#39; -not a real error.
Definition: pka.h:357
pka_cmp_code_t compare_result
Result of a comparison.
Definition: pka.h:407
Odd powers not in range 1 … 16.
Definition: pka.h:355
int pka_shift_left(pka_handle_t handle, void *user_data, pka_operand_t *value, uint32_t shift_cnt)
int pka_modulo(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *modulus)
int pka_divide(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *divisor)
Definition: pka.h:401
Definition: pka.h:166
Definition: pka.h:157
uint8_t pad
Reserved for future use.
Definition: pka.h:284
Definition: pka.h:327
bool pka_has_avail_result(pka_handle_t handle)
Right operand is smaller than left operand (&#39;A&#39; &gt; &#39;B&#39;).
Definition: pka.h:394
int pka_add_subtract(pka_handle_t handle, void *user_data, pka_operand_t *value, pka_operand_t *addend, pka_operand_t *subtrahend)