share/man/man4/nsp.4

   1 .\"     $NetBSD: nsp.4,v 1.1 2008/11/02 22:11:36 tls Exp $
   2 .\"
   3 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Coyote Point Systems, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  20 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  21 .\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
  22 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  23 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  24 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  27 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 2, 2008
  31 .Dt NSP 4
  32 .Os
  33 .Sh NAME
  34 .Nm nsp
  35 .Nd NBMK/CyberGuard/NetOctave NSP2000 crypto accelerator
  36 .Sh SYNOPSIS
  37 .Cd "nsp* at pci? dev ? function ?"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver supports cards using the NSP2000 cryptographic processor,
  42 originally manufactured and sold by NetOctave, then CyberGuard, and
  43 presently (late 2008) by NBMK Encryption Technologies.
  44 .Pp
  45 The NSP2000 is a cryptographic
  46 .Dq packet processor
  47 or
  48 .Dq macro processor
  49 featuring extensive support for protocol handshake acceleration
  50 and protocol record operations (e.g. single-pass pad-encrypt-and-hash
  51 for SSL or ESP messages).
  52 It also provides various cryptographic and mathematical primitives
  53 such as random number generation, encryption/decryption (DES, 3DES, and RC4),
  54 hash computation (MD5, SHA1, and HMAC), and an extensive set of operations
  55 for arbitrary precision arithmetic.
  56 It contains a tamper-resistant write-only memory region for storage
  57 of cryptographic keys.
  58 .Pp
  59 The
  60 .Nm
  61 driver registers support for the following operations with
  62 .Xr opencrypto 9 :
  63 .Bl -tag -width "CRK_DH_COMPUTE_KEY" -offset indent
  64 .It Dv CRYPTO_DES_CBC
  65 DES in CBC mode.
  66 .It Dv CRYPTO_3DES_CBC
  67 Triple-DES in CBC mode.
  68 .It Dv CRYPTO_MD5
  69 The MD5 hash algorithm.
  70 .It Dv CRYPTO_SHA1
  71 The SHA-1 hash algorithm.
  72 .It Dv CRYPTO_SHA1_HMAC
  73 The HMAC message authentication code using SHA-1 as the hash function.
  74 .It Dv CRYPTO_MD5_HMAC
  75 The HMAC message authentication code using MD5 as the hash function.
  76 .It Dv CRK_MOD
  77 Compute x modulo y.
  78 .It Dv CRK_MOD_ADD
  79 Modular addition.
  80 .It Dv CRK_MOD_ADDINV
  81 Modular additive inversion.
  82 .It Dv CRK_MOD_SUB
  83 Modular subtraction.
  84 .It Dv CRK_MOD_MULT
  85 Modular multiplication.
  86 .It Dv CRK_MOD_MULTINV
  87 Modular multiplicative inversion.
  88 .It Dv CRK_MOD_EXP
  89 Modular exponentiation.
  90 .It Dv CRK_DSA_SIGN
  91 DSA signature creation.
  92 .It Dv CRK_DSA_VERIFY
  93 DSA signature verification.
  94 .It Dv CRK_DH_COMPUTE_KEY
  95 Diffie-Hellman key computation.
  96 .El
  97 .Sh PERFORMANCE
  98 The
  99 .Nm
 100 driver can perform several hundred 1024-bit RSA operations per second,
 101 and can encrypt and hash about 200Mbit/sec of data with symmetric
 102 operations.
 103 Each figure is approximately 1/3 the rated throughput for
 104 the device.
 105 .Pp
 106 Several restrictions limit the performance of this driver:
 107 .Bl -enum -compact
 108 .It
 109 The
 110 .Dv CRK_MOD_EXP_CRT
 111 operation (modular exponentiation with operands in Chinese Remainder
 112 Theorem form) is unfortunately not supported because the
 113 .Xr opencrypto 9
 114 interface specifies this operation in a way which may only be
 115 compatible with the
 116 .Xr ubsec 4
 117 accelerator.
 118 .It
 119 The handshake operations and record transforms are not supported as they
 120 are a poor fit for the current
 121 .Xr opencrypto 9
 122 API.
 123 Support for either would require a method of passing record-transform
 124 contexts between layers of the framework, likely in both directions across
 125 the user-kernel boundary.
 126 Without record operations, the host CPU will almost always
 127 perform RC4 faster than the NSP2000, so RC4 support is disabled in the
 128 .Nm
 129 driver.
 130 .It
 131 The on-board key memory is not supported.
 132 It would be relatively easy to add support for this feature to
 133 .Xr opencrypto 9 ,
 134 but the interface for supporting this functionality in OpenSSL in
 135 OpenSSL is complex and poorly documented, which makes kernel support
 136 useless.
 137 .It
 138 The OpenSSL
 139 .Dq engine
 140 for
 141 .Xr crypto 4
 142 does not yet support the HMAC forms of the hash operations, which roughly
 143 halves performance for many workloads.
 144 .El
 145 .Pp
 146 On a more positive note, the NSP2000 and
 147 .Nm
 148 driver offer excellent performance for small modular arithmetic operations,
 149 achieving 75,000 or more such operations per second.
 150 .Sh SEE ALSO
 151 .Xr crypto 4 ,
 152 .Xr fast_ipsec 4 ,
 153 .Xr intro 4 ,
 154 .Xr rnd 4 ,
 155 .Xr opencrypto 9
 156 .Sh HISTORY
 157 The
 158 .Nm
 159 device driver is descended from the NetOctave SDK for
 160 .Fx 4.11 ,
 161 where it was called
 162 .Dq noct .
 163 It is unrelated to the driver of that
 164 name which appeared in
 165 .Ox 3.2 ,
 166 which does not support the public-key (or other bignum) functions of the
 167 device.
 168 The
 169 .Nm
 170 driver was ported to
 171 .Nx 5.0
 172 by Coyote Point Systems, Inc and generously made available under
 173 a BSD-style license by NBMK Encryption Technologies, Inc, the
 174 corporate successor of NetOctave.
 175 .Pp
 176 The
 177 .Nm
 178 device driver does not currently support the device node interface
 179 provided by the original NetOctave
 180 .Dq noct
 181 driver (which offers handshake acceleration, record operations,
 182 memory-mapped handling of packet payloads, and several other useful
 183 features) but most of the code to do so is still present, albeit
 184 in untested form.
 185 .Sh BUGS
 186 Support for limitations of the NSP2000 PCI interface (broken burst-mode
 187 operation, lack of scatter-gather support) is present but tested only on
 188 a fairly small range of host systems.
 189 .Pp
 190 It appears that most if not all NSP2000 cards ever manufactured were
 191 designed to carry either one or two accelerator chips, which suggests
 192 that cards exist with both chips populated.
 193 The
 194 .Nm
 195 driver has never been tested with more than one instance present at a time.