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