7/31/2017
Nitrox-Installation and User Guide
Cavium
Document
Revision
Networks
0.3
Nitrox-Installation and User Guide
Nitrox-Installation and User Guide
Revision
0.1
0.2
0.3
Date
07/27/03
09/26/03
02/17/04
Who
FM
FM
FM
Confidential and Proprietary
Description
Initial Revision
Added uninstall procedure in the driver installation section
Added section explaining how to install a board other than
CN1010
Cavium Networks
Page 1 of 17
7/31/2017
Nitrox-Installation and User Guide
Nitrox-Installation and User Guide ..................................................................................... 1
Introduction ......................................................................................................................... 4
1 Installation................................................................................................................... 5
1.1
Deleting the old driver and corresponding files .................................................. 5
1.2
Installing the new driver ..................................................................................... 5
2 NITROX board configuration ..................................................................................... 7
2.1
Configuring NITROX board before installation – nitrox.inf .............................. 7
2.1.1
Pre-allocated buffer sizes and counts .......................................................... 7
2.1.2
Board specific configuration ....................................................................... 8
2.2
Configuring NITROX board after installation .................................................... 9
3 Special notes for installing board other than the default (CN1010) ......................... 11
4 Sample Test Application ........................................................................................... 12
5 User Guide ................................................................................................................ 13
5.1
Initialization and shutdown ............................................................................... 14
5.1.1
Csp1Initialize ............................................................................................ 14
5.1.2
Csp1ShutDown ......................................................................................... 14
5.2
Memory management/Resource allocation....................................................... 14
5.2.1
Csp1AllocContext ..................................................................................... 14
5.2.2
Csp1FreeContext....................................................................................... 14
5.2.3
Csp1AllocKeyMem .................................................................................. 14
5.2.4
Csp1FreeKeyMem .................................................................................... 14
5.2.5
Csp1StoreKey ........................................................................................... 14
5.2.6
Csp1ReadContext ..................................................................................... 14
5.2.7
Csp1WriteContext..................................................................................... 14
5.2.8
Csp1CheckForCompletion ........................................................................ 15
5.3
Security protocol processing ............................................................................. 15
5.3.1
Csp1Random ............................................................................................. 15
5.3.2
Csp1Hmac ................................................................................................. 15
5.3.3
Csp1HmacStart ......................................................................................... 15
5.3.4
Csp1HmacUpdate ..................................................................................... 15
5.3.5
Csp1HmacFinish ....................................................................................... 15
5.3.6
Csp1Me ..................................................................................................... 15
5.3.7
Csp1Pkcs1v15Enc..................................................................................... 15
5.3.8
Csp1Pkcs1v15CrtEnc ............................................................................... 16
5.3.9
Csp1Pkcs1v15Dec .................................................................................... 16
5.3.10
Csp1Pkcs1v15CrtDec ............................................................................... 16
5.3.11
Csp1InitializeRc4 ...................................................................................... 16
5.3.12
Csp1EncryptRc4 ....................................................................................... 16
5.3.13
Csp1Initialize3DES................................................................................... 16
5.3.14
Csp1Encrypt3DES .................................................................................... 16
5.3.15
Csp1Descrypt3DES .................................................................................. 16
5.3.16
Csp1InitializeAES..................................................................................... 16
5.3.17
Csp1EncryptAES ...................................................................................... 16
5.3.18
Csp1DecryptAES ...................................................................................... 16
Confidential and Proprietary
Cavium Networks
Page 2 of 17
7/31/2017
5.3.19
5.3.20
5.3.21
5.3.22
Nitrox-Installation and User Guide
Csp1Handshake......................................................................................... 17
Csp1HandshakeStart ................................................................................. 17
Csp1HandshakeUpdate ............................................................................. 17
Csp1HandshakeFinish............................................................................... 17
Confidential and Proprietary
Cavium Networks
Page 3 of 17
7/31/2017
Nitrox-Installation and User Guide
Introduction
The NITROX processor provides acceleration of cryptographic algorithms and protocols
processing. It is a PCI/PCIX based solution which can plug-in to any 3.3 volt PCI slot.
NITROX API and Driver software have been designed to achieve the following
objectives:






