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 July 2, 2015
  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 When the flag
 337 .Dv CRD_F_IV_EXPLICIT
 338 is set, this field contains the IV.
 339 .It Va crd_key
 340 When the
 341 .Dv CRD_F_KEY_EXPLICIT
 342 flag is set, 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 .\" This flag name has nothing to do w/ it's behavior, fix the name.
 374 For encryption, if this bit is not set the IV used to encrypt the packet
 375 will be written at the location pointed to by
 376 .Va crd_inject .
 377 The IV length is assumed to be equal to the blocksize of the
 378 encryption algorithm.
 379 For encryption, if this bit is set, nothing is done.
 380 For decryption, this flag has no meaning.
 381 Applications that do special
 382 .Dq "IV cooking" ,
 383 such as the half-IV mode in
 384 .Xr ipsec 4 ,
 385 can use this flag to indicate that the IV should not be written on the packet.
 386 This flag is typically used in conjunction with the
 387 .Dv CRD_F_IV_EXPLICIT
 388 flag.
 389 .It Dv CRD_F_IV_EXPLICIT
 390 This bit is set when the IV is explicitly
 391 provided by the consumer in the
 392 .Va crd_iv
 393 field.
 394 Otherwise, for encryption operations the IV is provided for by
 395 the driver used to perform the operation, whereas for decryption
 396 operations it is pointed to by the
 397 .Va crd_inject
 398 field.
 399 This flag is typically used when the IV is calculated
 400 .Dq "on the fly"
 401 by the consumer, and does not precede the data (some
 402 .Xr ipsec 4
 403 configurations, and the encrypted swap are two such examples).
 404 .It Dv CRD_F_KEY_EXPLICIT
 405 For encryption and authentication (MAC) algorithms, this bit is set when the key
 406 is explicitly provided by the consumer in the
 407 .Va crd_key
 408 field for the given operation.
 409 Otherwise, the key is taken at newsession time from the
 410 .Va cri_key
 411 field.
 412 As calculating the key schedule may take a while, it is recommended that often
 413 used keys are given their own session.
 414 .It Dv CRD_F_COMP
 415 For compression algorithms, this bit is set when compression is required (when
 416 not set, decompression is performed).
 417 .El
 418 .It Va CRD_INI
 419 This
 420 .Vt cryptoini
 421 structure will not be modified by the framework or the device drivers.
 422 Since this information accompanies every cryptographic
 423 operation request, drivers may re-initialize state on-demand
 424 (typically an expensive operation).
 425 Furthermore, the cryptographic
 426 framework may re-route requests as a result of full queues or hardware
 427 failure, as described above.
 428 .It Va crd_next
 429 Point to the next descriptor.
 430 Linked operations are useful in protocols such as
 431 .Xr ipsec 4 ,
 432 where multiple cryptographic transforms may be applied on the same
 433 block of data.
 434 .El
 435 .El
 436 .Pp
 437 .Fn crypto_getreq
 438 allocates a
 439 .Vt cryptop
 440 structure with a linked list of as many
 441 .Vt cryptodesc
 442 structures as were specified in the argument passed to it.
 443 .Pp
 444 .Fn crypto_freereq
 445 deallocates a structure
 446 .Vt cryptop
 447 and any
 448 .Vt cryptodesc
 449 structures linked to it.
 450 Note that it is the responsibility of the
 451 callback routine to do the necessary cleanups associated with the
 452 opaque field in the
 453 .Vt cryptop
 454 structure.
 455 .Pp
 456 .Fn crypto_kdispatch
 457 is called to perform a keying operation.
 458 The various fields in the
 459 .Vt cryptkop
 460 structure are:
 461 .Bl -tag -width ".Va krp_callback"
 462 .It Va krp_op
 463 Operation code, such as
 464 .Dv CRK_MOD_EXP .
 465 .It Va krp_status
 466 Return code.
 467 This
 468 .Va errno Ns -style
 469 variable indicates whether lower level reasons
 470 for operation failure.
 471 .It Va krp_iparams
 472 Number if input parameters to the specified operation.
 473 Note that each operation has a (typically hardwired) number of such parameters.
 474 .It Va krp_oparams
 475 Number if output parameters from the specified operation.
 476 Note that each operation has a (typically hardwired) number of such parameters.
 477 .It Va krp_kvp
 478 An array of kernel memory blocks containing the parameters.
 479 .It Va krp_hid
 480 Identifier specifying which low-level driver is being used.
 481 .It Va krp_callback
 482 Callback called on completion of a keying operation.
 483 .El
 484 .Sh DRIVER-SIDE API
 485 The
 486 .Fn crypto_get_driverid ,
 487 .Fn crypto_register ,
 488 .Fn crypto_kregister ,
 489 .Fn crypto_unregister ,
 490 .Fn crypto_unblock ,
 491 and
 492 .Fn crypto_done
 493 routines are used by drivers that provide support for cryptographic
 494 primitives to register and unregister with the kernel crypto services
 495 framework.
 496 Drivers must first use the
 497 .Fn crypto_get_driverid
 498 function to acquire a driver identifier, specifying the
 499 .Fa cc_flags
 500 as an argument (normally 0, but software-only drivers should specify
 501 .Dv CRYPTOCAP_F_SOFTWARE ) .
 502 For each algorithm the driver supports, it must then call
 503 .Fn crypto_register .
 504 The first two arguments are the driver and algorithm identifiers.
 505 The next two arguments specify the largest possible operator length (in bits,
 506 important for public key operations) and flags for this algorithm.
 507 The last four arguments must be provided in the first call to
 508 .Fn crypto_register
 509 and are ignored in all subsequent calls.
 510 They are pointers to three
 511 driver-provided functions that the framework may call to establish new
 512 cryptographic context with the driver, free already established
 513 context, and ask for a request to be processed (encrypt, decrypt,
 514 etc.); and an opaque parameter to pass when calling each of these routines.
 515 .Fn crypto_unregister
 516 is called by drivers that wish to withdraw support for an algorithm.
 517 The two arguments are the driver and algorithm identifiers, respectively.
 518 Typically, drivers for
 519 PCMCIA
 520 crypto cards that are being ejected will invoke this routine for all
 521 algorithms supported by the card.
 522 .Fn crypto_unregister_all
 523 will unregister all algorithms registered by a driver
 524 and the driver will be disabled (no new sessions will be allocated on
 525 that driver, and any existing sessions will be migrated to other
 526 drivers).
 527 The same will be done if all algorithms associated with a driver are
 528 unregistered one by one.
 529 .Pp
 530 The calling convention for the three driver-supplied routines is:
 531 .Pp
 532 .Bl -item -compact
 533 .It
 534 .Ft int
 535 .Fn \*[lp]*newsession\*[rp] "void *" "uint32_t *" "struct cryptoini *" ;
 536 .It
 537 .Ft int
 538 .Fn \*[lp]*freesession\*[rp] "void *" "uint64_t" ;
 539 .It
 540 .Ft int
 541 .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
 542 .It
 543 .Ft int
 544 .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
 545 .El
 546 .Pp
 547 On invocation, the first argument to
 548 all routines is an opaque data value supplied when the algorithm
 549 is registered with
 550 .Fn crypto_register .
 551 The second argument to
 552 .Fn newsession
 553 contains the driver identifier obtained via
 554 .Fn crypto_get_driverid .
 555 On successful return, it should contain a driver-specific session
 556 identifier.
 557 The third argument is identical to that of
 558 .Fn crypto_newsession .
 559 .Pp
 560 The
 561 .Fn freesession
 562 routine takes as arguments the opaque data value and the SID
 563 (which is the concatenation of the
 564 driver identifier and the driver-specific session identifier).
 565 It should clear any context associated with the session (clear hardware
 566 registers, memory, etc.).
 567 .Pp
 568 The
 569 .Fn process
 570 routine is invoked with a request to perform crypto processing.
 571 This routine must not block, but should queue the request and return
 572 immediately.
 573 Upon processing the request, the callback routine should be invoked.
 574 In case of an unrecoverable error, the error indication must be placed in the
 575 .Va crp_etype
 576 field of the
 577 .Vt cryptop
 578 structure.
 579 When the request is completed, or an error is detected, the
 580 .Fn process
 581 routine should invoke
 582 .Fn crypto_done .
 583 Session migration may be performed, as mentioned previously.
 584 .Pp
 585 In case of a temporary resource exhaustion, the
 586 .Fn process
 587 routine may return
 588 .Er ERESTART
 589 in which case the crypto services will requeue the request, mark the driver
 590 as
 591 .Dq blocked ,
 592 and stop submitting requests for processing.
 593 The driver is then responsible for notifying the crypto services
 594 when it is again able to process requests through the
 595 .Fn crypto_unblock
 596 routine.
 597 This simple flow control mechanism should only be used for short-lived
 598 resource exhaustion as it causes operations to be queued in the crypto
 599 layer.
 600 Doing so is preferable to returning an error in such cases as
 601 it can cause network protocols to degrade performance by treating the
 602 failure much like a lost packet.
 603 .Pp
 604 The
 605 .Fn kprocess
 606 routine is invoked with a request to perform crypto key processing.
 607 This routine must not block, but should queue the request and return
 608 immediately.
 609 Upon processing the request, the callback routine should be invoked.
 610 In case of an unrecoverable error, the error indication must be placed in the
 611 .Va krp_status
 612 field of the
 613 .Vt cryptkop
 614 structure.
 615 When the request is completed, or an error is detected, the
 616 .Fn kprocess
 617 routine should invoked
 618 .Fn crypto_kdone .
 619 .Sh RETURN VALUES
 620 .Fn crypto_register ,
 621 .Fn crypto_kregister ,
 622 .Fn crypto_unregister ,
 623 .Fn crypto_newsession ,
 624 .Fn crypto_freesession ,
 625 and
 626 .Fn crypto_unblock
 627 return 0 on success, or an error code on failure.
 628 .Fn crypto_get_driverid
 629 returns a non-negative value on error, and \-1 on failure.
 630 .Fn crypto_getreq
 631 returns a pointer to a
 632 .Vt cryptop
 633 structure and
 634 .Dv NULL
 635 on failure.
 636 .Fn crypto_dispatch
 637 returns
 638 .Er EINVAL
 639 if its argument or the callback function was
 640 .Dv NULL ,
 641 and 0 otherwise.
 642 The callback is provided with an error code in case of failure, in the
 643 .Va crp_etype
 644 field.
 645 .Sh FILES
 646 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
 647 .It Pa sys/opencrypto/crypto.c
 648 most of the framework code
 649 .El
 650 .Sh SEE ALSO
 651 .Xr crypto 4 ,
 652 .Xr ipsec 4 ,
 653 .Xr crypto 7 ,
 654 .Xr malloc 9 ,
 655 .Xr sleep 9
 656 .Sh HISTORY
 657 The cryptographic framework first appeared in
 658 .Ox 2.7
 659 and was written by
 660 .An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
 661 .Sh BUGS
 662 The framework currently assumes that all the algorithms in a
 663 .Fn crypto_newsession
 664 operation must be available by the same driver.
 665 If that is not the case, session initialization will fail.
 666 .Pp
 667 The framework also needs a mechanism for determining which driver is
 668 best for a specific set of algorithms associated with a session.
 669 Some type of benchmarking is in order here.
 670 .Pp
 671 Multiple instances of the same algorithm in the same session are not
 672 supported.
 673 Note that 3DES is considered one algorithm (and not three
 674 instances of DES).
 675 Thus, 3DES and DES could be mixed in the same request.