Add manual page for nsp(4), the driver for NSP2000 cryptographic
accellerators.  Adjust mdoc.local so it knows about .Fx 4.11, present in
nsp manual page.


(tls)

.\"	$NetBSD: nsp.4,v 1.1 2008/11/02 22:11:36 tls Exp $
.\"
.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Coyote Point Systems, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 2, 2008
.Dt NSP 4
.Os
.Sh NAME
.Nm nsp
.Nd NBMK/CyberGuard/NetOctave NSP2000 crypto accellerator
.Sh SYNOPSIS
.Cd "nsp* at pci? dev ? function ?"
.Sh DESCRIPTION
The
.Nm
driver supports cards using the NSP2000 cryptographic processor,
originally manufactured and sold by NetOctave, then CyberGuard, and
presently (late 2008) by NBMK Encryption Technologies.
.Pp
The NSP2000 is
a cryptographic "packet processor" or "macro processor" featuring extensive
support for protocol handshake acceleration and protocol record operations
(e.g. single-pass pad-encrypt-and-hash for SSL or ESP messages).  It
also provides various cryptographic and mathematical primitives
such as random number generation, encryption/decryption (DES, 3DES, and RC4),
hash computation (MD5, SHA1, and HMAC), and an extensive set of operations
for arbitrary precision arithmetic.  It contains a tamper-resistant write-
only memory region for storage of cryptographic keys.
.Pp
The
.Nm
driver registers support for the following operations with
.Xr opencrypto 9 :
.Bl -tag -width "CRK_DH_COMPUTE_KEY" -offset indent
.It CRYPTO_DES_CBC
DES in CBC mode.
.It CRYPTO_3DES_CBC
Triple-DES in CBC mode.
.It CRYPTO_MD5
The MD5 hash algorithm.
.It CRYPTO_SHA1
The SHA-1 hash algorithm.
.It CRYPTO_SHA1_HMAC
The HMAC message authentication code using SHA-1 as the hash function.
.It CRYPTO_MD5_HMAC
The HMAC message authentication code using MD5 as the hash function.
.It CRK_MOD
Compute x modulo y.
.It CRK_MOD_ADD
Modular addition.
.It CRK_MOD_ADDINV
Modular additive inversion.
.It CRK_MOD_SUB
Modular subtraction.
.It CRK_MOD_MULT
Moduar multiplication.
.It CRK_MOD_MULTINV
Modular multiplicative inversion.
.It CRK_MOD_EXP
Modular exponentiation.
.It CRK_DSA_SIGN
DSA signature creation.
.It CRK_DSA_VERIFY
DSA signature verification.
.It CRK_DH_COMPUTE_KEY
Diffie-Hellman key computation.
.El
.Sh PERFORMANCE
.Pp
The
.Nm
driver can perform several hundred 1024-bit RSA operations per second,
and can encrypt and hash about 200Mbit/sec of data with symmetric
operations.  Each figure is approximately 1/3 the rated throughput for
the device.
.Pp
Several restrictions limit the performance of this driver:
.Bl -enum -compact
.It
The CRK_MOD_EXP_CRT operation (modular exponentiation with operands in
Chinese Remainder Theorem form) is unfortunately not supported because
the
.Xr opencrypto 9 :
interface specifies this operation in a way which may only be compatible
with the
.Xr ubsec 4
accellerator.
.It
The handshake operations and record transforms are not supported as they
are a poor fit for the current
.Xr opencrypto 9
API.  Support for either would require a method of passing record-transform
contexts between layers of the framework, likely in both directions across
the user-kernel boundary.
Without record operations, the host CPU will almost always
perform RC4 faster than the NSP2000, so RC4 support is disabled in the
.Nm
driver.
.It
The onboard key memory is not supported.  It would be relatively easy to
add support for this feature to
.Xr opencrypto 9 ,
but the interface for supporting this functionality in OpenSSL
in OpenSSL is complex and poorly documented, which makes kernel support
unuseful.
.It
The OpenSSL "engine" for
.Xr crypto 4
does not yet support the HMAC forms of the hash operations, which roughly
halves performance for many workloads.
.El
.Pp
On a more positive note, the NSP2000 and
.Nm
driver offer excellent performance for small modular arithmetic operations,
achieving 75,000 or more such operations per second.
.Sh SEE ALSO
.Xr crypto 4 ,
.Xr fast_ipsec 4 ,
.Xr intro 4 ,
.Xr rnd 4 ,
.Xr opencrypto 9
.Sh HISTORY
The
.Nm
device driver is descended from the NetOctave SDK for
.Fx 4.11 ,
where it was called "noct".  It is unrelated to the driver of that
name which appeared in
.Ox 3.2 ,
which does not support the public-key (or other bignum) functions of the
device.  The
.Nm
driver was ported to
.Nx 5.0
by Coyote Point Systems, Inc and generously made available under a BSD-style
license by NBMK Encryption Technologies, Inc, the corporate successor of
NetOctave.
.Pp
The
.Nm
device driver does not currently support the device node interface provided
by the original NetOctave "noct" driver (which offers handshake accelleration,
record operations, memory-mapped handling of packet payloads, and several
other useful features) but most of the code to do so is still present, albeit
in untested form.
.Sh BUGS
Support for limitations of the NSP2000 PCI interface (broken burst-mode
operation, lack of scatter-gather support) is present but tested only on
a fairly small range of host systems.
.Pp
It appears that most if not all NSP2000 cards ever manufactured were
designed to carry either one or two accellerator chips, which suggests
that cards exist with both chips populated.  The
.Nm
driver has never been tested with more than one instance present at a time.