/share/man/man9/crypto.9
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 665 lines · 658 code · 7 blank · 0 comment · 0 complexity · 5913da3122b5c57ef984c7ce8e8ef6c9 MD5 · raw file
- .\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
- .\"
- .\" The author of this manual 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.
- .\"
- .\" $FreeBSD$
- .\"
- .Dd September 19, 2007
- .Dt CRYPTO 9
- .Os
- .Sh NAME
- .Nm crypto
- .Nd API for cryptographic services in the kernel
- .Sh SYNOPSIS
- .In opencrypto/cryptodev.h
- .Ft int32_t
- .Fn crypto_get_driverid uint8_t
- .Ft int
- .Fn crypto_register uint32_t int uint16_t uint32_t "int \*[lp]*\*[rp]\*[lp]void *, uint32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, uint64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *"
- .Ft int
- .Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
- .Ft int
- .Fn crypto_unregister uint32_t int
- .Ft int
- .Fn crypto_unregister_all uint32_t
- .Ft void
- .Fn crypto_done "struct cryptop *"
- .Ft void
- .Fn crypto_kdone "struct cryptkop *"
- .Ft int
- .Fn crypto_newsession "uint64_t *" "struct cryptoini *" int
- .Ft int
- .Fn crypto_freesession uint64_t
- .Ft int
- .Fn crypto_dispatch "struct cryptop *"
- .Ft int
- .Fn crypto_kdispatch "struct cryptkop *"
- .Ft int
- .Fn crypto_unblock uint32_t int
- .Ft "struct cryptop *"
- .Fn crypto_getreq int
- .Ft void
- .Fn crypto_freereq void
- .Bd -literal
- #define CRYPTO_SYMQ 0x1
- #define CRYPTO_ASYMQ 0x2
- #define EALG_MAX_BLOCK_LEN 16
- struct cryptoini {
- int cri_alg;
- int cri_klen;
- int cri_mlen;
- caddr_t cri_key;
- uint8_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;
- #define crd_iv CRD_INI.cri_iv
- #define crd_key CRD_INI.cri_key
- #define crd_alg CRD_INI.cri_alg
- #define crd_klen CRD_INI.cri_klen
- struct cryptodesc *crd_next;
- };
- struct cryptop {
- TAILQ_ENTRY(cryptop) crp_next;
- uint64_t crp_sid;
- int crp_ilen;
- int crp_olen;
- int crp_etype;
- int crp_flags;
- caddr_t crp_buf;
- caddr_t crp_opaque;
- struct cryptodesc *crp_desc;
- int (*crp_callback) (struct cryptop *);
- caddr_t crp_mac;
- };
- struct crparam {
- caddr_t crp_p;
- u_int crp_nbits;
- };
- #define CRK_MAXPARAM 8
- struct cryptkop {
- TAILQ_ENTRY(cryptkop) krp_next;
- 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 */
- uint32_t krp_hid;
- struct crparam krp_param[CRK_MAXPARAM];
- int (*krp_callback)(struct cryptkop *);
- };
- .Ed
- .Sh DESCRIPTION
- .Nm
- is a framework for drivers of cryptographic hardware to register with
- the kernel so
- .Dq consumers
- (other kernel subsystems, and
- users through the
- .Pa /dev/crypto
- 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
- .Xr sleep 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 a 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.
- .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
- .Vt cryptoini
- structure are:
- .Bl -tag -width ".Va cri_next"
- .It Va cri_alg
- Contains an algorithm identifier.
- Currently supported algorithms are:
- .Pp
- .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
- .It Dv CRYPTO_AES_CBC
- .It Dv CRYPTO_ARC4
- .It Dv CRYPTO_BLF_CBC
- .It Dv CRYPTO_CAMELLIA_CBC
- .It Dv CRYPTO_CAST_CBC
- .It Dv CRYPTO_DES_CBC
- .It Dv CRYPTO_3DES_CBC
- .It Dv CRYPTO_SKIPJACK_CBC
- .It Dv CRYPTO_MD5
- .It Dv CRYPTO_MD5_HMAC
- .It Dv CRYPTO_MD5_KPDK
- .It Dv CRYPTO_RIPEMD160_HMAC
- .It Dv CRYPTO_SHA1
- .It Dv CRYPTO_SHA1_HMAC
- .It Dv CRYPTO_SHA1_KPDK
- .It Dv CRYPTO_SHA2_256_HMAC
- .It Dv CRYPTO_SHA2_384_HMAC
- .It Dv CRYPTO_SHA2_512_HMAC
- .It Dv CRYPTO_NULL_HMAC
- .It Dv CRYPTO_NULL_CBC
- .El
- .It Va cri_klen
- Specifies the length of the key in bits, for variable-size key
- algorithms.
- .It Va cri_mlen
- Specifies how many bytes from the calculated hash should be copied back.
- 0 means entire hash.
- .It Va cri_key
- Contains the key to be used with the algorithm.
- .It Va 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 Va cri_next
- Contains a pointer to another
- .Vt cryptoini
- structure.
- Multiple such structures may be linked to establish multi-algorithm sessions
- .Xr ( ipsec 4
- is an example consumer of such a feature).
- .El
- .Pp
- The
- .Vt 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
- .Vt cryptop
- structure are:
- .Bl -tag -width ".Va crp_callback"
- .It Va crp_sid
- Contains the SID.
- .It Va crp_ilen
- Indicates the total length in bytes of the buffer to be processed.
- .It Va crp_olen
- On return, contains the total length of the result.
- For symmetric crypto operations, this will be the same as the input length.
- This will be used if the framework needs to allocate a new
- buffer for the result (or for re-formatting the input).
- .It Va 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
- .Va crp_etype
- field.
- It is the responsibility of the callback routine to set the appropriate
- .Xr spl 9
- level.
- .It Va 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
- .Va 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
- .Va 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 Va crp_flags
- Is a bitmask of flags associated with this request.
- Currently defined flags are:
- .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
- .It Dv CRYPTO_F_IMBUF
- The buffer pointed to by
- .Va crp_buf
- is an mbuf chain.
- .It Dv CRYPTO_F_IOV
- The buffer pointed to by
- .Va crp_buf
- is an
- .Vt uio
- structure.
- .It Dv CRYPTO_F_REL
- Must return data in the same place.
- .It Dv CRYPTO_F_BATCH
- Batch operation if possible.
- .It Dv CRYPTO_F_CBIMM
- Do callback immediately instead of doing it from a dedicated kernel thread.
- .It Dv CRYPTO_F_DONE
- Operation completed.
- .It Dv CRYPTO_F_CBIFSYNC
- Do callback immediately if operation is synchronous.
- .El
- .It Va 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,
- depending on
- .Va crp_flags .
- .It Va crp_opaque
- This is passed through the crypto framework untouched and is
- intended for the invoking application's use.
- .It Va 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 ".Va crd_inject"
- .It Va crd_iv
- The field where IV should be provided when the
- .Dv CRD_F_IV_EXPLICIT
- flag is given.
- .It Va crd_key
- When the
- .Dv CRD_F_KEY_EXPLICIT
- flag is given, the
- .Va crd_key
- points to a buffer with encryption or authentication key.
- .It Va crd_alg
- An algorithm to use.
- Must be the same as the one given at newsession time.
- .It Va crd_klen
- The
- .Va crd_key
- key length.
- .It Va crd_skip
- The offset in the input buffer where processing should start.
- .It Va crd_len
- How many bytes, after
- .Va crd_skip ,
- should be processed.
- .It Va 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
- .Va crd_flags ) .
- For MAC algorithms, this is where the result of the keyed hash will be
- inserted.
- .It Va crd_flags
- The following flags are defined:
- .Bl -tag -width 3n
- .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
- .Va 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
- .Va 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
- .Va crd_iv
- field.
- 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
- .Va 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_KEY_EXPLICIT
- For encryption and authentication (MAC) algorithms, this bit is set when the key
- is explicitly provided by the consumer in the
- .Va crd_key
- field for the given operation.
- Otherwise, the key is taken at newsession time from the
- .Va cri_key
- field.
- .It Dv CRD_F_COMP
- For compression algorithms, this bit is set when compression is required (when
- not set, decompression is performed).
- .El
- .It Va CRD_INI
- This
- .Vt 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 Va 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
- .Vt cryptop
- structure with a linked list of as many
- .Vt cryptodesc
- structures as were specified in the argument passed to it.
- .Pp
- .Fn crypto_freereq
- deallocates a structure
- .Vt cryptop
- and any
- .Vt 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
- .Vt cryptop
- structure.
- .Pp
- .Fn crypto_kdispatch
- is called to perform a keying operation.
- The various fields in the
- .Vt cryptkop
- structure are:
- .Bl -tag -width ".Va krp_callback"
- .It Va krp_op
- Operation code, such as
- .Dv CRK_MOD_EXP .
- .It Va krp_status
- Return code.
- This
- .Va errno Ns -style
- variable indicates whether lower level reasons
- for operation failure.
- .It Va krp_iparams
- Number if input parameters to the specified operation.
- Note that each operation has a (typically hardwired) number of such parameters.
- .It Va krp_oparams
- Number if output parameters from the specified operation.
- Note that each operation has a (typically hardwired) number of such parameters.
- .It Va krp_kvp
- An array of kernel memory blocks containing the parameters.
- .It Va krp_hid
- Identifier specifying which low-level driver is being used.
- .It Va 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 ,
- .Fn crypto_unblock ,
- 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 ) .
- 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 for this algorithm.
- The last four 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.); and an opaque parameter to pass when calling each of these routines.
- .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
- PCMCIA
- crypto cards that are being ejected will invoke this routine for all
- algorithms supported by the card.
- .Fn crypto_unregister_all
- will unregister all algorithms registered by a driver
- 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:
- .Pp
- .Bl -item -compact
- .It
- .Ft int
- .Fn \*[lp]*newsession\*[rp] "void *" "uint32_t *" "struct cryptoini *" ;
- .It
- .Ft int
- .Fn \*[lp]*freesession\*[rp] "void *" "uint64_t" ;
- .It
- .Ft int
- .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
- .It
- .Ft int
- .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
- .El
- .Pp
- On invocation, the first argument to
- all routines is an opaque data value supplied when the algorithm
- is registered with
- .Fn crypto_register .
- The second argument to
- .Fn newsession
- contains the driver identifier obtained via
- .Fn crypto_get_driverid .
- On successful return, it should contain a driver-specific session
- identifier.
- The third argument is identical to that of
- .Fn crypto_newsession .
- .Pp
- The
- .Fn freesession
- routine takes as arguments the opaque data value and 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 an unrecoverable error, the error indication must be placed in the
- .Va crp_etype
- field of the
- .Vt cryptop
- structure.
- When the request is completed, or an error is detected, the
- .Fn process
- routine should invoke
- .Fn crypto_done .
- Session migration may be performed, as mentioned previously.
- .Pp
- In case of a temporary resource exhaustion, the
- .Fn process
- routine may return
- .Er ERESTART
- in which case the crypto services will requeue the request, mark the driver
- as
- .Dq blocked ,
- and stop submitting requests for processing.
- The driver is then responsible for notifying the crypto services
- when it is again able to process requests through the
- .Fn crypto_unblock
- routine.
- This simple flow control mechanism should only be used for short-lived
- resource exhaustion as it causes operations to be queued in the crypto
- layer.
- Doing so is preferable to returning an error in such cases as
- it can cause network protocols to degrade performance by treating the
- failure much like a lost packet.
- .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 an unrecoverable error, the error indication must be placed in the
- .Va krp_status
- field of the
- .Vt 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 ,
- .Fn crypto_freesession ,
- and
- .Fn crypto_unblock
- 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
- .Vt cryptop
- structure and
- .Dv NULL
- on failure.
- .Fn crypto_dispatch
- returns
- .Er EINVAL
- if 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
- .Va crp_etype
- field.
- .Sh FILES
- .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
- .It Pa sys/opencrypto/crypto.c
- most of the framework code
- .El
- .Sh SEE ALSO
- .Xr ipsec 4 ,
- .Xr malloc 9 ,
- .Xr sleep 9
- .Sh HISTORY
- The cryptographic framework first appeared in
- .Ox 2.7
- and was written by
- .An "Angelos D. Keromytis" Aq 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 is 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.