CRYPTO_ASYM(9)         FreeBSD Kernel Developer's Manual        CRYPTO_ASYM(9)

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,
                   and CRK_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)(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)

FreeBSD 13.1-RELEASE-p6         March 27, 2020         FreeBSD 13.1-RELEASE-p6