share/man/man9/crypto.9

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