pka.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: © 2023 NVIDIA Corporation & affiliates.
// SPDX-License-Identifier: BSD-3-Clause
 
 
#ifndef __PKA_H__
#define __PKA_H__
 
#ifdef __KERNEL__
#include <linux/types.h>
#else
#include <stdint.h>
#include <stdbool.h>
#endif
 
typedef uint64_t    pka_instance_t;
 
#define PKA_INSTANCE_INVALID    0
 
typedef struct pka_local_info_t*    pka_handle_t;
 
#define PKA_HANDLE_INVALID      NULL
 
typedef enum
{
    PKA_F_PROCESS_MODE_SINGLE      = 0x1,
    PKA_F_PROCESS_MODE_MULTI       = 0x2,
    PKA_F_SYNC_MODE_DISABLE        = 0x4,
    PKA_F_SYNC_MODE_ENABLE         = 0x8
} pka_flags_t;
 
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);
 
// user_data value used to indicate the context of async_jobs context 
// so that there is no need to acquire lock
#define USER_DATA_POLLING  1
 
#define MAX_OPERAND_CNT     11
 
#define MAX_RESULT_CNT      2
 
#define MAX_BYTE_LEN        520 // 130 * 4 bytes
 
#define OTHER_MAX_BYTE_LEN  264 //  66 * 4 bytes
 
#define MAX_RESULT_CNT   2
 
typedef struct  // 16 bytes long
{
    uint16_t buf_len;       
    uint16_t actual_len;    
    uint8_t  is_encrypted;  
    uint8_t  big_endian;    
    uint8_t  internal_use;  
    uint8_t  pad;           
    uint8_t* buf_ptr;       
} pka_operand_t;
 
typedef enum
{
    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_opcode_t;
 
typedef enum
{
    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,   // Not a real error?
    RC_UNKNOWN_COMMAND       = 0x87,
    RC_INTERMEDIATE_PAI      = 0x89,   // PAI = Point At Infinity
    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_t;
 
typedef enum
{
    RC_COMPARE_EQUAL      = 0x1,
    RC_LEFT_IS_SMALLER    = 0x2,
    RC_RIGHT_IS_SMALLER   = 0x4
} pka_cmp_code_t;
 
typedef struct  // 50 bytes long
{
    void*             user_data;       
    pka_opcode_t      opcode;          
    uint8_t           result_cnt;      
    pka_result_code_t status;          
    pka_cmp_code_t    compare_result;  
    pka_operand_t     results[MAX_RESULT_CNT]; 
} pka_results_t;
 
int pka_get_result(pka_handle_t handle, pka_results_t* results);
 
// This function handles the scenarios of async and sync pka request.
// user_data is used to distinguish the two.
// In sync mode, lock is acquired and relased inside this function.
// In async mode, lock is acquired by caller: polling_func.
int pka_get_result_by_user_data(pka_handle_t handle, pka_results_t* results, 
                        void *user_data);
 
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);
 
 
typedef struct
{
    pka_operand_t x;  
    pka_operand_t y;  
} ecc_point_t;
 
typedef struct
{
    pka_operand_t p;  
    pka_operand_t a;  
    pka_operand_t b;  
} ecc_curve_t;
 
typedef enum
{
    PKA_CURVE_NULL = 0,
    PKA_CURVE_25519,
    PKA_CURVE_448
}pka_mont_curve_t;
 
typedef struct
{
    pka_operand_t    p;    
    pka_operand_t    A;    
    pka_mont_curve_t type; 
} ecc_mont_curve_t;
 
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);
 
typedef struct
{
    pka_operand_t r;  
    pka_operand_t s;  
} dsa_signature_t;
 
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);
 
#endif // __PKA_H__