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