NAME
crypto_asym —
asymmetric cryptographic
operations
SYNOPSIS
#include
<opencrypto/cryptodev.h>
int
crypto_kdispatch(struct
cryptkop *krp);
void
crypto_kdone(struct
cryptkop *krp);
int
crypto_kregister(uint32_t
driverid, int kalg,
uint32_t flags);
int
CRYPTODEV_KPROCESS(device_t
dev, struct cryptop
*krp, int
flags);
DESCRIPTION
The in-kernel cryptographic kernel framework supports asymmetric requests (keying requests) in addition to symmetric operations. There are currently no in-kernel users of these requests, but applications can make requests of hardware drivers via the /dev/crypto device .Some APIs are shared with the framework's symmetric request support. This manual describes the APIs and data structures unique to asymmetric requests.
Request Objects
A request is described by a struct cryptkop containing the following fields:
- krp_op
- Operation to perform. Available operations include
CRK_MOD_EXP,CRK_MOD_EXP_CRT,CRK_DSA_SIGN,CRK_DSA_VERIFY, andCRK_DH_COMPUTE_KEY. - krp_status
- Error status. Either zero on success, or an error if an operation fails.
Set by drivers prior to completing a request via
crypto_kdone(). - krp_iparams
- Count of input parameters.
- krp_oparams
- Count of output parameters.
- krp_crid
- Requested device.
- krp_hid
- Device used to complete the request.
- krp_param
- Array of parameters. The array contains the input parameters first
followed by the output parameters. Each parameter is stored as a bignum.
Each bignum is described by a struct crparam
containing the following fields:
- crp_p
- Pointer to array of packed bytes.
- crp_nbits
- Size of bignum in bits.
- krp_callback
- Callback function. This must point to a callback function of type void (*)(struct cryptkop *). The callback function should inspect krp_status to determine the status of the completed operation.
New requests should be initialized to zero
before setting fields to appropriate values. Once the request has been
populated, it should be passed to
crypto_kdispatch().
crypto_kdispatch()
will choose a device driver to perform the operation described by
krp and invoke that driver's
CRYPTO_KPROCESS()
method.
Driver API
Drivers register support for asymmetric operations by calling
crypto_kregister()
for each supported algorithm. driverid should be the
value returned by an earlier call to
crypto_get_driverid().
kalg should list one of the operations that can be set
in krp_op. flags is a bitmask of
zero or more of the following values:
CRYPTO_ALG_FLAG_RNG_ENABLE- Device has a hardware RNG for DH/DSA.
CRYPTO_ALG_FLAG_DSA_SHA- Device can compute a SHA digest of a message.
Drivers unregister with the framework
via
crypto_unregister_all().
Similar to
CRYPTO_PROCESS(),
CRYPTO_KPROCESS()
should complete the request or schedule it for asynchronous completion. If
this method is not able to complete a request due to insufficient resources,
it can defer the request (and future asymmetric requests) by returning
ERESTART. Once resources are available, the driver
should invoke
crypto_unblock()
with CRYPTO_ASYMQ to resume processing of asymmetric
requests.
Once a request is completed, the driver should
set krp_status and then call
crypto_kdone().
RETURN VALUES
crypto_kdispatch(),
crypto_kregister(), and
CRYPTODEV_KPROCESS() return zero on success or an
error on failure.
SEE ALSO
crypto(7), crypto(9), crypto_driver(9), crypto_request(9), crypto_session(9)