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 March 27, 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
 110 .It Dv CRYPTO_MD5_HMAC
 111 .It Dv CRYPTO_MD5_KPDK
 112 .It Dv CRYPTO_NULL_HMAC
 113 .It Dv CRYPTO_POLY1305
 114 .It Dv CRYPTO_RIPEMD160
 115 .It Dv CRYPTO_RIPEMD160_HMAC
 116 .It Dv CRYPTO_SHA1
 117 .It Dv CRYPTO_SHA1_HMAC
 118 .It Dv CRYPTO_SHA1_KPDK
 119 .It Dv CRYPTO_SHA2_224
 120 .It Dv CRYPTO_SHA2_224_HMAC
 121 .It Dv CRYPTO_SHA2_256
 122 .It Dv CRYPTO_SHA2_256_HMAC
 123 .It Dv CRYPTO_SHA2_384
 124 .It Dv CRYPTO_SHA2_384_HMAC
 125 .It Dv CRYPTO_SHA2_512
 126 .It Dv CRYPTO_SHA2_512_HMAC
 127 .El
 128 .Pp
 129 The following encryption algorithms are supported:
 130 .Pp
 131 .Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact
 132 .It Dv CRYPTO_AES_CBC
 133 .It Dv CRYPTO_AES_ICM
 134 .It Dv CRYPTO_AES_XTS
 135 .It Dv CRYPTO_ARC4
 136 .It Dv CRYPTO_BLF_CBC
 137 .It Dv CRYPTO_CAMELLIA_CBC
 138 .It Dv CRYPTO_CAST_CBC
 139 .It Dv CRYPTO_CHACHA20
 140 .It Dv CRYPTO_DES_CBC
 141 .It Dv CRYPTO_3DES_CBC
 142 .It Dv CRYPTO_NULL_CBC
 143 .It Dv CRYPTO_SKIPJACK_CBC
 144 .El
 145 .Pp
 146 The following authenticated encryption with additional data (AEAD)
 147 algorithms are supported:
 148 .Pp
 149 .Bl -tag -offset indent -width CRYPTO_AES_NIST_GCM_16 -compact
 150 .It Dv CRYPTO_AES_CCM_16
 151 .It Dv CRYPTO_AES_NIST_GCM_16
 152 .El
 153 .Pp
 154 The following compression algorithms are supported:
 155 .Pp
 156 .Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact
 157 .It Dv CRYPTO_DEFLATE_COMP
 158 .El
 159 .Sh FILES
 160 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
 161 .It Pa sys/opencrypto/crypto.c
 162 most of the framework code
 163 .El
 164 .Sh SEE ALSO
 165 .Xr crypto 4 ,
 166 .Xr ipsec 4 ,
 167 .Xr crypto 7 ,
 168 .Xr crypto_asym 9 ,
 169 .Xr crypto_driver 9 ,
 170 .Xr crypto_request 9 ,
 171 .Xr crypto_session 9 ,
 172 .Xr sleep 9
 173 .Sh HISTORY
 174 The cryptographic framework first appeared in
 175 .Ox 2.7
 176 and was written by
 177 .An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
 178 .Sh BUGS
 179 The framework needs a mechanism for determining which driver is
 180 best for a specific set of algorithms associated with a session.
 181 Some type of benchmarking is in order here.