sys/dev/pci/n8/include_public/n8_pub_common.h

   1 /*-
   2  * Copyright (C) 2001-2003 by NBMK Encryption Technologies.
   3  * All rights reserved.
   4  *
   5  * NBMK Encryption Technologies provides no support of any kind for
   6  * this software.  Questions or concerns about it may be addressed to
   7  * the members of the relevant open-source community at
   8  * <tech-crypto@netbsd.org>.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are
  12  * met:
  13  *
  14  * 1. Redistributions of source code must retain the above copyright
  15  *    notice, this list of conditions and the following disclaimer.
  16  *
  17  * 2. Redistributions in binary form must reproduce the above
  18  *    copyright notice, this list of conditions and the following
  19  *    disclaimer in the documentation and/or other materials provided
  20  *    with the distribution.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 /*****************************************************************************
  36  * @(#) n8_pub_common.h 1.42@(#)
  37  *****************************************************************************/
  38
  39 /*****************************************************************************/
  40 /** @file n8_pub_common.h
  41  *  @brief Common type declarations used in public interface.
  42  *
  43  * Common header file for NetOctave public includes.
  44  *
  45  *****************************************************************************/
  46
  47 /*****************************************************************************
  48  * Revision history:
  49  * 06/30/03 brr   Added N8_HASH_NONE to supported hash algorithms.
  50  * 06/06/03 brr   Brought N8_Hardware_t here from n8_common.
  51  * 05/07/03 brr   Removed type from N8_MemoryHandle_t;
  52  * 04/21/03 brr   Redefined N8_MemoryType_t to support single memory type
  53  *                throughout the SDK.
  54  * 04/01/03 brr   Include n8_sdk_config to pick up configuration.
  55  * 03/10/03 brr   Added support for API callbacks.
  56  * 08/01/02 bac   Documented 'modulusSize' for N8_DH_KeyMaterial_t is in bytes.
  57  * 07/16/02 bac   Removed trailing comma from last enum entry in N8_SKSKeyType_t
  58  * 06/27/02 brr   Support two memory types in N8_MemoryStruct_t.
  59  * 06/14/02 hml   Added N8_MEMORY_KERNEL_BUFFER to N8_MemoryType_t and
  60  *                added bankPhysAddress to N8_MemoryStruct_t.
  61  * 06/12/02 hml   Added bankIndex field to N8_MemoryHandle_t.
  62  * 06/10/02 hml   Added N8_MemoryType_t enum for the type of a memory
  63  *                allocation.
  64  * 03/26/02 hml   Changed N8_INVALID_UNIT to N8_UNINITIALIZED_UNIT to
  65  *                resolve a conflict with our N8_Status_t enum.
  66  * 03/26/02 brr   Added bufferState to N8_MemoryHandle_t.
  67  * 02/01/02 brr   Include only public include files.
  68  * 01/23/02 brr   Added next pointer to N8_MemoryHandle_t.
  69  * 01/12/02 bac   Removed obsolete items contHMAC and doBlockingHMAC from
  70  *                N8_HashObject_t.
  71  * 01/13/02 brr   Removed obsolete fields from N8_MemoryHandle_t.
  72  * 12/03/01 bac   Added entry_name to N8_SKSKeyHandle_t.
  73  * 11/12/01 spm   Added definition for integerized CEIL.
  74  * 11/14/01 msz   Added N8_QUEUE_REQUEST_CALLBACK
  75  * 11/12/01 hml   Added structureID to N8_HashObject_t (bug 261).
  76  * 11/10/01 mmd   Added RawVirtualAddress to N8_MemoryHandle_t, and now includes
  77  *                n8_device_info.h.
  78  * 11/07/01 dkm   Corrected header.
  79  * 11/06/01 hml   Added structureID field to the N8_ContextHandle_t type.
  80  * 10/25/01 dkm   Added comments to N8_RC4_t definition.
  81  * 10/23/01 dkm   Moved N8_ANY_UNIT from n8_common.h.
  82  * 10/22/01 mel   Added doBlockingHMAC to N8_HashObject_t.
  83  * 10/12/01 dkm   Original version. Adapted from n8_common.h.
  84  ****************************************************************************/
  85 #ifndef N8_PUB_COMMON_H
  86 #define N8_PUB_COMMON_H
  87
  88 #ifdef __cplusplus
  89 extern "C"
  90 {
  91 #endif
  92
  93 #if 0
  94 #include "n8_sdk_config.h"
  95 #endif
  96 #include "n8_pub_types.h"
  97 #include "n8_pub_errors.h"
  98
  99 /*************************************************************************
 100  *
 101  *  General Declarations: Not specific to any computational block.
 102  *
 103  ************************************************************************/
 104
 105 #define N8_ANY_UNIT  -1
 106 #define N8_UNINITIALIZED_UNIT -2
 107
 108 #define N8_DEF_MAX_NUM_PARAMS    12 /* Maximum number of parameters a function
 109                                      * called from the command line can accept */
 110
 111 #define CEIL(__A,__B) (((__A)+(__B)-1)/(__B))
 112
 113 /******************************************************************************
 114  * NETOCTAVE GENERIC TYPEDEF'S                                                *
 115  ******************************************************************************/
 116
 117 typedef unsigned char N8_Buffer_t;
 118
 119 typedef struct
 120 {
 121    N8_Buffer_t *value_p;
 122    unsigned int lengthBytes;     /* length of value in bytes */
 123 } N8_SizedBuffer_t;
 124
 125 typedef enum
 126 {
 127    N8_FALSE = 0,
 128    N8_TRUE  = 1
 129 } N8_Boolean_t;
 130
 131 /* N8_Component_t
 132  * Define the different components on the chip.  These may be used as array
 133  * indices so they must remain zero-based and contiguous. */
 134 typedef enum
 135 {
 136    N8_PKP = 0,
 137    N8_RNG = 1,
 138    N8_EA  = 2,
 139    N8_NUM_COMPONENTS = 3
 140 } N8_Component_t;
 141
 142 /*
 143  *  * Hardware types.
 144  *   */
 145 typedef enum
 146 {
 147    N8_NSP2000_HW   = 1,
 148    N8_BM           = 2,
 149    N8_FPGA         = 3
 150 } N8_Hardware_t;
 151
 152
 153 /*****************************************************************************
 154  * N8_ConfigAPI_t
 155  *
 156  *  This structure defines the API configuration. Pass this structure to the
 157  *  N8_InitializeAPI function is optional, unless using the callback thread.
 158  *
 159  *  NOTE: If this structure is modified, the constant N8_INITIALIZATION_VERSION
 160  *        must be changed.
 161  *
 162  *****************************************************************************/
 163 #define  N8_INITIALIZATION_VERSION 1
 164
 165 typedef struct
 166 {
 167    uint32_t      structure_version;/* The version of this strucure.         */
 168    uint32_t      callbackEvents;   /* The maximum number of callback events */
 169                                    /* queued to the API                     */
 170    uint32_t      callbackTimeout;  /* Timeout value for the callback event  */
 171                                    /* completion thread.                    */
 172 } N8_ConfigAPI_t;
 173
 174 /*****************************************************************************
 175  * N8_QueueStatusCodes_t
 176  *
 177  *  This enum contains the status of a request.
 178  *
 179  *  N8_QUEUE_REQUEST_SENT_FROM_API      The request is not yet on the queue
 180  *                                      but has been initialized by SAPI
 181  *  N8_QUEUE_REQUEST_QUEUED             The request is owned by QMGR
 182  *  N8_QUEUE_REQUEST_FINISHED           QMGR is done with the request.
 183  *                                      After setting a request to finished
 184  *                                      QMGR should no longer look at a request
 185  *                                      because a separate thread of SAPI
 186  *                                      code could delete it.
 187  *  N8_QUEUE_REQUEST_COMMAND_ERROR      The request had an error.
 188  *
 189  *****************************************************************************/
 190
 191 /* Status of request/event that is in the queue */
 192 typedef enum
 193 {
 194    N8_QUEUE_REQUEST_SENT_FROM_API         = 1,
 195    N8_QUEUE_REQUEST_QUEUED                = 2,
 196    N8_QUEUE_REQUEST_FINISHED              = 3,
 197    N8_QUEUE_REQUEST_COMMAND_ERROR         = 4
 198 } N8_QueueStatusCodes_t;
 199
 200 /* Type of memory allocation */
 201 typedef enum
 202 {
 203    N8_MEMBANK_QUEUE        = 0,   /* Allocation bank for command queues */
 204    N8_MEMBANK_EA           = 1,   /* Allocation bank for EA requests    */
 205    N8_MEMBANK_PK           = 2,   /* Allocation bank for PK requests    */
 206    N8_MEMBANK_USERPOOL     = 3,   /* Allocation bank for the user pool  */
 207    N8_MEMBANK_MAX          = 4    /* Upper bound for memory bank types  */
 208 } N8_MemoryType_t;
 209
 210
 211 /******************************************************************************
 212  * API RESOURCES -                                                            *
 213  *                                                                            *
 214  * N8_MemoryHandle_t is returned by calls to N8_AllocateBuffer and passed to  *
 215  * N8_FreeBuffer. It simplifies usage of kernel buffer mmap'ed to user space  *
 216  * by encapsulating everything needed to completely name/describe an          *
 217  * allocation. The caller needs only maintain a N8_MemoryHandle_t. The fields *
 218  * serve the following purposes :                                             *
 219  *                                                                            *
 220  * PhysicalAddress - Returns the physical base address of the allocation.     *
 221  * VirtualAddress  - Returns a usable pointer to the base of any allocation,  *
 222  *                   when allocating. Not needed for freeing memory.          *
 223  * Size            - Specifies the desired allocation size (in bytes) when    *
 224  *                   making an allocation call.                               *
 225  * bufferState     - A state variable used to indicate whether the buffer is  *
 226  *                   on an NSP's command queue and cannot be freed until the  *
 227  *                   command has been completed.                              *
 228  *                                                                            *
 229  * The most important note about this structure is that the calling           *
 230  * application must cooperate by using it as a read-only struct.              *
 231  ******************************************************************************/
 232
 233 typedef struct
 234 {
 235      unsigned long    PhysicalAddress;  /* Physical address of allocation */
 236      unsigned long   *VirtualAddress;   /* Virtual address of allocation */
 237      unsigned long    Size;             /* Size of the allocation. */
 238      unsigned long    bufferState;      /* State of buffer vis-a-vis queues */
 239      unsigned long    bankAddress;      /* virtual address of this bank
 240                                            in the process context it was set */
 241      unsigned long    bankPhysAddress;  /* Physical address of this bank */
 242      N8_MemoryType_t  bankIndex;        /* Bank index for the allocation */
 243 } N8_MemoryHandle_t;
 244
 245
 246
 247 /*****************************************************************************
 248  * typedef N8_Unit_t
 249  *****************************************************************************/
 250 /** @ingroup n8_common
 251  *  @typedef N8_Unit_t
 252  *  @brief This type is used for defining unit numbers.
 253  *
 254  *****************************************************************************/
 255 typedef int  N8_Unit_t;
 256
 257 /*****************************************************************************
 258  * typedef N8_Callback_t
 259  *****************************************************************************/
 260 /** @ingroup n8_common
 261  *  @typedef N8_Callback_t
 262  *  @brief This is the prototype of functions performed as callbacks from the
 263  *         API.
 264  *
 265  *****************************************************************************/
 266 typedef void (*N8_Callback_t)(void *, N8_Status_t);
 267 /*
 268  * Event.  This is a placeholder definition for an asynchronous event.
 269  */
 270 typedef struct
 271 {
 272    N8_Component_t         unit;   /* the execution unit the request for this
 273                                    * event is targeted. */
 274    N8_QueueStatusCodes_t  status; /* status of API call this event refers to */
 275    void                  *state;  /* this is opaque data which is not usable by
 276                                    * the user. */
 277 #ifdef SUPPORT_CALLBACKS
 278    N8_Callback_t         usrCallback;     /* User's callback function */
 279    void                  *usrData;        /* Pointer to user's data   */
 280 #endif
 281 } N8_Event_t;
 282
 283 /*************************************************************************
 284  *
 285  *  Hash Common: Common declarations required for hash computations.
 286  *
 287  ************************************************************************/
 288
 289 /* N8_HashAlgorithm_t
 290  * NOTE:  the values used here are not only for identification but are
 291  * also used as indices into an array, thus they need to be contiguous
 292  * and zero-based.
 293  */
 294 typedef enum
 295 {
 296    N8_MD5               = 1,
 297    N8_SHA1,
 298    N8_HMAC_MD5,
 299    N8_HMAC_SHA1,
 300    N8_HMAC_MD5_96,
 301    N8_HMAC_SHA1_96,
 302    N8_HASH_NONE
 303 } N8_HashAlgorithm_t;
 304
 305 #define N8_HASH_BLOCK_SIZE   64
 306 #define N8_MAX_RESIDUAL_LEN (N8_HASH_BLOCK_SIZE / sizeof(N8_Buffer_t))
 307
 308 /*
 309  * Hash object for MD5.  Inspired by
 310  * openssl/crypto/md5/md5.h::MD5state_t and
 311  * openssl/crypto/sha/sha.h::SHA_CTX.
 312  */
 313 typedef struct
 314 {
 315    uint32_t     iv[5];          /* Interim results. Name map:
 316                                  * SHA-1: h0 = iv[0] ... h4 = iv[4]
 317                                  * MD5: A=iv[0] ... D=iv[3]
 318                                  */
 319    uint32_t     ipadHMAC_iv[5]; /* HMAC key XOR with 0x36 */
 320    uint32_t     opadHMAC_iv[5]; /* HMAC key XOR with 0x5C */
 321    uint32_t     hashedHMACKey[16]; /* hashed/padded HMAC key */
 322    uint32_t     opad_Nl, opad_Nh;
 323    uint32_t     Nl, Nh;         /* 64 bit length */
 324    N8_Buffer_t  residual[N8_MAX_RESIDUAL_LEN];
 325                                 /* residual data from previous hash */
 326    int          residualLength; /* in bytes */
 327    N8_HashAlgorithm_t type;     /* type of algorithm initialized */
 328    int          hashSize;       /* size of resulting hash */
 329    N8_Unit_t    unitID;         /* execution unit */
 330    unsigned int structureID;
 331 } N8_HashObject_t;
 332
 333 /*************************************************************************
 334  *
 335  *  PK Common: Common declarations required for public key computations.
 336  *
 337  ************************************************************************/
 338 /*
 339  * Key Types
 340  */
 341 typedef enum
 342 {
 343    N8_PUBLIC       = 1,
 344    N8_PRIVATE      = 2,
 345    N8_PRIVATE_CRT  = 3,
 346    N8_PRIVATE_SKS  = 4
 347 } N8_KeyType_t;
 348
 349 typedef enum
 350 {
 351    N8_RSA_VERSION_1_KEY   = 1,
 352    N8_DSA_VERSION_1_KEY   = 2
 353 } N8_SKSKeyType_t;
 354
 355 #define N8_SKS_ENTRY_NAME_MAX_LENGTH 256
 356 typedef struct
 357 {
 358    N8_SKSKeyType_t     key_type;
 359    uint32_t            key_length; /* BNC digits */
 360    N8_Unit_t           unitID;
 361    uint32_t            sks_offset; /* SKS words */
 362    char                entry_name[N8_SKS_ENTRY_NAME_MAX_LENGTH];
 363 } N8_SKSKeyHandle_t;
 364
 365 /*
 366  * RSA Key Material
 367  */
 368 typedef struct
 369 {
 370    N8_SizedBuffer_t  publicKey;       /* present for public & private contexts */
 371    N8_SizedBuffer_t  privateKey;      /* present only for private context */
 372    N8_SizedBuffer_t  n;               /* modulus n = pq */
 373    N8_SizedBuffer_t  p;
 374    N8_SizedBuffer_t  q;
 375    N8_Unit_t         unitID;           /* Execution unit for request */
 376    N8_SKSKeyHandle_t SKSKeyHandle;     /* contains SKS info */
 377 } N8_RSAKeyMaterial_t;
 378
 379 /*
 380  * DSA Key Material
 381  */
 382 typedef struct
 383 {
 384    N8_SizedBuffer_t  publicKey;    /* present for public & private contexts */
 385    N8_SizedBuffer_t  privateKey;   /* present only for private context */
 386    N8_SizedBuffer_t  p;            /* prime modulus */
 387    N8_SizedBuffer_t  q;            /* prime divisor */
 388    N8_SizedBuffer_t  g;            /* generator */
 389    N8_Unit_t         unitID;       /* Unit id on which to execute this
 390                                       request */
 391    N8_SKSKeyHandle_t SKSKeyHandle; /* contains SKS info */
 392 } N8_DSAKeyMaterial_t;
 393
 394 /*
 395  * Diffie-Hellman Key Material
 396  */
 397 typedef struct
 398 {
 399    N8_Buffer_t        *p;           /* modulus */
 400    N8_Buffer_t        *g;           /* generator */
 401    unsigned int        modulusSize; /* modulus size in bytes */
 402    N8_Unit_t           unitID;      /* execution unit for this request */
 403 } N8_DH_KeyMaterial_t;
 404
 405 /***************************************************************
 406  *
 407  *  Context Common: Common declarations required for
 408  *                  context memory management.
 409  *
 410  **************************************************************/
 411
 412 /* Structure for context identification */
 413 typedef struct
 414 {
 415    unsigned int index;
 416    N8_Boolean_t    inUse;
 417    N8_Unit_t    unitID;
 418    int          structureID;
 419 } N8_ContextHandle_t;
 420
 421
 422 /****************************************************************************
 423  *
 424  *  Packet Common: Common declarations required for private key computations.
 425  *
 426  ***************************************************************************/
 427
 428 /* DES Key length used in RNG and Packet Processing */
 429 #define N8_DES_KEY_LENGTH 8
 430
 431 /* The permissible values for Cipher depend on the value of Protocol,
 432     and include the values ARC4 and DES. */
 433 typedef enum
 434 {
 435    N8_CIPHER_ARC4     = 1,
 436    N8_CIPHER_DES
 437 } N8_Cipher_t;
 438
 439 #ifdef __cplusplus
 440 }
 441 #endif
 442
 443 #endif
 444
 445