share/man/man4/safe.4

   1 .\"-
   2 .\" Copyright (c) 2003  Sam Leffler, Errno Consulting
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/share/man/man4/safe.4,v 1.7 2006/04/01 10:56:36 brueffer Exp $
  27 .\"
  28 .Dd April 21, 2018
  29 .Dt SAFE 4
  30 .Os
  31 .Sh NAME
  32 .Nm safe
  33 .Nd SafeNet crypto accelerator
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel,
  36 place the following lines in your
  37 kernel configuration file:
  38 .Bd -ragged -offset indent
  39 .Cd "device crypto"
  40 .Cd "device cryptodev"
  41 .Cd "device safe"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 safe_load="YES"
  49 .Ed
  50 .Pp
  51 .Nm sysctl Va hw.safe.debug
  52 .Nm sysctl Va hw.safe.dump
  53 .Nm sysctl Va hw.safe.rnginterval
  54 .Nm sysctl Va hw.safe.rngbufsize
  55 .Nm sysctl Va hw.safe.rngmaxalarm
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 driver supports cards containing SafeNet crypto accelerator chips.
  60 .Pp
  61 The
  62 .Nm
  63 driver registers itself to accelerate DES, Triple-DES, AES, MD5-HMAC,
  64 SHA1-HMAC, and NULL operations for
  65 .Xr crypto 4 .
  66 .Pp
  67 On all models, the driver registers itself to provide random data to the
  68 .Xr random 4
  69 subsystem.
  70 Periodically the driver will poll the hardware RNG and retrieve
  71 data for use by the system.
  72 If the driver detects that the hardware RNG is resonating with any local
  73 signal, it will reset the oscillators that generate random data.
  74 Three
  75 .Xr sysctl 8
  76 settings control this procedure:
  77 .Va hw.safe.rnginterval
  78 specifies the time, in seconds, between polling operations,
  79 .Va hw.safe.rngbufsize
  80 specifies the number of 32-bit words to retrieve on each poll,
  81 and
  82 .Va hw.safe.rngmaxalarm
  83 specifies the threshold for resetting the oscillators.
  84 .Pp
  85 When the driver is compiled with
  86 .Dv SAFE_DEBUG
  87 defined, two
  88 .Xr sysctl 8
  89 variables are provided for debugging purposes:
  90 .Va hw.safe.debug
  91 can be set to a non-zero value to enable debugging messages to be sent
  92 to the console for each cryptographic operation,
  93 .Va hw.safe.dump
  94 is a write-only variable that can be used to force driver state to be sent
  95 to the console.
  96 Set this variable to
  97 .Dq Li ring
  98 to dump the current state of the descriptor ring,
  99 to
 100 .Dq Li dma
 101 to dump the hardware DMA registers,
 102 or
 103 to
 104 .Dq Li int
 105 to dump the hardware interrupt registers.
 106 .Sh HARDWARE
 107 The
 108 .Nm
 109 driver supports cards containing any of the following chips:
 110 .Bl -tag -width "SafeNet 1141" -offset indent
 111 .It SafeNet 1141
 112 The original chipset.
 113 Supports DES, Triple-DES, AES, MD5, and SHA-1
 114 symmetric crypto operations, RNG, public key operations, and full IPsec
 115 packet processing.
 116 .It SafeNet 1741
 117 A faster version of the 1141.
 118 .El
 119 .Sh SEE ALSO
 120 .Xr crypt 3 ,
 121 .Xr crypto 4 ,
 122 .Xr intro 4 ,
 123 .Xr random 4 ,
 124 .Xr crypto 9
 125 .Sh BUGS
 126 Public key support is not implemented.