sys/dev/pci/n8/include_public/n8_pub_rng.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_rng.h 1.5@(#)
  37  *****************************************************************************/
  38
  39 /*****************************************************************************/
  40 /** @file n8_pub_rng
  41  *  @brief Public declarations for random number operations.
  42  *
  43  * Public header file for random number operations.
  44  *
  45  *****************************************************************************/
  46
  47 /*****************************************************************************
  48  * Revision history:
  49  * 05/15/03 brr   Add N8_RNG_MAX_REQUEST.
  50  * 10/12/01 dkm   Original version. Adapted from n8_rncommon.h.
  51  ****************************************************************************/
  52 #ifndef N8_PUB_RNG_H
  53 #define N8_PUB_RNG_H
  54
  55 #ifdef __cplusplus
  56 extern "C"
  57 {
  58 #endif
  59
  60 #include "n8_pub_common.h"
  61
  62 /* Maximum number of random bytes permitted in a single request. */
  63 #define N8_RNG_MAX_REQUEST         (8 * 1024)
  64
  65 /*
  66  * Seed source values.
  67  * These values will be modified to the expected values set by the hardware
  68  * spec in N8_SetRNGParameters().
  69  */
  70 typedef enum
  71 {
  72    N8_RNG_SEED_INTERNAL,
  73    N8_RNG_SEED_EXTERNAL,
  74    N8_RNG_SEED_HOST,
  75 } N8_RNG_Seed_t;
  76
  77
  78 /*****************************************************************************
  79  * Structures/type definitions
  80  *****************************************************************************/
  81
  82 typedef struct
  83 {
  84
  85   /* The following are entities in the control status register.  They   */
  86   /* should always be set.                                              */
  87
  88    /* Time of day counter enable.  Enables time of day counter to       */
  89    /* operate.  This should be set to N8_TRUE.                           */
  90    N8_Boolean_t      todEnable;
  91
  92    /* Enables use of external clock signal for an external seed source. */
  93    /* Should be set N8_TRUE only if/when the exteranl seed source is     */
  94    /* selected.                                                         */
  95    N8_Boolean_t      use_external_clock;
  96
  97    /* Data source of seed values.                                       */
  98    uint32_t       seed_source;
  99
 100    /* Iteratation count is the number of random 64-bit values generated */
 101    /* from each key.  The value may range from 1-256, and this value    */
 102    /* must be in that range.  Note that in the hardware the value       */
 103    /* stored in the control register is actually 1 less than the value  */
 104    /* specified here.                                                   */
 105    unsigned short iteration_count;
 106
 107    /* Pre-scale value for TOD.  Should be set to the clock frequency    */
 108    /* of the chip.                                                      */
 109    uint32_t       TOD_prescale;
 110
 111    /* Tells whether or not to use the initial_TOD_seconds field below.  */
 112    /* will be set to N8_FALSE on a get of this value.                    */
 113    N8_Boolean_t      set_TOD_counter;
 114
 115    /* DES keys for the X9.17 algorithm.  Will be forced to valid parity */
 116    /* These should be set to random values.                             */
 117    uint8_t        key1[N8_DES_KEY_LENGTH];
 118    uint8_t        key2[N8_DES_KEY_LENGTH];
 119
 120   /* The following entities may be ignored depending on the values      */
 121   /* set above.                                                         */
 122
 123    /* Host seed for X9.17 algorithm                                     */
 124    /* If seed_source is set to host seed, then the user must specify    */
 125    /* each seed value used to generate random values.  After each       */
 126    /* iteration_count number of 64-bit random values have been          */
 127    /* generated, a new hostSeed value must be supplied in order to      */
 128    /* continue generating more values.  If seed_source is not set to    */
 129    /* host seed then this value should not be set and is ignored.       */
 130    uint8_t        hostSeed[N8_DES_KEY_LENGTH];
 131
 132    /* Value to initialize the Time Of Day value (seconds).              */
 133    /* Ignored if set_TOD_counter is N8_FALSE.                            */
 134    uint32_t       initial_TOD_seconds;
 135
 136    /* The external clock scaler is the number of systems clock cycles   */
 137    /* cycles in each external clock cycle.  See the NSP 2000 Data       */
 138    /* Sheet for details.  This value is only used when seed source is   */
 139    /* set to external source, and then external clock should also be    */
 140    /* set to N8_TRUE.  Only the lower 20 bits of this are valid.         */
 141    uint32_t       externalClockScaler;
 142
 143   /* The following entities are ignored on a set, and are valid on a    */
 144   /* get.                                                               */
 145
 146    /* Host seed valid.  A N8_TRUE indication means that the host seed    */
 147    /* has not been consumed.  A N8_FALSE indication means that the host  */
 148    /* seed has been exhausted.  The user should check that this is      */
 149    /* N8_FALSE before writing a host seed to insure that a previous host */
 150    /* seed has won't be overwritten.  If this value is N8_FALSE the RNG  */
 151    /* will eventually stop providing random numbers until a new host    */
 152    /* seed is provided.                                                 */
 153    N8_Boolean_t      hostSeedValid;
 154
 155    /* The RNG core sets this bit (N8_TRUE) when a seed duplication error */
 156    /* is detected.  When this bit is set, and set_diagnostic_mode is    */
 157    /* not set (N8_FALSE), the RNG core will be disabled (halted.)        */
 158    N8_Boolean_t      seedErrorFlag;
 159
 160    /* The RNG core sets this bit (N8_TRUE) when an X9.17 duplication     */
 161    /* error is detected. When this bit is set, and set_diagnostic_mode  */
 162    /* is not set (N8_FALSE), the RNG core will be disabled (halted.)     */
 163    N8_Boolean_t      x9_17_errorFlag;
 164
 165    /* This returns the value of the last valid seed produced by the     */
 166    /* seed generator.                                                   */
 167    uint32_t       seedValue_ms;
 168    uint32_t       seedValue_ls;
 169
 170 } N8_RNG_Parameter_t;
 171
 172 /*****************************************************************************
 173  * Function prototypes
 174  *****************************************************************************/
 175 /*
 176  * Set Random Number Generator parameters
 177  */
 178 N8_Status_t N8_SetRNGParameters(N8_RNG_Parameter_t *p);
 179 N8_Status_t N8_GetRNGParameters(N8_RNG_Parameter_t *p);
 180 N8_Status_t N8_GetRandomBytes(int num_bytes, char *buf, N8_Event_t *event_p);
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif
 185
 186 #endif
 187
 188