👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for crypto (netbsd section 4)

CRYPTO(4)			   BSD Kernel Interfaces Manual 			CRYPTO(4)

NAME
     crypto, swcrypto -- user-mode access to hardware-accelerated cryptography

SYNOPSIS
     hifn*   at pci? dev ? function ?
     ubsec*  at pci? dev ? function ?

     pseudo-device crypto
     pseudo-device swcrypto

     #include <sys/ioctl.h>
     #include <sys/time.h>
     #include <crypto/cryptodev.h>

DESCRIPTION
     The crypto driver gives user-mode applications access to hardware-accelerated cryptographic
     transforms, as implemented by the opencrypto(9) in-kernel interface.

     The swcrypto driver is a software-only implementation of the opencrypto(9) interface, and
     must be included to use the interface without hardware acceleration.

     The /dev/crypto special device provides an ioctl(2) based interface.  User-mode applications
     should open the special device, then issue ioctl(2) calls on the descriptor.  User-mode
     access to /dev/crypto is generally controlled by three sysctl(8) variables, kern.usercrypto,
     kern.userasymcrypto, and kern.cryptodevallowsoft.	See sysctl(7) for additional details.

     The crypto device provides two distinct modes of operation: one mode for symmetric-keyed
     cryptographic requests, and a second mode for both asymmetric-key (public-key/private-key)
     requests, and for modular arithmetic (for Diffie-Hellman key exchange and other crypto-
     graphic protocols).  The two modes are described separately below.

THEORY OF OPERATION
     Regardless of whether symmetric-key or asymmetric-key operations are to be performed, use of
     the device requires a basic series of steps:

     1.   Open a file descriptor for the device.  See open(2).

     2.   If any symmetric operation will be performed, create one session, with CIOCGSESSION, or
	  multiple sessions, with CIOCNGSESSION.  Most applications will require at least one
	  symmetric session.  Since cipher and MAC keys are tied to sessions, many applications
	  will require more.  Asymmetric operations do not use sessions.

     3.   Submit requests, synchronously with CIOCCRYPT (symmetric) or CIOCKEY (asymmetric) or
	  asynchronously with CIOCNCRYPTM (symmetric) or CIOCNFKEYM (asymmetric).  The asynchro-
	  nous interface allows multiple requests to be submitted in one call if the user so
	  desires.

     4.   If the asynchronous interface is used, wait for results with select(2) or poll(2), then
	  collect them with CIOCNCRYPTRET (a particular request) or CIOCNCRYPTRETM (multiple
	  requests).

     5.   Destroy one session with CIOCFSESSION or many at once with CIOCNFSESSION.

     6.   Close the device with close(2).

