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 .\" $FreeBSD$
  19 .\"
  20 .Dd May 11, 2020
  21 .Dt CRYPTO 9
  22 .Os
  23 .Sh NAME
  24 .Nm crypto
  25 .Nd API for cryptographic services in the kernel
  26 .Sh SYNOPSIS
  27 .In opencrypto/cryptodev.h
  28 .Sh DESCRIPTION
  29 .Nm
  30 is a framework for in-kernel cryptography.
  31 It permits in-kernel consumers to encrypt and decrypt data
  32 and also enables userland applications to use cryptographic hardware
  33 through the
  34 .Pa /dev/crypto
  35 device.
  36 .Pp
  37 .Nm
  38 supports two modes of operation:
  39 one mode for symmetric-keyed cryptographic requests and digest,
  40 and a second mode for asymmetric-key requests and modular arithmetic.
  41 .Ss Symmetric-Key Mode
  42 Symmetric-key operations include encryption and decryption operations
  43 using block and stream ciphers as well as computation and verification
  44 of message authentication codes (MACs).
  45 In this mode,
  46 consumers allocate sessions to describe a transform as discussed in
  47 .Xr crypto_session 9 .
  48 Consumers then allocate request objects to describe each transformation
  49 such as encrypting a network packet or decrypting a disk sector.
  50 Requests are described in
  51 .Xr crypto_request 9 .
  52 .Pp
  53 Device drivers are responsible for processing requests submitted by
  54 consumers.
  55 .Xr crypto_driver 9
  56 describes the interfaces drivers use to register with the framework,
  57 helper routines the framework provides to faciliate request processing,
  58 and the interfaces drivers are required to provide.
  59 .Ss Asymmetric-Key Mode
  60 Assymteric-key operations do not use sessions.
  61 Instead,
  62 these operations perform individual mathematical operations using a set
  63 of input and output parameters.
  64 These operations are described in
  65 .Xr crypto_asym 9 .
  66 Drivers that support asymmetric operations use additional interfaces
  67 described in
  68 .Xr crypto_asym 9
  69 in addition to the base interfaces described in
  70 .Xr crypto_driver 9 .
  71 .Ss Callbacks
  72 Since the consumers may not be associated with a process, drivers may
  73 not
  74 .Xr sleep 9 .
  75 The same holds for the framework.
  76 Thus, a callback mechanism is used
  77 to notify a consumer that a request has been completed (the
  78 callback is specified by the consumer on a per-request basis).
  79 The callback is invoked by the framework whether the request was
  80 successfully completed or not.
  81 Errors are reported to the callback function.
  82 .Pp
  83 Session initialization does not use callbacks and returns errors
  84 synchronously.
  85 .Ss Session Migration
  86 For symmetric-key operations,
  87 a specific error code,
  88 .Er EAGAIN ,
  89 is used to indicate that a session handle has changed and that the
  90 request may be re-submitted immediately with the new session.
  91 The consumer should update its saved copy of the session handle
  92 to the value of
  93 .Fa crp_session
  94 so that future requests use the new session.
  95 .Ss Supported Algorithms
  96 More details on some algorithms may be found in
  97 .Xr crypto 7 .
  98 These algorithms are used for symmetric-mode operations.
  99 Asymmetric-mode operations support operations described in
 100 .Xr crypto_asym 9 .
 101 .Pp
 102 The following authentication algorithms are supported:
 103 .Pp
 104 .Bl -tag -offset indent -width CRYPTO_AES_CCM_CBC_MAC -compact
 105 .It Dv CRYPTO_AES_CCM_CBC_MAC
 106 .It Dv CRYPTO_AES_NIST_GMAC
 107 .It Dv CRYPTO_BLAKE2B
 108 .It Dv CRYPTO_BLAKE2S
 109 .It Dv CRYPTO_MD5_HMAC
 110 .It Dv CRYPTO_MD5_KPDK
 111 .It Dv CRYPTO_NULL_HMAC
 112 .It Dv CRYPTO_POLY1305
 113 .It Dv CRYPTO_RIPEMD160
 114 .It Dv CRYPTO_RIPEMD160_HMAC
 115 .It Dv CRYPTO_SHA1
 116 .It Dv CRYPTO_SHA1_HMAC
 117 .It Dv CRYPTO_SHA1_KPDK
 118 .It Dv CRYPTO_SHA2_224
 119 .It Dv CRYPTO_SHA2_224_HMAC
 120 .It Dv CRYPTO_SHA2_256
 121 .It Dv CRYPTO_SHA2_256_HMAC
 122 .It Dv CRYPTO_SHA2_384
 123 .It Dv CRYPTO_SHA2_384_HMAC
 124 .It Dv CRYPTO_SHA2_512
 125 .It Dv CRYPTO_SHA2_512_HMAC
 126 .El
 127 .Pp
 128 The following encryption algorithms are supported:
 129 .Pp
 130 .Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact
 131 .It Dv CRYPTO_AES_CBC
 132 .It Dv CRYPTO_AES_ICM
 133 .It Dv CRYPTO_AES_XTS
 134 .It Dv CRYPTO_ARC4
 135 .It Dv CRYPTO_BLF_CBC
 136 .It Dv CRYPTO_CAMELLIA_CBC
 137 .It Dv CRYPTO_CHACHA20
 138 .It Dv CRYPTO_DES_CBC
 139 .It Dv CRYPTO_3DES_CBC
 140 .It Dv CRYPTO_NULL_CBC
 141 .El
 142 .Pp
 143 The following authenticated encryption with additional data (AEAD)
 144 algorithms are supported:
 145 .Pp
 146 .Bl -tag -offset indent -width CRYPTO_AES_NIST_GCM_16 -compact
 147 .It Dv CRYPTO_AES_CCM_16
 148 .It Dv CRYPTO_AES_NIST_GCM_16
 149 .El
 150 .Pp
 151 The following compression algorithms are supported:
 152 .Pp
 153 .Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact
 154 .It Dv CRYPTO_DEFLATE_COMP
 155 .El
 156 .Sh FILES
 157 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
 158 .It Pa sys/opencrypto/crypto.c
 159 most of the framework code
 160 .El
 161 .Sh SEE ALSO
 162 .Xr crypto 4 ,
 163 .Xr ipsec 4 ,
 164 .Xr crypto 7 ,
 165 .Xr crypto_asym 9 ,
 166 .Xr crypto_driver 9 ,
 167 .Xr crypto_request 9 ,
 168 .Xr crypto_session 9 ,
 169 .Xr sleep 9
 170 .Sh HISTORY
 171 The cryptographic framework first appeared in
 172 .Ox 2.7
 173 and was written by
 174 .An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
 175 .Sh BUGS
 176 The framework needs a mechanism for determining which driver is
 177 best for a specific set of algorithms associated with a session.
 178 Some type of benchmarking is in order here.