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