SYMMETRIC-KEY OPERATION
     The symmetric-key operation mode provides a context-based API to traditional symmetric-key
     encryption (or privacy) algorithms, or to keyed and unkeyed one-way hash (HMAC and MAC)
     algorithms.  The symmetric-key mode also permits fused operation, where the hardware per-
     forms both a privacy algorithm and an integrity-check algorithm in a single pass over the
     data: either a fused encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt opera-
     tion.

     To use symmetric mode, you must first create a session specifying the algorithm(s) and
     key(s) to use; then issue encrypt or decrypt requests against the session.

   Symmetric-key privacy algorithms
     Contingent upon device drivers for installed cryptographic hardware registering with
     opencrypto(9), as providers of a given algorithm, some or all of the following symmetric-key
     privacy algorithms may be available:

	   CRYPTO_DES_CBC
	   CRYPTO_3DES_CBC
	   CRYPTO_BLF_CBC
	   CRYPTO_CAST_CBC
	   CRYPTO_SKIPJACK_CBC
	   CRYPTO_AES_CBC
	   CRYPTO_ARC4

   Integrity-check operations
     Contingent upon hardware support, some or all of the following keyed one-way hash algorithms
     may be available:

	   CRYPTO_RIPEMD160_HMAC
	   CRYPTO_MD5_KPDK
	   CRYPTO_SHA1_KPDK
	   CRYPTO_MD5_HMAC
	   CRYPTO_SHA1_HMAC
	   CRYPTO_SHA2_256_HMAC
	   CRYPTO_SHA2_384_HMAC
	   CRYPTO_SHA2_512_HMAC
	   CRYPTO_MD5
	   CRYPTO_SHA1

     The CRYPTO_MD5 and CRYPTO_SHA1 algorithms are actually unkeyed, but should be requested as
     symmetric-key hash algorithms with a zero-length key.

   IOCTL Request Descriptions
     CRIOGET int *fd
	      This operation is deprecated and will be removed after NetBSD 5.0.  It clones the
	      fd argument to ioctl(2), yielding a new file descriptor for the creation of ses-
	      sions.  Because the device now clones on open, this operation is unnecessary.

     CIOCGSESSION struct session_op *sessp

	      struct session_op {
		  u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
		  u_int32_t mac;      /* e.g. CRYPTO_MD5_HMAC */

		  u_int32_t keylen;   /* cipher key */
		  void * key;
		  int mackeylen;      /* mac key */
		  void * mackey;

		  u_int32_t ses;      /* returns: ses # */
	      };

	      Create a new cryptographic session on a file descriptor for the device; that is, a
	      persistent object specific to the chosen privacy algorithm, integrity algorithm,
	      and keys specified in sessp.  The special value 0 for either privacy or integrity
	      is reserved to indicate that the indicated operation (privacy or integrity) is not
	      desired for this session.

	      Multiple sessions may be bound to a single file descriptor.  The session ID
	      returned in sessp->ses is supplied as a required field in the symmetric-operation
	      structure crypt_op for future encryption or hashing requests.

	      This implementation will never return a session ID of 0 for a successful creation
	      of a session, which is a NetBSD extension.

	      For non-zero symmetric-key privacy algorithms, the privacy algorithm must be speci-
	      fied in sessp->cipher, the key length in sessp->keylen, and the key value in the
	      octets addressed by sessp->key.

	      For keyed one-way hash algorithms, the one-way hash must be specified in
	      sessp->mac, the key length in sessp->mackey, and the key value in the octets
	      addressed by sessp->mackeylen.

	      Support for a specific combination of fused privacy  and integrity-check algorithms
	      depends on whether the underlying hardware supports that combination.  Not all com-
	      binations are supported by all hardware, even if the hardware supports each opera-
	      tion as a stand-alone non-fused operation.

     CIOCNGSESSION struct crypt_sgop *sgop

	      struct crypt_sgop {
		  size_t      count;		      /* how many */
		  struct session_n_op * sessions; /* where to get them */
	      };

	      struct session_n_op {
		  u_int32_t cipher;	      /* e.g. CRYPTO_DES_CBC */
		  u_int32_t mac;	      /* e.g. CRYPTO_MD5_HMAC */

		  u_int32_t keylen;	      /* cipher key */
		  void * key;
		  u_int32_t mackeylen;	      /* mac key */
		  void * mackey;

		  u_int32_t ses;	      /* returns: session # */
		  int status;
	      };

	      Create one or more sessions.  Takes a counted array of session_n_op structures in
	      sgop.  For each requested session (array element n), the session number is returned
	      in sgop->sessions[n].ses and the status for that session creation in
	      sgop->sessions[n].status.

     CIOCCRYPT struct crypt_op *cr_op

	      struct crypt_op {
		  u_int32_t ses;
		  u_int16_t op;       /* e.g. COP_ENCRYPT */
		  u_int16_t flags;
		  u_int len;
		  void * src, *dst;
		  void * mac;	      /* must be large enough for result */
		  void * iv;
	      };

	      Request a symmetric-key (or hash) operation.  The file descriptor argument to
	      ioctl(2) must have been bound to a valid session.  To encrypt, set cr_op->op to
	      COP_ENCRYPT.  To decrypt, set cr_op->op to COP_DECRYPT.  The field cr_op->len sup-
	      plies the length of the input buffer; the fields cr_op->src, cr_op->dst,
	      cr_op->mac, cr_op->iv supply the addresses of the input buffer, output buffer, one-
	      way hash, and initialization vector, respectively.

     CIOCNCRYPTM struct crypt_mop *cr_mop

	      struct crypt_mop {
		  size_t count; 	      /* how many */
		  struct crypt_n_op * reqs;   /* where to get them */
	      };

	      struct crypt_n_op {
		  u_int32_t ses;
		  u_int16_t op; 	      /* e.g. COP_ENCRYPT */
		  u_int16_t flags;
		  u_int len;

		  u_int32_t reqid;	      /* request id */
		  int status;		      /* accepted or not */

		  void *opaque; 	      /* opaque pointer ret to user */
		  u_int32_t keylen;	      /* cipher key - optional */
		  void * key;
		  u_int32_t mackeylen;	      /* mac key - optional */
		  void * mackey;

		  void * src, * dst;
		  void * mac;
		  void * iv;
	      };

	      This is the asynchronous version of CIOCCRYPT, which allows multiple symmetric-key
	      (or hash) operations to be started (see CIOCRYPT above for the details for each
	      operation).

	      The cr_mop->count field specifies the number of operations provided in the
	      cr_mop->reqs array.

	      Each operation is assigned a unique request id returned in the
	      cr_mop->reqs[n].reqid field.

	      Each operation can accept an opaque value from the user to be passed back to the
	      user when the operation completes (e.g., to track context for the request).  The
	      opaque field is cr_mop->reqs[n].opaque.

	      If a problem occurs with starting any of the operations then that operation's
	      cr_mop->reqs[n].status field is filled with the error code.  The failure of an
	      operation does not prevent the other operations from being started.

	      The select(2) or poll(2) functions must be used on the device file descriptor to
	      detect that some operation has completed; results are then retrieved with
	      CIOCNCRYPTRETM.

	      The key and mackey fields of the operation structure are currently unused.  They
	      are intended for use to immediately rekey an existing session before processing a
	      new request.

     CIOCFSESSION void
	      Destroys the /dev/crypto session associated with the file-descriptor argument.

     CIOCNFSESSION struct crypt_sfop *sfop;

	      struct crypt_sfop {
		  size_t count;
		  u_int32_t *sesid;
	      };

	      Destroys the sfop->count sessions specified by the sfop array of session identi-
	      fiers.

