share/man/man9/crypto_asym.9

   1 .\" Copyright (c) 2020, Chelsio Inc
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions are met:
   5 .\"
   6 .\" 1. Redistributions of source code must retain the above copyright notice,
   7 .\"    this list of conditions and the following disclaimer.
   8 .\"
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" 3. Neither the name of the Chelsio Inc nor the names of its
  14 .\"    contributors may be used to endorse or promote products derived from
  15 .\"    this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" * Other names and brands may be claimed as the property of others.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd March 27, 2020
  34 .Dt CRYPTO_ASYM 9
  35 .Os
  36 .Sh NAME
  37 .Nm crypto_asym
  38 .Nd asymmetric cryptographic operations
  39 .Sh SYNOPSIS
  40 .In opencrypto/cryptodev.h
  41 .Ft int
  42 .Fn crypto_kdispatch "struct cryptkop *krp"
  43 .Ft void
  44 .Fn crypto_kdone "struct cryptkop *krp"
  45 .Ft int
  46 .Fn crypto_kregister "uint32_t driverid" "int kalg" "uint32_t flags"
  47 .Ft int
  48 .Fn CRYPTODEV_KPROCESS "device_t dev" "struct cryptop *krp" "int flags"
  49 .Sh DESCRIPTION
  50 The in-kernel cryptographic kernel framework supports asymmetric
  51 requests (keying requests) in addition to symmetric operations.
  52 There are currently no in-kernel users of these requests,
  53 but applications can make requests of hardware drivers via the
  54 .Pa /dev/crypto
  55 device .
  56 .Pp
  57 Some APIs are shared with the framework's symmetric request support.
  58 This manual describes the APIs and data structures unique to
  59 asymmetric requests.
  60 .Pp
  61 .Ss Request Objects
  62 A request is described by a
  63 .Vt struct cryptkop
  64 containing the following fields:
  65 .Bl -tag -width "krp_callback"
  66 .It Fa krp_op
  67 Operation to perform.
  68 Available operations include
  69 .Dv CRK_MOD_EXP ,
  70 .Dv CRK_MOD_EXP_CRT ,
  71 .Dv CRK_DSA_SIGN ,
  72 .Dv CRK_DSA_VERIFY ,
  73 and
  74 .Dv CRK_DH_COMPUTE_KEY .
  75 .It Fa krp_status
  76 Error status.
  77 Either zero on success,
  78 or an error if an operation fails.
  79 Set by drivers prior to completing a request via
  80 .Fn crypto_kdone .
  81 .It Fa krp_iparams
  82 Count of input parameters.
  83 .It Fa krp_oparams
  84 Count of output parameters.
  85 .It Fa krp_crid
  86 Requested device.
  87 .It Fa krp_hid
  88 Device used to complete the request.
  89 .It Fa krp_param
  90 Array of parameters.
  91 The array contains the input parameters first followed by the output
  92 parameters.
  93 Each parameter is stored as a bignum.
  94 Each bignum is described by a
  95 .Vt struct crparam
  96 containing the following fields:
  97 .Bl -tag -width "crp_nbits"
  98 .It Fa crp_p
  99 Pointer to array of packed bytes.
 100 .It Fa crp_nbits
 101 Size of bignum in bits.
 102 .El
 103 .It Fa krp_callback
 104 Callback function.
 105 This must point to a callback function of type
 106 .Vt void (*)(struct cryptkop *) .
 107 The callback function should inspect
 108 .Fa krp_status
 109 to determine the status of the completed operation.
 110 .El
 111 .Pp
 112 New requests should be initialized to zero before setting fields to
 113 appropriate values.
 114 Once the request has been populated,
 115 it should be passed to
 116 .Fn crypto_kdispatch .
 117 .Pp
 118 .Fn crypto_kdispatch
 119 will choose a device driver to perform the operation described by
 120 .Fa krp
 121 and invoke that driver's
 122 .Fn CRYPTO_KPROCESS
 123 method.
 124 .Ss Driver API
 125 Drivers register support for asymmetric operations by calling
 126 .Fn crypto_kregister
 127 for each supported algorithm.
 128 .Fa driverid
 129 should be the value returned by an earlier call to
 130 .Fn crypto_get_driverid .
 131 .Fa kalg
 132 should list one of the operations that can be set in
 133 .Fa krp_op .
 134 .Fa flags
 135 is a bitmask of zero or more of the following values:
 136 .Bl -tag -width "CRYPTO_ALG_FLAG_RNG_ENABLE"
 137 .It Dv CRYPTO_ALG_FLAG_RNG_ENABLE
 138 Device has a hardware RNG for DH/DSA.
 139 .It Dv CRYPTO_ALG_FLAG_DSA_SHA
 140 Device can compute a SHA digest of a message.
 141 .El
 142 .Pp
 143 Drivers unregister with the framework via
 144 .Fn crypto_unregister_all .
 145 .Pp
 146 Similar to
 147 .Fn CRYPTO_PROCESS ,
 148 .Fn CRYPTO_KPROCESS
 149 should complete the request or schedule it for asynchronous
 150 completion.
 151 If this method is not able to complete a request due to insufficient
 152 resources,
 153 it can defer the request (and future asymmetric requests) by returning
 154 .Dv ERESTART .
 155 Once resources are available,
 156 the driver should invoke
 157 .Fn crypto_unblock
 158 with
 159 .Dv CRYPTO_ASYMQ
 160 to resume processing of asymmetric requests.
 161 .Pp
 162 Once a request is completed,
 163 the driver should set
 164 .Fa krp_status
 165 and then call
 166 .Fn crypto_kdone .
 167 .Sh RETURN VALUES
 168 .Fn crypto_kdispatch ,
 169 .Fn crypto_kregister ,
 170 and
 171 .Fn CRYPTODEV_KPROCESS
 172 return zero on success or an error on failure.
 173 .Sh SEE ALSO
 174 .Xr crypto 7 ,
 175 .Xr crypto 9 ,
 176 .Xr crypto_driver 9 ,
 177 .Xr crypto_request 9 ,
 178 .Xr crypto_session 9