diff options
| -rw-r--r-- | share/man/man4/Makefile | 3 | ||||
| -rw-r--r-- | share/man/man4/crypto.4 | 113 | ||||
| -rw-r--r-- | share/man/man4/hifn.4 | 111 | ||||
| -rw-r--r-- | share/man/man4/ubsec.4 | 99 | ||||
| -rw-r--r-- | share/man/man9/Makefile | 2 | ||||
| -rw-r--r-- | share/man/man9/crypto.9 | 591 |
6 files changed, 918 insertions, 1 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 49a57ae..a6afc65 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -28,6 +28,7 @@ MAN= aac.4 \ ccd.4 \ cd.4 \ ch.4 \ + crypto.4 \ csa.4 \ cue.4 \ da.4 \ @@ -51,6 +52,7 @@ MAN= aac.4 \ gre.4 \ gusc.4 \ gx.4 \ + hifn.4 \ ichsmb.4 \ icmp.4 \ icmp6.4 \ @@ -185,6 +187,7 @@ MAN= aac.4 \ tun.4 \ twe.4 \ txp.4 \ + ubsec.4 \ ucom.4 \ udbp.4 \ udp.4 \ diff --git a/share/man/man4/crypto.4 b/share/man/man4/crypto.4 new file mode 100644 index 0000000..5471134 --- /dev/null +++ b/share/man/man4/crypto.4 @@ -0,0 +1,113 @@ +.\" $OpenBSD: crypto.4,v 1.4 2002/09/12 07:15:03 deraadt Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 2001 Theo de Raadt +.\" All rights reserved. +.\" +.\" 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. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" 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 October 3, 2002 +.Dt CRYPTO 4 +.Os +.Sh NAME +.Nm crypto +.Nd hardware crypto access driver +.Sh SYNOPSIS +.Nm device crypto +.Sh DESCRIPTION +The +.Nm +driver provides userland applications access to hardware crypto support +via the kernel. +The +.Pa /dev/crypto +device node primarily operates in an +.Xr ioctl 2 +based model, permitting a variety of applications to query device capabilities, +submit transactions, and get results. +.Pp +If +.Ar count +given in the specification, and is greater than 0, a maximum of one +.Nm crypto +device is created. +.Pp +The following +.Xr ioctl 2 +calls apply only to the +.Nm crypto +devices: +.Bl -tag -width CIOCGSESSION +.It Dv CIOCGSESSION +Setup a new crypto session for a new type of operation. +.It Dv CIOCFSESSION +Free a previously established session. +.It Dv CIOCCRYPT +Perform a crypto operation against a previously setup session. +.El +.Pp +.Sh FEATURES +Depending on hardware being present, the following symmetric and +assymetric cryptographic features are potentially available from +.Pa /dev/crypto : +.Pp +.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent +.It CRYPTO_DES_CBC +.It CRYPTO_3DES_CBC +.It CRYPTO_BLF_CBC +.It CRYPTO_CAST_CBC +.It CRYPTO_SKIPJACK_CBC +.It CRYPTO_MD5_HMAC +.It CRYPTO_SHA1_HMAC +.It CRYPTO_RIPEMD160_HMAC +.It CRYPTO_MD5_KPDK +.It CRYPTO_SHA1_KPDK +.It CRYPTO_AES_CBC +.It CRYPTO_ARC4 +.It CRYPTO_MD5 +.It CRYPTO_SHA1 +.It CRK_MOD_EXP +.It CRK_MOD_EXP_CRT +.It CRK_DSA_SIGN +.It CRK_DSA_VERIFY +.It CRK_DH_COMPUTE_KEY +.El +.Pp +.Sh FILES +.Bl -tag -width /dev/crypto -compact +.It Pa /dev/crypto +crypto access device +.El +.Sh SEE ALSO +.Xr hifn 4 , +.Xr ubsec 4 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +OpenBSD 3.0. +The +.Nm +driver was imported to FreeBSD in 5.0. diff --git a/share/man/man4/hifn.4 b/share/man/man4/hifn.4 new file mode 100644 index 0000000..539d2e8 --- /dev/null +++ b/share/man/man4/hifn.4 @@ -0,0 +1,111 @@ +.\" $OpenBSD: hifn.4,v 1.32 2002/09/26 07:55:40 miod Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 2000 Theo de Raadt +.\" All rights reserved. +.\" +.\" 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. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" 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 October 3, 2002 +.Dt HIFN 4 +.Os +.Sh NAME +.Nm hifn +.Nd Hifn 7751/7951/7811 crypto accelerator +.Sh SYNOPSIS +.Nm device hifn +.Sh DESCRIPTION +The +.Nm +driver supports various cards containing the Hifn 7751, Hifn 7951, or +Hifn 7811 +chipsets, such as +.Bl -tag -width namenamenamena -offset indent +.It Invertex AEON +No longer being made. +Came as 128KB SRAM model, or 2MB DRAM model. +.It Hifn 7751 +Reference board with 512KB SRAM. +.It PowerCrypt +See +.Pa http://www.powercrypt.com/ . +Comes with 512KB SRAM. +.It XL-Crypt +See +.Pa http://www.powercrypt.com/ . +Only board based on 7811 (which is faster than 7751 and has +a random number generator). +.It NetSec 7751 +See +.Pa http://www.netsec.net/ . +Supports the most IPsec sessions, with 1MB SRAM. +.It Soekris Engineering vpn1201 and vpn1211 +See +.Pa http://www.soekris.com/ . +Contains a 7951 and supports symmetric and random number operations. +.El +.Pp +The +.Nm +driver registers itself to accelerate DES, Triple-DES, ARC4, MD5, +MD5-HMAC, SHA1, and SHA1-HMAC operations for +.Xr ipsec 4 +and +.Xr crypto 4 . +.Pp +The +.Tn Hifn 7951 +and +.Tn Hifn 7811 +will also supply data to the kernel +.Xr random 4 +subsystem. +.Sh BUGS +The 7751 chip starts out at initialization by only supporting compression. +A proprietary algorithm, which has been reverse engineered, is required to +unlock the cryptographic functionality of the chip. +It is possible for vendors to make boards which have a lock ID not known +to the driver, but all vendors currently just use the obvious ID which is +13 bytes of 0. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 9 +.Sh CAVEATS +The Hifn 9751 shares the same PCI id. +This chip is basically a 7751, but with the cryptographic functions missing. +Instead, the 9751 is only capable of doing compression. +Since we do not currently attempt to use any of these chips to do +compression, the 9751-based cards are not useful. +.Sh HISTORY +The +.Nm +device driver appeared in +OpenBSD 2.7. +The +.Nm +device driver was imported to FreeBSD in 5.0. diff --git a/share/man/man4/ubsec.4 b/share/man/man4/ubsec.4 new file mode 100644 index 0000000..2ec4258 --- /dev/null +++ b/share/man/man4/ubsec.4 @@ -0,0 +1,99 @@ +.\" $OpenBSD: ubsec.4,v 1.18 2002/09/26 07:55:41 miod Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 2000 Jason L. Wright (jason@thought.net) +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Jason L. Wright +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" 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 October 3, 2002 +.Dt UBSEC 4 +.Os +.Sh NAME +.Nm ubsec +.Nd Broadcom and BlueSteel uBsec 5x0x crypto accelerator +.Sh SYNOPSIS +.Nm device ubsec +.Sh DESCRIPTION +The +.Nm +driver supports cards containing any of the following chips: +.Bl -tag -width "Broadcom BCM5821" -offset indent +.It Bluesteel 5501 +The original chipset, no longer made. This extremely rare unit +was not very fast, lacked a RNG, and had a number of other bugs. +.It Bluesteel 5601 +A faster and fixed version of the original, with a random number +unit and large number engine added. +.It Broadcom BCM5801 +A BCM5805 without public key engine or random number generator. +.It Broadcom BCM5802 +A slower version of the BCM5805. +.It Broadcom BCM5805 +Faster version of Bluesteel 5601. +.It Broadcom BCM5820 +64 bit version of the chip, and significantly more advanced. +.It Broadcom BCM5821 +Faster version of the BCM5820. +.It Broadcom BCM5822 +Faster version of the BCM5820. +.El +.Pp +The +.Nm +driver registers itself to accelerate DES, Triple-DES, MD5-HMAC, +and SHA1-HMAC operations for +.Xr ipsec 4 +and +.Xr crypto 4 . +.Pp +On those models which contain a public key engine (almost all of the +more recent ones), this feature is registered with the +.Xr crypto 4 +subsystem. +.Pp +On all models except the Bluesteel 5501 and Broadcom 5801, the driver +registers itself to provide random data to the +.Xr random 4 +subsystem. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +device driver appeared in +OpenBSD 2.8. +The +.Nm +device driver was imported to FreeBSD in 5.0. +.Sh BUGS +The BCM5801 and BCM5802 have not actually been tested. diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index c24e53c..229e036 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -27,7 +27,7 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \ bus_generic_shutdown.9 bus_release_resource.9 \ byteorder.9 \ cd.9 cdevsw_add.9 cdevsw_remove.9 condvar.9 copy.9 \ - critical_enter.9 \ + critical_enter.9 crypto.9 \ devclass.9 devclass_add_driver.9 devclass_find.9 \ devclass_get_device.9 devclass_get_devices.9 \ devclass_get_maxunit.9 devclass_get_name.9 devclass_get_softc.9 \ diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9 new file mode 100644 index 0000000..93d3ddf --- /dev/null +++ b/share/man/man9/crypto.9 @@ -0,0 +1,591 @@ +.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ +.\" $FreeBSD$ +.\" +.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" Copyright (c) 2000, 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all source code copies of any software which is or includes a copy or +.\" modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd October 3, 2002 +.Dt CRYPTO 9 +.Os +.Sh NAME +.Nm crypto +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.Fd #include <crypto/cryptodev.h> +.Ft int32_t +.Fn crypto_get_driverid "u_int8_t" +.Ft int +.Fn crypto_register "u_int32_t" "int" "u_int16_t" "u_int32_t" "int (*)(u_int32_t *, struct cryptoini *)" "int (*)(u_int64_t)" "int (*)(struct cryptop *)" +.Ft int +.Fn crypto_kregister "u_int32_t" "int" "u_int32_t" "int (*)(struct cryptkop *)" +.Ft int +.Fn crypto_unregister "u_int32_t" "int" +.Ft void +.Fn crypto_done "struct cryptop *" +.Ft void +.Fn crypto_kdone "struct cryptkop *" +.Ft int +.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" "int" +.Ft int +.Fn crypto_freesession "u_int64_t" +.Ft int +.Fn crypto_dispatch "struct cryptop *" +.Ft int +.Fn crypto_kdispatch "struct cryptkop *" +.Ft struct cryptop * +.Fn crypto_getreq "int" +.Ft void +.Fn crypto_freereq "void" +.Bd -literal + +#define EALG_MAX_BLOCK_LEN 16 + +struct cryptoini { + int cri_alg; + int cri_klen; + int cri_rnd; + caddr_t cri_key; + u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; + struct cryptoini *cri_next; +}; + +struct cryptodesc { + int crd_skip; + int crd_len; + int crd_inject; + int crd_flags; + struct cryptoini CRD_INI; + struct cryptodesc *crd_next; +}; + +struct cryptop { + u_int64_t crp_sid; + int crp_ilen; + int crp_olen; + int crp_alloctype; + int crp_etype; + int crp_flags; + caddr_t crp_buf; + caddr_t crp_opaque; + struct cryptodesc *crp_desc; + int (*crp_callback) (struct cryptop *); + struct cryptop *crp_next; + caddr_t crp_mac; +}; + +struct crparam { + caddr_t crp_p; + u_int crp_nbits; +}; + +#define CRK_MAXPARAM 8 + +struct cryptkop { + u_int krp_op; /* ie. CRK_MOD_EXP or other */ + u_int krp_status; /* return status */ + u_short krp_iparams; /* # of input parameters */ + u_short krp_oparams; /* # of output parameters */ + u_int krp_pad1; + struct crparam krp_param[CRK_MAXPARAM]; + struct crparam krp_kvp[CRK_MAXPARAM]; + + u_int32_t krp_hid; + int (*krp_callback)(struct cryptkop *); + struct cryptkop *krp_next; +}; +.Ed +.br +.Sh DESCRIPTION +.Nm +is a framework for drivers of cryptographic hardware to register with +the kernel so +.Dq consumers +(other kernel subsystems, and eventually +users through an appropriate device) are able to make use of it. +Drivers register with the framework the algorithms they support, +and provide entry points (functions) the framework may call to +establish, use, and tear down sessions. +Sessions are used to cache cryptographic information in a particular driver +(or associated hardware), so initialization is not needed with every request. +Consumers of cryptographic services pass a set of +descriptors that instruct the framework (and the drivers registered +with it) of the operations that should be applied on the data (more +than one cryptographic operation can be requested). +.Pp +Keying operations are supported as well. +Unlike the symmetric operators described above, +these sessionless commands perform mathematical operations using +input and output parameters. +.Pp +Since the consumers may not be associated with a process, drivers may +not use +.Xr tsleep 9 . +The same holds for the framework. +Thus, a callback mechanism is used +to notify a consumer that a request has been completed (the +callback is specified by the consumer on an per-request basis). +The callback is invoked by the framework whether the request was +successfully completed or not. +An error indication is provided in the latter case. +A specific error code, +.Er EAGAIN , +is used to indicate that a session number has changed and that the +request may be re-submitted immediately with the new session number. +Errors are only returned to the invoking function if not +enough information to call the callback is available (meaning, there +was a fatal error in verifying the arguments). +For session initialization and teardown there is no callback mechanism used. +.br +.Pp +The +.Fn crypto_newsession +routine is called by consumers of cryptographic services (such as the +.Xr ipsec 4 +stack) that wish to establish a new session with the framework. +On success, the first argument will contain the Session Identifier (SID). +The second argument contains all the necessary information for +the driver to establish the session. +The third argument indicates whether a +hardware driver (1) should be used or not (0). +The various fields in the +.Fa cryptoini +structure are: +.Bl -tag -width foobarmoocow +.It Fa cri_alg +Contains an algorithm identifier. +Currently supported algorithms are: +.Bd -literal +CRYPTO_DES_CBC +CRYPTO_3DES_CBC +CRYPTO_BLF_CBC +CRYPTO_CAST_CBC +CRYPTO_SKIPJACK_CBC +CRYPTO_MD5_HMAC +CRYPTO_SHA1_HMAC +CRYPTO_RIPEMD160_HMAC +CRYPTO_MD5_KPDK +CRYPTO_SHA1_KPDK +CRYPTO_AES_CBC +CRYPTO_ARC4 +CRYPTO_MD5 +CRYPTO_SHA1 +.Ed +.Pp +.It Fa cri_klen +Specifies the length of the key in bits, for variable-size key +algorithms. +.It Fa cri_rnd +Specifies the number of rounds to be used with the algorithm, for +variable-round algorithms. +.It Fa cri_key +Contains the key to be used with the algorithm. +.It Fa cri_iv +Contains an explicit initialization vector (IV), if it does not prefix +the data. +This field is ignored during initialization. +If no IV is explicitly passed (see below on details), a random IV is used +by the device driver processing the request. +.It Fa cri_next +Contains a pointer to another +.Fa cryptoini +structure. +Multiple such structures may be linked to establish multi-algorithm sessions +.Pf ( Xr ipsec 4 +is an example consumer of such a feature). +.El +.Pp +The +.Fa cryptoini +structure and its contents will not be modified by the framework (or +the drivers used). +Subsequent requests for processing that use the +SID returned will avoid the cost of re-initializing the hardware (in +essence, SID acts as an index in the session cache of the driver). +.Pp +.Fn crypto_freesession +is called with the SID returned by +.Fn crypto_newsession +to disestablish the session. +.Pp +.Fn crypto_dispatch +is called to process a request. +The various fields in the +.Fa cryptop +structure are: +.Bl -tag -width crp_alloctype +.It Fa crp_sid +Contains the SID. +.It Fa crp_ilen +Indicates the total length in bytes of the buffer to be processed. +.It Fa crp_olen +On return, contains the total length of the result. +For symmetric crypto operations, this will be the same as the input length. +.It Fa crp_alloctype +Indicates the type of buffer, as used in the kernel +.Xr malloc 9 +routine. +This will be used if the framework needs to allocate a new +buffer for the result (or for re-formatting the input). +.It Fa crp_callback +This routine is invoked upon completion of the request, whether +successful or not. +It is invoked through the +.Fn crypto_done +routine. +If the request was not successful, an error code is set in the +.Fa crp_etype +field. +It is the responsibility of the callback routine to set the appropriate +.Xr spl 9 +level. +.It Fa crp_etype +Contains the error type, if any errors were encountered, or zero if +the request was successfully processed. +If the +.Er EAGAIN +error code is returned, the SID has changed (and has been recorded in the +.Fa crp_sid +field). +The consumer should record the new SID and use it in all subsequent requests. +In this case, the request may be re-submitted immediately. +This mechanism is used by the framework to perform +session migration (move a session from one driver to another, because +of availability, performance, or other considerations). +.Pp +Note that this field only makes sense when examined by +the callback routine specified in +.Fa crp_callback . +Errors are returned to the invoker of +.Fn crypto_process +only when enough information is not present to call the callback +routine (i.e., if the pointer passed is +.Dv NULL +or if no callback routine was specified). +.It Fa crp_flags +Is a bitmask of flags associated with this request. +Currently defined flags are: +.Bl -tag -width CRYPTO_F_IMBUF +.It Dv CRYPTO_F_IMBUF +The buffer pointed to by +.Fa crp_buf +is an mbuf chain. +.El +.Pp +.It Fa crp_buf +Points to the input buffer. +On return (when the callback is invoked), +it contains the result of the request. +The input buffer may be an mbuf +chain or a contiguous buffer (of a type identified by +.Fa crp_alloctype ) , +depending on +.Fa crp_flags . +.It Fa crp_opaque +This is passed through the crypto framework untouched and is +intended for the invoking application's use. +.It Fa crp_desc +This is a linked list of descriptors. +Each descriptor provides +information about what type of cryptographic operation should be done +on the input buffer. +The various fields are: +.Bl -tag -width=crd_inject +.It Fa crd_skip +The offset in the input buffer where processing should start. +.It Fa crd_len +How many bytes, after +.Fa Fa crd_skip , +should be processed. +.It Fa crd_inject +Offset from the beginning of the buffer to insert any results. +For encryption algorithms, this is where the initialization vector +(IV) will be inserted when encrypting or where it can be found when +decrypting (subject to +.Fa Fa crd_flags ) . +For MAC algorithms, this is where the result of the keyed hash will be +inserted. +.It Fa crd_flags +The following flags are defined: +.Bl -tag -width CRD_F_IV_EXPLICIT +.It Dv CRD_F_ENCRYPT +For encryption algorithms, this bit is set when encryption is required +(when not set, decryption is performed). +.It Dv CRD_F_IV_PRESENT +For encryption algorithms, this bit is set when the IV already +precedes the data, so the +.Fa crd_inject +value will be ignored and no IV will be written in the buffer. +Otherwise, the IV used to encrypt the packet will be written +at the location pointed to by +.Fa crd_inject . +The IV length is assumed to be equal to the blocksize of the +encryption algorithm. +Some applications that do special +.Dq IV cooking , +such as the half-IV mode in +.Xr ipsec 4 , +can use this flag to indicate that the IV should not be written on the packet. +This flag is typically used in conjunction with the +.Dv CRD_F_IV_EXPLICIT +flag. +.It Dv CRD_F_IV_EXPLICIT +For encryption algorithms, this bit is set when the IV is explicitly +provided by the consumer in the +.Fa crd_iv +fields. +Otherwise, for encryption operations the IV is provided for by +the driver used to perform the operation, whereas for decryption +operations it is pointed to by the +.Fa crd_inject +field. +This flag is typically used when the IV is calculated +.Dq on the fly +by the consumer, and does not precede the data (some +.Xr ipsec 4 +configurations, and the encrypted swap are two such examples). +.It Dv CRD_F_COMP +For compression algorithms, this bit is set when compression is required (when +not set, decompression is performed). +.El +.It Fa CRD_INI +This +.Fa cryptoini +structure will not be modified by the framework or the device drivers. +Since this information accompanies every cryptographic +operation request, drivers may re-initialize state on-demand +(typically an expensive operation). +Furthermore, the cryptographic +framework may re-route requests as a result of full queues or hardware +failure, as described above. +.It Fa crd_next +Point to the next descriptor. +Linked operations are useful in protocols such as +.Xr ipsec 4 , +where multiple cryptographic transforms may be applied on the same +block of data. +.El +.El +.Pp +.Fn crypto_getreq +allocates a +.Fa cryptop +structure with a linked list of as many +.Fa cryptodesc +structures as were specified in the argument passed to it. +.Pp +.Fn crypto_freereq +deallocates a structure +.Fa cryptop +and any +.Fa cryptodesc +structures linked to it. +Note that it is the responsibility of the +callback routine to do the necessary cleanups associated with the +opaque field in the +.Fa cryptop +structure. +.Pp +.Fn crypto_kdispatch +is called to perform a keying operation. +The various fields in the +.Fa crytokop +structure are: +.Bl -tag -width crp_alloctype +.It Fa krp_op +Operation code, such as CRK_MOD_EXP. +.It Fa krp_status +Return code. +This errno-style variable indicates whether lower level reasons +for operation failure. +.It Fa krp_iparams +Number if input parameters to the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Fa krp_oparams +Number if output parameters from the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Fa krp_kvp +An array of kernel memory blocks containing the parameters. +.It Fa krp_hid +Identifier specifying which low-level driver is being used. +.It Fa krp_callback +Callback called on completion of a keying operation. +.El +.Sh DRIVER-SIDE API +The +.Fn crypto_get_driverid , +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +and +.Fn crypto_done +routines are used by drivers that provide support for cryptographic +primitives to register and unregister with the kernel crypto services +framework. +Drivers must first use the +.Fn crypto_get_driverid +function to acquire a driver identifier, specifying the +.Fa cc_flags +as an argument (normally 0, but software-only drivers should specify +.Dv CRYPTOCAP_F_SOFTWARE Ns ). +For each algorithm the driver supports, it must then call +.Fn crypto_register . +The first two arguments are the driver and algorithm identifiers. +The next two arguments specify the largest possible operator length (in bits, +important for public key operations) and flags (e.g., whether an hardware RNG is +available) for this algorithm. +The last three arguments must be provided in the first call to +.Fn crypto_register +and are ignored in all subsequent calls. +They are pointers to three +driver-provided functions that the framework may call to establish new +cryptographic context with the driver, free already established +context, and ask for a request to be processed (encrypt, decrypt, +etc.) +.Fn crypto_unregister +is called by drivers that wish to withdraw support for an algorithm. +The two arguments are the driver and algorithm identifiers, respectively. +Typically, drivers for +.Xr pcmcia 4 +crypto cards that are being ejected will invoke this routine for all +algorithms supported by the card. +If called with +.Dv CRYPTO_ALGORITHM_ALL , +all algorithms registered for a driver will be unregistered in one go +and the driver will be disabled (no new sessions will be allocated on +that driver, and any existing sessions will be migrated to other +drivers). +The same will be done if all algorithms associated with a driver are +unregistered one by one. +.Pp +The calling convention for the three driver-supplied routines is: +.Bd -literal +int (*newsession) (u_int32_t *, struct cryptoini *); +int (*freesession) (u_int64_t); +int (*process) (struct cryptop *); +int (*kprocess) (struct cryptkop *); +.Ed +.Pp +On invocation, the first argument to +.Fn newsession +contains the driver identifier obtained via +.Fn crypto_get_driverid . +On successfully returning, it should contain a driver-specific session +identifier. +The second argument is identical to that of +.Fn crypto_newsession . +.Pp +The +.Fn freesession +routine takes as argument the SID (which is the concatenation of the +driver identifier and the driver-specific session identifier). +It should clear any context associated with the session (clear hardware +registers, memory, etc.). +.Pp +The +.Fn process +routine is invoked with a request to perform crypto processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of error, the error indication must be placed in the +.Fa crp_etype +field of the +.Fa cryptop +structure. +When the request is completed, or an error is detected, the +.Fn process +routine should invoked +.Fn crypto_done . +Session migration may be performed, as mentioned previously. +.Pp +The +.Fn kprocess +routine is invoked with a request to perform crypto key processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of error, the error indication must be placed in the +.Fa krp_status +field of the +.Fa cryptkop +structure. +When the request is completed, or an error is detected, the +.Fn kprocess +routine should invoked +.Fn crypto_kdone . +.Sh RETURN VALUES +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +.Fn crypto_newsession , +and +.Fn crypto_freesession +return 0 on success, or an error code on failure. +.Fn crypto_get_driverid +returns a non-negative value on error, and \-1 on failure. +.Fn crypto_getreq +returns a pointer to a +.Fa cryptop +structure and +.Dv NULL +on failure. +.Fn crypto_dispatch +returns +.Er EINVAL +is its argument or the callback function was +.Dv NULL , +and 0 otherwise. +The callback is provided with an error code in case of failure, in the +.Fa crp_etype +field. +.Sh FILES +.Bl -tag -width sys/crypto/crypto.c +.It Pa sys/crypto/crypto.c +most of the framework code +.El +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr pcmcia 4 , +.Xr malloc 9 , +.Xr tsleep 9 +.Sh HISTORY +The cryptographic framework first appeared in +OpenBSD 2.7 +and was written by Angelos D. Keromytis <angelos@openbsd.org>. +.Sh BUGS +The framework currently assumes that all the algorithms in a +.Fn crypto_newsession +operation must be available by the same driver. +If that's not the case, session initialization will fail. +.Pp +The framework also needs a mechanism for determining which driver is +best for a specific set of algorithms associated with a session. +Some type of benchmarking is in order here. +.Pp +Multiple instances of the same algorithm in the same session are not +supported. +Note that 3DES is considered one algorithm (and not three +instances of DES). +Thus, 3DES and DES could be mixed in the same request. +.Pp +A queue for completed operations should be implemented and processed +at some software +.Xr spl 9 +level, to avoid overall system latency issues, and potential kernel +stack exhaustion while processing a callback. +.Pp +When SMP time comes, we will support use of a second processor (or +more) as a crypto device (this is actually AMP, but we need the same +basic support). |
