Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CRYPTO(9)	       FreeBSD Kernel Developer's Manual	     CRYPTO(9)

NAME
     crypto -- API for cryptographic services in the kernel

SYNOPSIS
     #include <opencrypto/cryptodev.h>

DESCRIPTION
     crypto is a framework for in-kernel cryptography.	It permits in-kernel
     consumers to encrypt and decrypt data and also enables userland applica-
     tions to use cryptographic	hardware through the /dev/crypto device.

     crypto supports two modes of operation: one mode for symmetric-keyed
     cryptographic requests and	digest,	and a second mode for asymmetric-key
     requests and modular arithmetic.

   Symmetric-Key Mode
     Symmetric-key operations include encryption and decryption	operations us-
     ing block and stream ciphers as well as computation and verification of
     message authentication codes (MACs).  In this mode, consumers allocate
     sessions to describe a transform as discussed in crypto_session(9).  Con-
     sumers then allocate request objects to describe each transformation such
     as	encrypting a network packet or decrypting a disk sector.  Requests are
     described in crypto_request(9).

     Device drivers are	responsible for	processing requests submitted by con-
     sumers.  crypto_driver(9) describes the interfaces	drivers	use to regis-
     ter with the framework, helper routines the framework provides to facili-
     ate request processing, and the interfaces	drivers	are required to	pro-
     vide.

   Asymmetric-Key Mode
     Assymteric-key operations do not use sessions.  Instead, these operations
     perform individual	mathematical operations	using a	set of input and out-
     put parameters.  These operations are described in	crypto_asym(9).	 Driv-
     ers that support asymmetric operations use	additional interfaces de-
     scribed in	crypto_asym(9) in addition to the base interfaces described in
     crypto_driver(9).

   Callbacks
     Since the consumers may not be associated with a process, drivers may not
     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 call-
     back is specified by the consumer on a per-request	basis).	 The callback
     is	invoked	by the framework whether the request was successfully com-
     pleted or not.  Errors are	reported to the	callback function.

     Session initialization does not use callbacks and returns errors syn-
     chronously.

   Session Migration
     For symmetric-key operations, a specific error code, EAGAIN, is used to
     indicate that a session handle has	changed	and that the request may be
     re-submitted immediately with the new session.  The consumer should up-
     date its saved copy of the	session	handle to the value of crp_session so
     that future requests use the new session.

   Supported Algorithms
     More details on some algorithms may be found in crypto(7).	 These algo-
     rithms are	used for symmetric-mode	operations.  Asymmetric-mode opera-
     tions support operations described	in crypto_asym(9).

     The following authentication algorithms are supported:

	   CRYPTO_AES_CCM_CBC_MAC
	   CRYPTO_AES_NIST_GMAC
	   CRYPTO_BLAKE2B
	   CRYPTO_BLAKE2S
	   CRYPTO_NULL_HMAC
	   CRYPTO_POLY1305
	   CRYPTO_RIPEMD160
	   CRYPTO_RIPEMD160_HMAC
	   CRYPTO_SHA1
	   CRYPTO_SHA1_HMAC
	   CRYPTO_SHA2_224
	   CRYPTO_SHA2_224_HMAC
	   CRYPTO_SHA2_256
	   CRYPTO_SHA2_256_HMAC
	   CRYPTO_SHA2_384
	   CRYPTO_SHA2_384_HMAC
	   CRYPTO_SHA2_512
	   CRYPTO_SHA2_512_HMAC

     The following encryption algorithms are supported:

	   CRYPTO_AES_CBC
	   CRYPTO_AES_ICM
	   CRYPTO_AES_XTS
	   CRYPTO_CAMELLIA_CBC
	   CRYPTO_CHACHA20
	   CRYPTO_NULL_CBC

     The following authenticated encryption with additional data (AEAD)	algo-
     rithms are	supported:

	   CRYPTO_AES_CCM_16
	   CRYPTO_AES_NIST_GCM_16

     The following compression algorithms are supported:

	   CRYPTO_DEFLATE_COMP

FILES
     sys/opencrypto/crypto.c  most of the framework code

SEE ALSO
     crypto(4),	ipsec(4), crypto(7), crypto_asym(9), crypto_driver(9),
     crypto_request(9),	crypto_session(9), sleep(9)

HISTORY
     The cryptographic framework first appeared	in OpenBSD 2.7 and was written
     by	Angelos	D. Keromytis <angelos@openbsd.org>.

BUGS
     The framework 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.

FreeBSD	13.0			 May 11, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=crypto&sektion=9&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help