ASYMMETRIC-KEY OPERATION
   Asymmetric-key algorithms
     Contingent upon hardware support, the following asymmetric (public-key/private-key; or key-
     exchange subroutine) operations may also be available:

	   Algorithm		 Input parameter    Output parameter
				 Count		    Count
	   CRK_MOD_EXP		 3		    1
	   CRK_MOD_EXP_CRT	 6		    1
	   CRK_MOD_ADD		 3		    1
	   CRK_MOD_ADDINV	 2		    1
	   CRK_MOD_SUB		 3		    1
	   CRK_MOD_MULT 	 3		    1
	   CRK_MOD_MULTINV	 2		    1
	   CRK_MOD		 2		    1
	   CRK_DSA_SIGN 	 5		    2
	   CRK_DSA_VERIFY	 7		    0
	   CRK_DH_COMPUTE_KEY	 3		    1

     See below for discussion of the input and output parameter counts.

   Asymmetric-key commands
     CIOCASYMFEAT int *feature_mask
	      Returns a bitmask of supported asymmetric-key operations.  Each of the above-listed
	      asymmetric operations is present if and only if the bit position numbered by the
	      code for that operation is set.  For example, CRK_MOD_EXP is available if and only
	      if the bit (1 << CRK_MOD_EXP) is set.

     CIOCKEY struct crypt_kop *kop

	      struct crypt_kop {
		  u_int crk_op; 	      /* e.g. CRK_MOD_EXP */
		  u_int crk_status;	      /* return status */
		  u_short crk_iparams;	      /* # of input params */
		  u_short crk_oparams;	      /* # of output params */
		  u_int crk_pad1;
		  struct crparam crk_param[CRK_MAXPARAM];
	      };

	      /* Bignum parameter, in packed bytes. */
	      struct crparam {
		  void * crp_p;
		  u_int crp_nbits;
	      };

	      Performs an asymmetric-key operation from the list above.  The specific operation
	      is supplied in kop->crk_op; final status for the operation is returned in
	      kop->crk_status.	The number of input arguments and the number of output arguments
	      is specified in kop->crk_iparams and kop->crk_iparams, respectively.  The field
	      crk_param[] must be filled in with exactly kop->crk_iparams + kop->crk_oparams
	      arguments, each encoded as a struct crparam (address, bitlength) pair.

	      The semantics of these arguments are currently undocumented.

     CIOCNFKEYM struct crypt_mkop *mkop

	      struct crypt_mkop {
		  size_t count; 	      /* how many */
		  struct crypt_n_op * reqs;   /* where to get them */
	      };

	      struct crypt_n_kop {
		  u_int crk_op; 	      /* e.g. CRK_MOD_EXP */
		  u_int crk_status;	      /* accepted or not */
		  u_short crk_iparams;	      /* # of input params */
		  u_short crk_oparams;	      /* # of output params */
		  u_int32_t crk_reqid;	      /* request id */
		  struct crparam crk_param[CRK_MAXPARAM];
		  void *crk_opaque;	      /* opaque pointer ret to user */
	      };

	      This is the asynchronous version of CIOCKEY, which starts one or more key opera-
	      tions.  See CIOCNCRYPTM above and CIOCNCRYPTRETM below for descriptions of the
	      mkop>count, mkop>reqs, mkop>reqs[n].crk_reqid, mkop>reqs[n].crk_status, and
	      mkop>reqs[n].crk_opaque fields of the argument structure, and result retrieval.

   Asynchronous status commands
     When requests are submitted with the CIOCNCRYPTM or CIOCNFKEYM commands, result retrieval is
     asynchronous (the submit ioctls return immediately).  Use the select(2) or poll(2) functions
     to determine when the file descriptor has completed operations ready to be retrieved.

     CIOCNCRYPTRET struct crypt_result *cres

	      struct crypt_result {
		  u_int32_t reqid;    /* request ID */
		  u_int32_t status;   /* 0 if successful */
		  void * opaque;      /* pointer from user */
	      };

	      Check for the status of the request specified by cres->reqid.  This requires a lin-
	      ear search through all completed requests and should be used with extreme care if
	      the number of requests pending on this file descriptor may be large.

	      The cres->status field is set as follows:

	      0 	   The request has completed, and its results have been copied out to the
			   original crypt_n_op or crypt_n_kop structure used to start the
			   request.  The copyout occurs during this ioctl, so the calling process
			   must be the process that started the request.

	      EINPROGRESS  The request has not yet completed.

	      EINVAL	   The request was not found.

	      Other values indicate a problem during the processing of the request.

     CIOCNCRYPTRETM struct cryptret_t *cret

	      struct cryptret {
		  size_t count; 		      /* space for how many */
		  struct crypt_result * results;      /* where to put them */
	      };

	      Retrieve a number of completed requests.	This ioctl accepts a count and an array
	      (each array element is a crypt_result_t structure as used by CIOCNCRYPTRET above)
	      and fills the array with up to cret->count results of completed requests.

	      This ioctl fills in the cret->results[n].reqid field, so that the request which has
	      completed may be identified by the application.  Note that the results may include
	      requests submitted both as symmetric and asymmetric operations.

SEE ALSO
     hifn(4), ubsec(4), opencrypto(9)

HISTORY
     The crypto driver is derived from a version which appeared in FreeBSD 4.8, which in turn is
     based on code which appeared in OpenBSD 3.2.

     The "new API" for asynchronous operation with multiple basic operations per system call (the
     "N" ioctl variants) was contributed by Coyote Point Systems, Inc. and first appeared in
     NetBSD 5.0.

BUGS
     Error checking and reporting is weak.

     The values specified for symmetric-key key sizes to CIOCGSESSION must exactly match the val-
     ues expected by opencrypto(9).  The output buffer and MAC buffers supplied to CIOCCRYPT must
     follow whether privacy or integrity algorithms were specified for session: if you request a
     non-NULL algorithm, you must supply a suitably-sized buffer.

     The scheme for passing arguments for asymmetric requests is baroque.

     The naming inconsistency between CRIOGET and the various CIOC* names is an unfortunate his-
     torical artifact.

BSD					February 25, 2011				      BSD


All times are GMT -4. The time now is 05:14 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password