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