/share/man/man9/crypto.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 665 lines · 658 code · 7 blank · 0 comment · 0 complexity · 5913da3122b5c57ef984c7ce8e8ef6c9 MD5 · raw file

  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 September 19, 2007
  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. .Ft int32_t
  29. .Fn crypto_get_driverid uint8_t
  30. .Ft int
  31. .Fn crypto_register uint32_t int uint16_t uint32_t "int \*[lp]*\*[rp]\*[lp]void *, uint32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, uint64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *"
  32. .Ft int
  33. .Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
  34. .Ft int
  35. .Fn crypto_unregister uint32_t int
  36. .Ft int
  37. .Fn crypto_unregister_all uint32_t
  38. .Ft void
  39. .Fn crypto_done "struct cryptop *"
  40. .Ft void
  41. .Fn crypto_kdone "struct cryptkop *"
  42. .Ft int
  43. .Fn crypto_newsession "uint64_t *" "struct cryptoini *" int
  44. .Ft int
  45. .Fn crypto_freesession uint64_t
  46. .Ft int
  47. .Fn crypto_dispatch "struct cryptop *"
  48. .Ft int
  49. .Fn crypto_kdispatch "struct cryptkop *"
  50. .Ft int
  51. .Fn crypto_unblock uint32_t int
  52. .Ft "struct cryptop *"
  53. .Fn crypto_getreq int
  54. .Ft void
  55. .Fn crypto_freereq void
  56. .Bd -literal
  57. #define CRYPTO_SYMQ 0x1
  58. #define CRYPTO_ASYMQ 0x2
  59. #define EALG_MAX_BLOCK_LEN 16
  60. struct cryptoini {
  61. int cri_alg;
  62. int cri_klen;
  63. int cri_mlen;
  64. caddr_t cri_key;
  65. uint8_t cri_iv[EALG_MAX_BLOCK_LEN];
  66. struct cryptoini *cri_next;
  67. };
  68. struct cryptodesc {
  69. int crd_skip;
  70. int crd_len;
  71. int crd_inject;
  72. int crd_flags;
  73. struct cryptoini CRD_INI;
  74. #define crd_iv CRD_INI.cri_iv
  75. #define crd_key CRD_INI.cri_key
  76. #define crd_alg CRD_INI.cri_alg
  77. #define crd_klen CRD_INI.cri_klen
  78. struct cryptodesc *crd_next;
  79. };
  80. struct cryptop {
  81. TAILQ_ENTRY(cryptop) crp_next;
  82. uint64_t crp_sid;
  83. int crp_ilen;
  84. int crp_olen;
  85. int crp_etype;
  86. int crp_flags;
  87. caddr_t crp_buf;
  88. caddr_t crp_opaque;
  89. struct cryptodesc *crp_desc;
  90. int (*crp_callback) (struct cryptop *);
  91. caddr_t crp_mac;
  92. };
  93. struct crparam {
  94. caddr_t crp_p;
  95. u_int crp_nbits;
  96. };
  97. #define CRK_MAXPARAM 8
  98. struct cryptkop {
  99. TAILQ_ENTRY(cryptkop) krp_next;
  100. u_int krp_op; /* ie. CRK_MOD_EXP or other */
  101. u_int krp_status; /* return status */
  102. u_short krp_iparams; /* # of input parameters */
  103. u_short krp_oparams; /* # of output parameters */
  104. uint32_t krp_hid;
  105. struct crparam krp_param[CRK_MAXPARAM];
  106. int (*krp_callback)(struct cryptkop *);
  107. };
  108. .Ed
  109. .Sh DESCRIPTION
  110. .Nm
  111. is a framework for drivers of cryptographic hardware to register with
  112. the kernel so
  113. .Dq consumers
  114. (other kernel subsystems, and
  115. users through the
  116. .Pa /dev/crypto
  117. device) are able to make use of it.
  118. Drivers register with the framework the algorithms they support,
  119. and provide entry points (functions) the framework may call to
  120. establish, use, and tear down sessions.
  121. Sessions are used to cache cryptographic information in a particular driver
  122. (or associated hardware), so initialization is not needed with every request.
  123. Consumers of cryptographic services pass a set of
  124. descriptors that instruct the framework (and the drivers registered
  125. with it) of the operations that should be applied on the data (more
  126. than one cryptographic operation can be requested).
  127. .Pp
  128. Keying operations are supported as well.
  129. Unlike the symmetric operators described above,
  130. these sessionless commands perform mathematical operations using
  131. input and output parameters.
  132. .Pp
  133. Since the consumers may not be associated with a process, drivers may
  134. not
  135. .Xr sleep 9 .
  136. The same holds for the framework.
  137. Thus, a callback mechanism is used
  138. to notify a consumer that a request has been completed (the
  139. callback is specified by the consumer on a per-request basis).
  140. The callback is invoked by the framework whether the request was
  141. successfully completed or not.
  142. An error indication is provided in the latter case.
  143. A specific error code,
  144. .Er EAGAIN ,
  145. is used to indicate that a session number has changed and that the
  146. request may be re-submitted immediately with the new session number.
  147. Errors are only returned to the invoking function if not
  148. enough information to call the callback is available (meaning, there
  149. was a fatal error in verifying the arguments).
  150. For session initialization and teardown there is no callback mechanism used.
  151. .Pp
  152. The
  153. .Fn crypto_newsession
  154. routine is called by consumers of cryptographic services (such as the
  155. .Xr ipsec 4
  156. stack) that wish to establish a new session with the framework.
  157. On success, the first argument will contain the Session Identifier (SID).
  158. The second argument contains all the necessary information for
  159. the driver to establish the session.
  160. The third argument indicates whether a
  161. hardware driver (1) should be used or not (0).
  162. The various fields in the
  163. .Vt cryptoini
  164. structure are:
  165. .Bl -tag -width ".Va cri_next"
  166. .It Va cri_alg
  167. Contains an algorithm identifier.
  168. Currently supported algorithms are:
  169. .Pp
  170. .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
  171. .It Dv CRYPTO_AES_CBC
  172. .It Dv CRYPTO_ARC4
  173. .It Dv CRYPTO_BLF_CBC
  174. .It Dv CRYPTO_CAMELLIA_CBC
  175. .It Dv CRYPTO_CAST_CBC
  176. .It Dv CRYPTO_DES_CBC
  177. .It Dv CRYPTO_3DES_CBC
  178. .It Dv CRYPTO_SKIPJACK_CBC
  179. .It Dv CRYPTO_MD5
  180. .It Dv CRYPTO_MD5_HMAC
  181. .It Dv CRYPTO_MD5_KPDK
  182. .It Dv CRYPTO_RIPEMD160_HMAC
  183. .It Dv CRYPTO_SHA1
  184. .It Dv CRYPTO_SHA1_HMAC
  185. .It Dv CRYPTO_SHA1_KPDK
  186. .It Dv CRYPTO_SHA2_256_HMAC
  187. .It Dv CRYPTO_SHA2_384_HMAC
  188. .It Dv CRYPTO_SHA2_512_HMAC
  189. .It Dv CRYPTO_NULL_HMAC
  190. .It Dv CRYPTO_NULL_CBC
  191. .El
  192. .It Va cri_klen
  193. Specifies the length of the key in bits, for variable-size key
  194. algorithms.
  195. .It Va cri_mlen
  196. Specifies how many bytes from the calculated hash should be copied back.
  197. 0 means entire hash.
  198. .It Va cri_key
  199. Contains the key to be used with the algorithm.
  200. .It Va cri_iv
  201. Contains an explicit initialization vector (IV), if it does not prefix
  202. the data.
  203. This field is ignored during initialization.
  204. If no IV is explicitly passed (see below on details), a random IV is used
  205. by the device driver processing the request.
  206. .It Va cri_next
  207. Contains a pointer to another
  208. .Vt cryptoini
  209. structure.
  210. Multiple such structures may be linked to establish multi-algorithm sessions
  211. .Xr ( ipsec 4
  212. is an example consumer of such a feature).
  213. .El
  214. .Pp
  215. The
  216. .Vt cryptoini
  217. structure and its contents will not be modified by the framework (or
  218. the drivers used).
  219. Subsequent requests for processing that use the
  220. SID returned will avoid the cost of re-initializing the hardware (in
  221. essence, SID acts as an index in the session cache of the driver).
  222. .Pp
  223. .Fn crypto_freesession
  224. is called with the SID returned by
  225. .Fn crypto_newsession
  226. to disestablish the session.
  227. .Pp
  228. .Fn crypto_dispatch
  229. is called to process a request.
  230. The various fields in the
  231. .Vt cryptop
  232. structure are:
  233. .Bl -tag -width ".Va crp_callback"
  234. .It Va crp_sid
  235. Contains the SID.
  236. .It Va crp_ilen
  237. Indicates the total length in bytes of the buffer to be processed.
  238. .It Va crp_olen
  239. On return, contains the total length of the result.
  240. For symmetric crypto operations, this will be the same as the input length.
  241. This will be used if the framework needs to allocate a new
  242. buffer for the result (or for re-formatting the input).
  243. .It Va crp_callback
  244. This routine is invoked upon completion of the request, whether
  245. successful or not.
  246. It is invoked through the
  247. .Fn crypto_done
  248. routine.
  249. If the request was not successful, an error code is set in the
  250. .Va crp_etype
  251. field.
  252. It is the responsibility of the callback routine to set the appropriate
  253. .Xr spl 9
  254. level.
  255. .It Va crp_etype
  256. Contains the error type, if any errors were encountered, or zero if
  257. the request was successfully processed.
  258. If the
  259. .Er EAGAIN
  260. error code is returned, the SID has changed (and has been recorded in the
  261. .Va crp_sid
  262. field).
  263. The consumer should record the new SID and use it in all subsequent requests.
  264. In this case, the request may be re-submitted immediately.
  265. This mechanism is used by the framework to perform
  266. session migration (move a session from one driver to another, because
  267. of availability, performance, or other considerations).
  268. .Pp
  269. Note that this field only makes sense when examined by
  270. the callback routine specified in
  271. .Va crp_callback .
  272. Errors are returned to the invoker of
  273. .Fn crypto_process
  274. only when enough information is not present to call the callback
  275. routine (i.e., if the pointer passed is
  276. .Dv NULL
  277. or if no callback routine was specified).
  278. .It Va crp_flags
  279. Is a bitmask of flags associated with this request.
  280. Currently defined flags are:
  281. .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
  282. .It Dv CRYPTO_F_IMBUF
  283. The buffer pointed to by
  284. .Va crp_buf
  285. is an mbuf chain.
  286. .It Dv CRYPTO_F_IOV
  287. The buffer pointed to by
  288. .Va crp_buf
  289. is an
  290. .Vt uio
  291. structure.
  292. .It Dv CRYPTO_F_REL
  293. Must return data in the same place.
  294. .It Dv CRYPTO_F_BATCH
  295. Batch operation if possible.
  296. .It Dv CRYPTO_F_CBIMM
  297. Do callback immediately instead of doing it from a dedicated kernel thread.
  298. .It Dv CRYPTO_F_DONE
  299. Operation completed.
  300. .It Dv CRYPTO_F_CBIFSYNC
  301. Do callback immediately if operation is synchronous.
  302. .El
  303. .It Va crp_buf
  304. Points to the input buffer.
  305. On return (when the callback is invoked),
  306. it contains the result of the request.
  307. The input buffer may be an mbuf
  308. chain or a contiguous buffer,
  309. depending on
  310. .Va crp_flags .
  311. .It Va crp_opaque
  312. This is passed through the crypto framework untouched and is
  313. intended for the invoking application's use.
  314. .It Va crp_desc
  315. This is a linked list of descriptors.
  316. Each descriptor provides
  317. information about what type of cryptographic operation should be done
  318. on the input buffer.
  319. The various fields are:
  320. .Bl -tag -width ".Va crd_inject"
  321. .It Va crd_iv
  322. The field where IV should be provided when the
  323. .Dv CRD_F_IV_EXPLICIT
  324. flag is given.
  325. .It Va crd_key
  326. When the
  327. .Dv CRD_F_KEY_EXPLICIT
  328. flag is given, the
  329. .Va crd_key
  330. points to a buffer with encryption or authentication key.
  331. .It Va crd_alg
  332. An algorithm to use.
  333. Must be the same as the one given at newsession time.
  334. .It Va crd_klen
  335. The
  336. .Va crd_key
  337. key length.
  338. .It Va crd_skip
  339. The offset in the input buffer where processing should start.
  340. .It Va crd_len
  341. How many bytes, after
  342. .Va crd_skip ,
  343. should be processed.
  344. .It Va crd_inject
  345. Offset from the beginning of the buffer to insert any results.
  346. For encryption algorithms, this is where the initialization vector
  347. (IV) will be inserted when encrypting or where it can be found when
  348. decrypting (subject to
  349. .Va crd_flags ) .
  350. For MAC algorithms, this is where the result of the keyed hash will be
  351. inserted.
  352. .It Va crd_flags
  353. The following flags are defined:
  354. .Bl -tag -width 3n
  355. .It Dv CRD_F_ENCRYPT
  356. For encryption algorithms, this bit is set when encryption is required
  357. (when not set, decryption is performed).
  358. .It Dv CRD_F_IV_PRESENT
  359. For encryption algorithms, this bit is set when the IV already
  360. precedes the data, so the
  361. .Va crd_inject
  362. value will be ignored and no IV will be written in the buffer.
  363. Otherwise, the IV used to encrypt the packet will be written
  364. at the location pointed to by
  365. .Va crd_inject .
  366. The IV length is assumed to be equal to the blocksize of the
  367. encryption algorithm.
  368. Some applications that do special
  369. .Dq "IV cooking" ,
  370. such as the half-IV mode in
  371. .Xr ipsec 4 ,
  372. can use this flag to indicate that the IV should not be written on the packet.
  373. This flag is typically used in conjunction with the
  374. .Dv CRD_F_IV_EXPLICIT
  375. flag.
  376. .It Dv CRD_F_IV_EXPLICIT
  377. For encryption algorithms, this bit is set when the IV is explicitly
  378. provided by the consumer in the
  379. .Va crd_iv
  380. field.
  381. Otherwise, for encryption operations the IV is provided for by
  382. the driver used to perform the operation, whereas for decryption
  383. operations it is pointed to by the
  384. .Va crd_inject
  385. field.
  386. This flag is typically used when the IV is calculated
  387. .Dq "on the fly"
  388. by the consumer, and does not precede the data (some
  389. .Xr ipsec 4
  390. configurations, and the encrypted swap are two such examples).
  391. .It Dv CRD_F_KEY_EXPLICIT
  392. For encryption and authentication (MAC) algorithms, this bit is set when the key
  393. is explicitly provided by the consumer in the
  394. .Va crd_key
  395. field for the given operation.
  396. Otherwise, the key is taken at newsession time from the
  397. .Va cri_key
  398. field.
  399. .It Dv CRD_F_COMP
  400. For compression algorithms, this bit is set when compression is required (when
  401. not set, decompression is performed).
  402. .El
  403. .It Va CRD_INI
  404. This
  405. .Vt cryptoini
  406. structure will not be modified by the framework or the device drivers.
  407. Since this information accompanies every cryptographic
  408. operation request, drivers may re-initialize state on-demand
  409. (typically an expensive operation).
  410. Furthermore, the cryptographic
  411. framework may re-route requests as a result of full queues or hardware
  412. failure, as described above.
  413. .It Va crd_next
  414. Point to the next descriptor.
  415. Linked operations are useful in protocols such as
  416. .Xr ipsec 4 ,
  417. where multiple cryptographic transforms may be applied on the same
  418. block of data.
  419. .El
  420. .El
  421. .Pp
  422. .Fn crypto_getreq
  423. allocates a
  424. .Vt cryptop
  425. structure with a linked list of as many
  426. .Vt cryptodesc
  427. structures as were specified in the argument passed to it.
  428. .Pp
  429. .Fn crypto_freereq
  430. deallocates a structure
  431. .Vt cryptop
  432. and any
  433. .Vt cryptodesc
  434. structures linked to it.
  435. Note that it is the responsibility of the
  436. callback routine to do the necessary cleanups associated with the
  437. opaque field in the
  438. .Vt cryptop
  439. structure.
  440. .Pp
  441. .Fn crypto_kdispatch
  442. is called to perform a keying operation.
  443. The various fields in the
  444. .Vt cryptkop
  445. structure are:
  446. .Bl -tag -width ".Va krp_callback"
  447. .It Va krp_op
  448. Operation code, such as
  449. .Dv CRK_MOD_EXP .
  450. .It Va krp_status
  451. Return code.
  452. This
  453. .Va errno Ns -style
  454. variable indicates whether lower level reasons
  455. for operation failure.
  456. .It Va krp_iparams
  457. Number if input parameters to the specified operation.
  458. Note that each operation has a (typically hardwired) number of such parameters.
  459. .It Va krp_oparams
  460. Number if output parameters from the specified operation.
  461. Note that each operation has a (typically hardwired) number of such parameters.
  462. .It Va krp_kvp
  463. An array of kernel memory blocks containing the parameters.
  464. .It Va krp_hid
  465. Identifier specifying which low-level driver is being used.
  466. .It Va krp_callback
  467. Callback called on completion of a keying operation.
  468. .El
  469. .Sh DRIVER-SIDE API
  470. The
  471. .Fn crypto_get_driverid ,
  472. .Fn crypto_register ,
  473. .Fn crypto_kregister ,
  474. .Fn crypto_unregister ,
  475. .Fn crypto_unblock ,
  476. and
  477. .Fn crypto_done
  478. routines are used by drivers that provide support for cryptographic
  479. primitives to register and unregister with the kernel crypto services
  480. framework.
  481. Drivers must first use the
  482. .Fn crypto_get_driverid
  483. function to acquire a driver identifier, specifying the
  484. .Fa cc_flags
  485. as an argument (normally 0, but software-only drivers should specify
  486. .Dv CRYPTOCAP_F_SOFTWARE ) .
  487. For each algorithm the driver supports, it must then call
  488. .Fn crypto_register .
  489. The first two arguments are the driver and algorithm identifiers.
  490. The next two arguments specify the largest possible operator length (in bits,
  491. important for public key operations) and flags for this algorithm.
  492. The last four arguments must be provided in the first call to
  493. .Fn crypto_register
  494. and are ignored in all subsequent calls.
  495. They are pointers to three
  496. driver-provided functions that the framework may call to establish new
  497. cryptographic context with the driver, free already established
  498. context, and ask for a request to be processed (encrypt, decrypt,
  499. etc.); and an opaque parameter to pass when calling each of these routines.
  500. .Fn crypto_unregister
  501. is called by drivers that wish to withdraw support for an algorithm.
  502. The two arguments are the driver and algorithm identifiers, respectively.
  503. Typically, drivers for
  504. PCMCIA
  505. crypto cards that are being ejected will invoke this routine for all
  506. algorithms supported by the card.
  507. .Fn crypto_unregister_all
  508. will unregister all algorithms registered by a driver
  509. and the driver will be disabled (no new sessions will be allocated on
  510. that driver, and any existing sessions will be migrated to other
  511. drivers).
  512. The same will be done if all algorithms associated with a driver are
  513. unregistered one by one.
  514. .Pp
  515. The calling convention for the three driver-supplied routines is:
  516. .Pp
  517. .Bl -item -compact
  518. .It
  519. .Ft int
  520. .Fn \*[lp]*newsession\*[rp] "void *" "uint32_t *" "struct cryptoini *" ;
  521. .It
  522. .Ft int
  523. .Fn \*[lp]*freesession\*[rp] "void *" "uint64_t" ;
  524. .It
  525. .Ft int
  526. .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
  527. .It
  528. .Ft int
  529. .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
  530. .El
  531. .Pp
  532. On invocation, the first argument to
  533. all routines is an opaque data value supplied when the algorithm
  534. is registered with
  535. .Fn crypto_register .
  536. The second argument to
  537. .Fn newsession
  538. contains the driver identifier obtained via
  539. .Fn crypto_get_driverid .
  540. On successful return, it should contain a driver-specific session
  541. identifier.
  542. The third argument is identical to that of
  543. .Fn crypto_newsession .
  544. .Pp
  545. The
  546. .Fn freesession
  547. routine takes as arguments the opaque data value and the SID
  548. (which is the concatenation of the
  549. driver identifier and the driver-specific session identifier).
  550. It should clear any context associated with the session (clear hardware
  551. registers, memory, etc.).
  552. .Pp
  553. The
  554. .Fn process
  555. routine is invoked with a request to perform crypto processing.
  556. This routine must not block, but should queue the request and return
  557. immediately.
  558. Upon processing the request, the callback routine should be invoked.
  559. In case of an unrecoverable error, the error indication must be placed in the
  560. .Va crp_etype
  561. field of the
  562. .Vt cryptop
  563. structure.
  564. When the request is completed, or an error is detected, the
  565. .Fn process
  566. routine should invoke
  567. .Fn crypto_done .
  568. Session migration may be performed, as mentioned previously.
  569. .Pp
  570. In case of a temporary resource exhaustion, the
  571. .Fn process
  572. routine may return
  573. .Er ERESTART
  574. in which case the crypto services will requeue the request, mark the driver
  575. as
  576. .Dq blocked ,
  577. and stop submitting requests for processing.
  578. The driver is then responsible for notifying the crypto services
  579. when it is again able to process requests through the
  580. .Fn crypto_unblock
  581. routine.
  582. This simple flow control mechanism should only be used for short-lived
  583. resource exhaustion as it causes operations to be queued in the crypto
  584. layer.
  585. Doing so is preferable to returning an error in such cases as
  586. it can cause network protocols to degrade performance by treating the
  587. failure much like a lost packet.
  588. .Pp
  589. The
  590. .Fn kprocess
  591. routine is invoked with a request to perform crypto key processing.
  592. This routine must not block, but should queue the request and return
  593. immediately.
  594. Upon processing the request, the callback routine should be invoked.
  595. In case of an unrecoverable error, the error indication must be placed in the
  596. .Va krp_status
  597. field of the
  598. .Vt cryptkop
  599. structure.
  600. When the request is completed, or an error is detected, the
  601. .Fn kprocess
  602. routine should invoked
  603. .Fn crypto_kdone .
  604. .Sh RETURN VALUES
  605. .Fn crypto_register ,
  606. .Fn crypto_kregister ,
  607. .Fn crypto_unregister ,
  608. .Fn crypto_newsession ,
  609. .Fn crypto_freesession ,
  610. and
  611. .Fn crypto_unblock
  612. return 0 on success, or an error code on failure.
  613. .Fn crypto_get_driverid
  614. returns a non-negative value on error, and \-1 on failure.
  615. .Fn crypto_getreq
  616. returns a pointer to a
  617. .Vt cryptop
  618. structure and
  619. .Dv NULL
  620. on failure.
  621. .Fn crypto_dispatch
  622. returns
  623. .Er EINVAL
  624. if its argument or the callback function was
  625. .Dv NULL ,
  626. and 0 otherwise.
  627. The callback is provided with an error code in case of failure, in the
  628. .Va crp_etype
  629. field.
  630. .Sh FILES
  631. .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
  632. .It Pa sys/opencrypto/crypto.c
  633. most of the framework code
  634. .El
  635. .Sh SEE ALSO
  636. .Xr ipsec 4 ,
  637. .Xr malloc 9 ,
  638. .Xr sleep 9
  639. .Sh HISTORY
  640. The cryptographic framework first appeared in
  641. .Ox 2.7
  642. and was written by
  643. .An "Angelos D. Keromytis" Aq angelos@openbsd.org .
  644. .Sh BUGS
  645. The framework currently assumes that all the algorithms in a
  646. .Fn crypto_newsession
  647. operation must be available by the same driver.
  648. If that is not the case, session initialization will fail.
  649. .Pp
  650. The framework also needs a mechanism for determining which driver is
  651. best for a specific set of algorithms associated with a session.
  652. Some type of benchmarking is in order here.
  653. .Pp
  654. Multiple instances of the same algorithm in the same session are not
  655. supported.
  656. Note that 3DES is considered one algorithm (and not three
  657. instances of DES).
  658. Thus, 3DES and DES could be mixed in the same request.