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