share/man/man9/crypto.9

   1 .\"     $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
   2 .\"
   3 .\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu)
   4 .\"
   5 .\" Copyright (c) 2000, 2001 Angelos D. Keromytis
   6 .\"
   7 .\" Permission to use, copy, and modify this software with or without fee
   8 .\" is hereby granted, provided that this entire notice is included in
   9 .\" all source code copies of any software which is or includes a copy or
  10 .\" modification of this software.
  11 .\"
  12 .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
  13 .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
  14 .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
  15 .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
  16 .\" PURPOSE.
  17 .\"
  18 .Dd April 12, 2021
  19 .Dt CRYPTO 9
  20 .Os
  21 .Sh NAME
  22 .Nm crypto
  23 .Nd API for cryptographic services in the kernel
  24 .Sh SYNOPSIS
  25 .In opencrypto/cryptodev.h
  26 .Sh DESCRIPTION
  27 .Nm
  28 is a framework for in-kernel cryptography.
  29 It permits in-kernel consumers to encrypt and decrypt data
  30 and also enables userland applications to use cryptographic hardware
  31 through the
  32 .Pa /dev/crypto
  33 device.
  34 .Pp
  35 .Nm
  36 supports encryption and decryption operations
  37 using block and stream ciphers as well as computation and verification
  38 of message authentication codes (MACs).
  39 Consumers allocate sessions to describe a transform as discussed in
  40 .Xr crypto_session 9 .
  41 Consumers then allocate request objects to describe each transformation
  42 such as encrypting a network packet or decrypting a disk sector.
  43 Requests are described in
  44 .Xr crypto_request 9 .
  45 .Pp
  46 Device drivers are responsible for processing requests submitted by
  47 consumers.
  48 .Xr crypto_driver 9
  49 describes the interfaces drivers use to register with the framework,
  50 helper routines the framework provides to facilitate request processing,
  51 and the interfaces drivers are required to provide.
  52 .Ss Callbacks
  53 Since the consumers may not be associated with a process, drivers may
  54 not
  55 .Xr sleep 9 .
  56 The same holds for the framework.
  57 Thus, a callback mechanism is used
  58 to notify a consumer that a request has been completed (the
  59 callback is specified by the consumer on a per-request basis).
  60 The callback is invoked by the framework whether the request was
  61 successfully completed or not.
  62 Errors are reported to the callback function.
  63 .Pp
  64 Session initialization does not use callbacks and returns errors
  65 synchronously.
  66 .Ss Session Migration
  67 Operations may fail with a specific error code,
  68 .Er EAGAIN ,
  69 to indicate that a session handle has changed and that the
  70 request may be re-submitted immediately with the new session.
  71 The consumer should update its saved copy of the session handle
  72 to the value of
  73 .Fa crp_session
  74 so that future requests use the new session.
  75 .Ss Supported Algorithms
  76 More details on some algorithms may be found in
  77 .Xr crypto 7 .
  78 .Pp
  79 The following authentication algorithms are supported:
  80 .Pp
  81 .Bl -tag -offset indent -width CRYPTO_AES_CCM_CBC_MAC -compact
  82 .It Dv CRYPTO_AES_CCM_CBC_MAC
  83 .It Dv CRYPTO_AES_NIST_GMAC
  84 .It Dv CRYPTO_BLAKE2B
  85 .It Dv CRYPTO_BLAKE2S
  86 .It Dv CRYPTO_NULL_HMAC
  87 .It Dv CRYPTO_POLY1305
  88 .It Dv CRYPTO_RIPEMD160
  89 .It Dv CRYPTO_RIPEMD160_HMAC
  90 .It Dv CRYPTO_SHA1
  91 .It Dv CRYPTO_SHA1_HMAC
  92 .It Dv CRYPTO_SHA2_224
  93 .It Dv CRYPTO_SHA2_224_HMAC
  94 .It Dv CRYPTO_SHA2_256
  95 .It Dv CRYPTO_SHA2_256_HMAC
  96 .It Dv CRYPTO_SHA2_384
  97 .It Dv CRYPTO_SHA2_384_HMAC
  98 .It Dv CRYPTO_SHA2_512
  99 .It Dv CRYPTO_SHA2_512_HMAC
 100 .El
 101 .Pp
 102 The following encryption algorithms are supported:
 103 .Pp
 104 .Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact
 105 .It Dv CRYPTO_AES_CBC
 106 .It Dv CRYPTO_AES_ICM
 107 .It Dv CRYPTO_AES_XTS
 108 .It Dv CRYPTO_CAMELLIA_CBC
 109 .It Dv CRYPTO_CHACHA20
 110 .It Dv CRYPTO_NULL_CBC
 111 .El
 112 .Pp
 113 The following authenticated encryption with additional data (AEAD)
 114 algorithms are supported:
 115 .Pp
 116 .Bl -tag -offset indent -width CRYPTO_CHACHA20_POLY1305 -compact
 117 .It Dv CRYPTO_AES_CCM_16
 118 .It Dv CRYPTO_AES_NIST_GCM_16
 119 .It Dv CRYPTO_CHACHA20_POLY1305
 120 .El
 121 .Pp
 122 The following compression algorithms are supported:
 123 .Pp
 124 .Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact
 125 .It Dv CRYPTO_DEFLATE_COMP
 126 .El
 127 .Sh FILES
 128 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
 129 .It Pa sys/opencrypto/crypto.c
 130 most of the framework code
 131 .El
 132 .Sh SEE ALSO
 133 .Xr crypto 4 ,
 134 .Xr ipsec 4 ,
 135 .Xr crypto 7 ,
 136 .Xr crypto_driver 9 ,
 137 .Xr crypto_request 9 ,
 138 .Xr crypto_session 9 ,
 139 .Xr sleep 9
 140 .Sh HISTORY
 141 The cryptographic framework first appeared in
 142 .Ox 2.7
 143 and was written by
 144 .An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
 145 .Sh BUGS
 146 The framework needs a mechanism for determining which driver is
 147 best for a specific set of algorithms associated with a session.
 148 Some type of benchmarking is in order here.