High performance of the system
Robust behavior and error tolerance
Hardware layer abstraction
Manageability of software code
Minimal customer code development for ease of integration
High-level APIs written to address all the application requirements
The NITROX APIs and driver architecture addresses these objectives by using design
that is both scalable and manageable. The principal layers include and device driver, the
API and the application layer as shown below:
APPLICATION
API
DEVICE DRIVER
PCI
NITROX board
Confidential and Proprietary
Cavium Networks
Page 4 of 17
7/31/2017
Nitrox-Installation and User Guide
1 Installation
Follow the steps below to install the driver for NITROX board: (Note: these installation
instructions are shown for Win2003)
1.1 Deleting the old driver and corresponding files
It is advisable to un-install the old nitrox driver and delete the corresponding files before
installing the new driver. Windows keep history of all the installed drivers. If a driver has
been uninstalled, windows does not delete its corresponding driver files, just in case the
same hardware is plugged again in the future.
Please follow these steps to delete the older driver files (pkp or nitrox):
1. Uninstall the old driver (pkp or nitrox) using the device manager. (right click on
the device and select uninstall).
2. Delete the driver sys file (pkp.sys or nitrox.sys) from ‘c:\winnt\system32\drivers’
directory (replace c:\winnt with the windows installation directory). Delete also
the ‘code0.dat’, ‘code1.dat’ and ‘microcode.cst’ from the same directory (i.e.
c:\winnt\system32).
3. Make sure that in folder settings (Tools->folder options->view), ‘Show hidden
files and folders’ option is selected.
4. Go to ‘inf’ folder in the windows directory.
5. Search for all the files with the name starting from ‘oem’ and have the extension
‘inf’. Open each file and search for ‘cavium’. Once you have found the file, delete
this file and the corresponding ‘.pnf’ file.
1.2 Installing the new driver
Follow these steps to install the new driver:
1. Copy the driver and all the corresponding files to a directory (e.g.
c:\install\driver). The following files are required for the proper driver
installation:
nitrox.sys
nitrox.inf
nitrox.cat
code0.dat (Microcode even code – loaded to the chip at startup)
code1.dat (Microcode odd code – loaded to the chip at startup)
microcode.cst (Microcode constants – loaded to the chip at startup)
2. Turn off the computer.
3. Plug in the Nitrox crypto accelerator to an available pci slot.
Confidential and Proprietary
Cavium Networks
Page 5 of 17
7/31/2017
Nitrox-Installation and User Guide
4. Turn the computer back on.
5. The o/s will detect a pci device. Follow the installation wizard. (you can also use
the add hardware wizard instead).
6. Select the advanced option.
7. When asked, specify the location where the driver files are. (e.g. c:\install\driver).
The wizard will pick up the inf file and will install the supported files.
8. After the installation completes, check the device manager to make sure the driver
has been installed properly.
Confidential and Proprietary
Cavium Networks
Page 6 of 17
7/31/2017
Nitrox-Installation and User Guide
2 NITROX board configuration
Different board parameters can be configured using either the ‘nitrox.inf’ file before the
installation, or the registry after the installation.
2.1 Configuring NITROX board before installation – nitrox.inf
Nitrox.inf file consists of various configurable parameters that can be configured before
the installation of the board. The list of all the parameters and their values are explained
below:
2.1.1 Pre-allocated buffer sizes and counts
These values control how many buffers to be allocated when the driver starts and what is
their size. The input data is copied from user buffer to these pre-allocated buffers before
it is sent to the chip. The output is also copied back from these buffers to the user buffer.
These buffers are allocated using the physical memory of the system which means that
the size and count of these buffers depend on the physical memory present in the system.
Parameter Name
ExTinyBufferSize
ExTinyBufferCount
TinyBufferSize
TinyBufferCount
SmallBufferSize
SmallBufferCount
MediumBufferSize
MediumBufferCount
LargeBufferSize
LargeBufferCount
HugeBufferSize
HugeBufferCount
Description
extra tiny buffer size
no. of extra tiny buffers
tiny buffer size
no. of tiny buffers
small buffer size
no. of small buffers
medium buffer size
no. of medium buffers
large buffer size
no. of large buffers
huge buffer size
no. of huge buffers
Default Value
1024
500
2048
150
5376
350
10240
100
16384
16
32768
10
When a request is received from an application, the driver gets a pre-allocated buffer
using the size of the input request, copies the data to this buffer and sends the address of
the pre-allocated buffer to the chip. It also sends the address of another pre-allocated
buffer which is used to hold the results generated by the chip. The NITROX chip
processes the data, and puts the results in the result buffer. The driver copies back the
data form the pre-allocated result buffer to the user buffer. The two pre-allocated buffer
used in this process can now be re-used with another request.
Confidential and Proprietary
Cavium Networks
Page 7 of 17
7/31/2017
Nitrox-Installation and User Guide
2.1.2 Board specific configuration
These parameters set the board type and its capabilities. The following parameters can be
set:
Parameter Name
BoardType
DebugEnable
CommandQueueSize
CtxMemSizeInHost
CtxChunkSize
InitTWSI
MaxCores
CoreMask0
CoreMask1
CoreMask2
Description
Nitrox crypto board type.
(valid types are: CN501,
CN1001, CN1005, CN1010,
CN1120, CN1220, CN1230)
Enable/disable the DbgPrint
Command queue size.
Command queue holds all
the request which are picked
up by the NITROX chip.
context memory size in host.
Context memory holds keys,
IVs and other application
specific information. (this
configuration is only
applicable if there is no
external DDR memory
available)
Each context memory block
size
If set, initializes the TWSI
(Two wire serial interface)
interface (Note: if this value
is 0, the auto DDR discovery
will also be disabled. For all
the CN10xx and CN11xx
type boards, this should be 0)
Max number of cores
available
For CN501 this is 2
For CN1001 this is 1
For CN1005 this is 2
For CN1010 this is 4
For CN1120 this is 8
For CN1220 this is 8
For CN1230 this is 16
Core masks for different
boards:
These masks should have the
following values:
Default Value
CN1010
0 (disable)
2048
1048576
512
0 (don't init)
4
0x0000000F
0x0000000F
0x0000000F
CN501:
core mask 0 : 0x00000003
core mask 1 : 0x00000003
core mask 2 : 0x00000003
Confidential and Proprietary
Cavium Networks
Page 8 of 17
7/31/2017
Nitrox-Installation and User Guide
CN1001:
core mask 0 : 0x00000001
core mask 1 : 0x00000001
core mask 2 : 0x00000001
CN1005:
core mask 0 : 0x00000003
core mask 1 : 0x00000003
core mask 2 : 0x00000003
CN1010:
core mask 0 : 0x0000000F
core mask 1 : 0x0000000F
core mask 2 : 0x0000000F
CN1120:
core mask 0 : 0x000000FF
core mask 1 : 0x00000F0F
core mask 2 : 0x000F000F
CN1220:
core mask 0 : 0x000000FF
core mask 1 : 0x00000F0F
core mask 2 : 0x000F000F
MicroCodeEven
MicroCodeOdd
MicroData
CN1230:
core mask 0 : 0x00FF00FF
core mask 1 : 0x0000FFFF
core mask 2 : 0x000FFF0F
Microcode even data
Microcode odd data
Microcode constants
\SystemRoot\System32\code0.dat
\SystemRoot\System32\code1.dat
\SystemRoot\System32\microcode.cst
2.2 Configuring NITROX board after installation
Once the nitrox accelerator has been installed, its settings can be changed through the
registry. After changing the values in the registry, restart the system and the driver will
pickup the new values.
All the inf file configuration values are stored in the following registry location:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Nitrox
The subkey 'Buffer' contains the pre-allocated pool buffer configuration. The subkey
'Configuration' contains the board type, masks and other configuration information.
Confidential and Proprietary
Cavium Networks
Page 9 of 17
7/31/2017
Nitrox-Installation and User Guide
There is an additional key called 'LastError' in the Configuration subkey. This stores the
last error occurred during the board installation or operation. This is useful to debug the
error. The error code is 4 bytes, and rest of the filed is appended by extra debug
information (if there is any).
Confidential and Proprietary
Cavium Networks
Page 10 of 17
7/31/2017
Nitrox-Installation and User Guide
3 Special notes for installing board other than the
default (CN1010)
Nitrox driver works for various CNXXX boards. All the board specific information is
stored in and retrieved from the windows registry.
CN1010 is configured as the default board, and the configuration in the windows registry
is setup accordingly. In order to make another board (other than CN1010) working,
windows registry settings need re-configuration.
Follow these setups to configure a board other than CN1010:
1. If a Nitrox board has ever been installed on the machine, windows will have the
driver and registry settings already. After plugging in the new board, you may see
a yellow question mark in front of the nitrox device in the device manager. If you
want to keep the existing driver, change the windows registry setting for the new
board accordingly (go to step 3) - otherwise delete the driver first (as explained in
section 1.1).
2. If the machine does not have the nitrox driver, install it (as explained in section
1.2). This will try to setup the default board (CN1010) which is different from the
board being installed. The installation procedure may fail (you may see a yellow
question mark in front of the nitrox device in device manager), but it will setup all
the driver and windows registry entries correctly. In order to make this driver
working correctly with a board other than CN1010, we need to setup the registry
settings correctly.
3. Launch the registry editor (start->run and type regedit)
4. All the nitrox related settings are stored in:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Nitrox\Configuration
Change the following settings according to the board type. (All the settings are
explained in section 2.1.2). Let’s assume we are installing CN501 in this case:
BoardType
CoreMask0
CoreMask1
CoreMask2
MaxCores
-
CN501
0x00000003
0x00000003
0x00000003
2
5. Exit the RegEdit program. Disable and enable the drvice (nitrox) using the device
manager – this should make the driver working properly.
Confidential and Proprietary
Cavium Networks
Page 11 of 17
7/31/2017
Nitrox-Installation and User Guide
4 Sample Test Application
‘NitroxTester.exe’ is the sample application which shows the working of the API
interface. It performs thee operation:
1.
2.
3.
4.
Generate Random numbers
Performs mod exp.
Performs 3DES encryption/decryption in blocking mode.
Performs AES encryption/decryption in non-blocking mode.
Confidential and Proprietary
Cavium Networks
Page 12 of 17
7/31/2017
Nitrox-Installation and User Guide
5 User Guide
The NITROX/NITROX-LITE board device driver provides a robust and efficient
interface to an application and hides all the low level details of direct communication
with the device. The NITROX/NITROX_LITE board device driver initializes the
hardware, creates an instruction processing interface for the host system and responds to
the interrupts generated by the hardware as a result of error conditions.
The API layer sits on top of the device driver and simplifies the driver interface to an
application. The layer provides three types of function calls:
1. Initialization and shutdown – acquires and yields a handle to the driver.
2. Memory management/Resource allocation – performs heap management for onchip SRAM and the local DDR memory (or the host memory if the DDR memory
is not available).
3. Security protocol processing – executes an instruction on the
NITROX/NITROX_LITE chip.
The API layer is implemented in cavium_common.c and cavium_common.h files. (These
files are not part of the driver but are supplied with a sample application). The API gets
all the data from the application using the API calls, and convert them to the structure
defined below before sending them to the device driver:
typedef struct {
Uint16
opcode;
Uint16
size;
Uint16
param;
Uint16
dlen;
/* length in
Uint16
rlen;
/* length in
OperationMode
operation_mode; /*
Uint64
ctx_ptr;
Uint16
incnt;
/* number of
Uint16
outcnt;
/* number of
Uint8
*inptr[MAX_INCNT];
Uint32
insize[MAX_INCNT];
Uint32
inoffset[MAX_INCNT];
Uint32
inunit[MAX_INCNT];
Uint8
*outptr[MAX_OUTCNT];
Uint32
outsize[MAX_OUTCNT];
Uint32
outoffset[MAX_OUTCNT];
Uint32
outunit[MAX_OUTCNT];
Uint32
async_index;
} Csp1OperationBuffer;
bytes of the input data */
bytes of the output data */
blocking / non-blocking */
pointers in inptr array. */
pointers in outptr array. */
The device driver extracts all the information and sends them to the chip. All the
conversion is transparent from the application, which can only see the API interface.
Below is the list of API calls available to an application: (more description, #defines and
implementation details can be found in cavium_common.c and cavium_common.h files)
Confidential and Proprietary
Cavium Networks
Page 13 of 17
7/31/2017
Nitrox-Installation and User Guide
5.1 Initialization and shutdown
5.1.1 Csp1Initialize
Acquires a file handle for the device and initializes the driver.
5.1.2 Csp1ShutDown
Cleanup and closes the driver handle.
5.2 Memory management/Resource allocation
5.2.1 Csp1AllocContext
Allocates a context segment (in the local DDR DRAM or the host memory depending on
the system) and returns its handle.
5.2.2 Csp1FreeContext
Free a context segment allocated previously using Csp1AllocContext
5.2.3 Csp1AllocKeyMem
Acquires a key memory segment and returns its handle
5.2.4 Csp1FreeKeyMem
Fess a key memory segment previously allocated using Csp1AllocKeyMem.
5.2.5 Csp1StoreKey
Store a key to memory segment indicated by key handle.
5.2.6 Csp1ReadContext
Routine to read data from the context.
5.2.7 Csp1WriteContext
Write data to context memory.
Confidential and Proprietary
Cavium Networks
Page 14 of 17
7/31/2017
Nitrox-Installation and User Guide
5.2.8 Csp1CheckForCompletion
Checks the status of the request. There are two types of requests generated by the
application. Blocking and non-blocking. In blocking request, the application sends a
request, and then blocks until it gets the response. In the non-blocking mode, the
application sends a request and gets a request id from the device driver. The application
can use the Csp1CheckForCompletion function later with the request id to query if the
operation has been completed or not.
5.3 Security protocol processing
5.3.1 Csp1Random
Generates random data.
5.3.2 Csp1Hmac
Compute the HMAC of a complete message. Does not use context.
5.3.3 Csp1HmacStart
Compute the first stage in a multi-step HMAC.
5.3.4 Csp1HmacUpdate
Compute an intermediate step in a multi-step HMAC.
5.3.5 Csp1HmacFinish
Compute the final step in a multi-step HMAC.
5.3.6 Csp1Me
Calculates Modular exponentiation.
p = x^e mod m
5.3.7 Csp1Pkcs1v15Enc
Performs PKCS#1v1.5 encryption.
Confidential and Proprietary
Cavium Networks
Page 15 of 17
7/31/2017
Nitrox-Installation and User Guide
5.3.8 Csp1Pkcs1v15CrtEnc
Performs PKCS#1v1.5 encryption using Chinese Remainder Theorem.
5.3.9 Csp1Pkcs1v15Dec
Performs PKCS#1v1.5 decryption.
5.3.10
Csp1Pkcs1v15CrtDec
Performs PKCS#1v1.5 decryption using Chinese Remainder Theorem.
5.3.11
Csp1InitializeRc4
Initializes RC4 cipher mode with the cipher key.
5.3.12
Csp1EncryptRc4
Performs the encryption and decryption using RC4 cipher mode.
5.3.13
Csp1Initialize3DES
Initializes the 3DES cipher mode with the cipher key and the iv.
5.3.14
Csp1Encrypt3DES
Performs 3DES encryption.
5.3.15
Csp1Descrypt3DES
Performs 3DES decrypt.
5.3.16
Csp1InitializeAES
Initializes AES cipher mode with the cipher key and the iv.
5.3.17
Csp1EncryptAES
Performs AES encryption.
5.3.18
Csp1DecryptAES
Performs AES decryption.
Confidential and Proprietary
Cavium Networks
Page 16 of 17
ID
7/31/2017
5.3.19
Nitrox-Installation and User Guide
Csp1Handshake
Calculates both MD5 and SHA1 hashes in one call.
5.3.20
Csp1HandshakeStart
Starts the multi-step hash function.
5.3.21
Csp1HandshakeUpdate
Update the multi-step hash operation.
5.3.22
Csp1HandshakeFinish
Complete the multi-step hash operation and get the MD5 and SHA1 hash values.
Confidential and Proprietary
Cavium Networks
Page 17 of 17