1 CRYPTOADM(1M) Maintenance Commands CRYPTOADM(1M) 2 3 4 5 NAME 6 cryptoadm - cryptographic framework administration 7 8 SYNOPSIS 9 cryptoadm list [-mpv] [provider=provider-name] 10 [mechanism=mechanism-list] 11 12 13 cryptoadm disable 14 provider=provider-name mechanism=mechanism-list | random | all 15 16 17 cryptoadm enable 18 provider=provider-name mechanism=mechanism-list | random | all 19 20 21 cryptoadm install provider=provider-name 22 23 24 cryptoadm install provider=provider-name 25 [mechanism=mechanism-list] 26 27 28 cryptoadm uninstall provider=provider-name 29 30 31 cryptoadm unload provider=provider-name 32 33 34 cryptoadm disable fips-140 35 36 37 cryptoadm enable fips-140 38 39 40 cryptoadm list fips-140 41 42 43 cryptoadm refresh 44 45 46 cryptoadm start 47 48 49 cryptoadm stop 50 51 52 cryptoadm --help 53 54 55 DESCRIPTION 56 The cryptoadm utility displays cryptographic provider information for a 57 system, configures the mechanism policy for each provider, and installs 58 or uninstalls a cryptographic provider. The cryptographic framework 59 supports three types of providers: a user-level provider (a PKCS11 60 shared library), a kernel software provider (a loadable kernel software 61 module), and a kernel hardware provider (a cryptographic hardware 62 device). 63 64 65 For kernel software providers, the cryptoadm utility provides the 66 unload subcommand. This subcommand instructs the kernel to unload a 67 kernel software providers. 68 69 70 For the cryptographic framework's metaslot, the cryptoadm utility 71 provides subcommands to enable and disable the metaslot's features, 72 list metaslot's configuration, specify alternate persistent object 73 storage, and configure the metaslot's mechanism policy. 74 75 76 The cryptoadm utility provides subcommands to enable and disable 77 FIPS-140 mode in the Cryptographic Framework. It also provides a list 78 subcommand to display the current status of FIPS-140 mode. 79 80 81 Administrators will find it useful to use syslog facilities (see 82 syslogd(1M) and logadm(1M)) to maintain the cryptographic subsystem. 83 Logging can be especially useful under the following circumstances: 84 85 o If kernel-level daemon is dead, all applications fail. You 86 can learn this from syslog and use svcadm(1M) to restart the 87 svc:/system/cryptosvc service. 88 89 o If there are bad providers plugged into the framework, you 90 can learn this from syslog and remove the bad providers from 91 the framework. 92 93 94 With the exception of the subcommands or options listed below, the 95 cryptoadm command needs to be run by a privileged user. 96 97 o subcommand list, any options 98 99 o subcommand --help 100 101 OPTIONS 102 The cryptoadm utility has the various combinations of subcommands and 103 options shown below. 104 105 cryptoadm list 106 107 Display the list of installed providers. 108 109 110 cryptoadm list metaslot 111 112 Display the system-wide configuration for metaslot. 113 114 115 cryptoadm list -m [ provider=provider-name | metaslot ] 116 117 Display a list of mechanisms that can be used with the installed 118 providers or metaslot. If a provider is specified, display the name 119 of the specified provider and the mechanism list that can be used 120 with that provider. If the metaslot keyword is specified, display 121 the list of mechanisms that can be used with metaslot. 122 123 124 cryptoadm list -p [ provider=provider-name | metaslot ] 125 126 Display the mechanism policy (that is, which mechanisms are 127 available and which are not) for the installed providers. Also 128 display the provider feature policy or metaslot. If a provider is 129 specified, display the name of the provider with the mechanism 130 policy enforced on it only. If the metaslot keyword is specified, 131 display the mechanism policy enforced on the metaslot. 132 133 134 cryptoadm list -v provider=provider-name | metaslot 135 136 Display details about the specified provider if a provider is 137 specified. If the metaslot keyword is specified, display details 138 about the metaslot. 139 140 141 -v 142 143 For the various list subcommands described above (except for list 144 -p), the -v (verbose) option provides details about providers, 145 mechanisms and slots. 146 147 148 cryptoadm disable provider=provider-name 149 [ mechanism=mechanism-list | provider-feature ... | all ] 150 151 Disable the mechanisms or provider features specified for the 152 provider. See OPERANDS for a description of mechanism, provider- 153 feature, and the all keyword. 154 155 156 cryptoadm [ mechanism=mechanism-list ] [ auto-key-migrate ] 157 158 Disable the metaslot feature in the cryptographic framework or 159 disable some of metaslot's features. If no operand is specified, 160 this command disables the metaslot feature in the cryptographic 161 framework. If a list of mechanisms is specified, disable mechanisms 162 specified for metaslot. If all mechanisms are disabled for 163 metaslot, the metaslot will be disabled. See OPERANDS for a 164 description of mechanism. If the auto-key-migrate keyword is 165 specified, it disables the migration of sensitive token objects to 166 other slots even if it is necessary for performing crypto 167 operations. See OPERANDS for a description of auto-key-migrate. 168 169 170 cryptoadm enable provider=provider-name 171 [ mechanism=mechanism-list | provider-feature ... | all ] 172 173 Enable the mechanisms or provider features specified for the 174 provider. See OPERANDS for a description of mechanism, provider- 175 feature, and the all keyword. 176 177 178 cryptoadm enable metaslot [ mechanism=mechanism-list ] | 179 [ [ token=token-label] [ slot=slot-description] | 180 default-keystore ] | [ auto-key-migrate ] 181 182 If no operand is specified, this command enables the metaslot 183 feature in the cryptographic framework. If a list of mechanisms is 184 specified, it enables only the list of specified mechanisms for 185 metaslot. If token-label is specified, the specified token will be 186 used as the persistent object store. If the slot-description is 187 specified, the specified slot will be used as the persistent object 188 store. If both the token-label and the slot-description are 189 specified, the provider with the matching token label and slot 190 description is used as the persistent object store. If the default- 191 keystore keyword is specified, metaslot will use the default 192 persistent object store. If the auto-key-migrate keyword is 193 specified, sensitive token objects will automatically migrate to 194 other slots as needed to complete certain crypto operations. See 195 OPERANDS for a description of mechanism, token, slot, default- 196 keystore, and auto-key-migrate. 197 198 199 cryptoadm install provider=provider-name 200 201 Install a user-level provider into the system. The provider operand 202 must be an absolute pathname of the corresponding shared library. 203 If there are both 32-bit and 64-bit versions for a library, this 204 command should be run once only with the path name containing $ISA. 205 Note that $ISA is not a reference to an environment variable. Note 206 also that $ISA must be quoted (with single quotes [for example, 207 '$ISA']) or the $ must be escaped to keep it from being incorrectly 208 expanded by the shell. The user-level framework expands $ISA to an 209 empty string or an architecture-specific directory, for example, 210 sparcv9. 211 212 The preferred way of installing a user-level provider is to build a 213 package for the provider. For more information, see the Solaris 214 Security for Developer's Guide. 215 216 217 cryptoadm install provider=provider-name 218 mechanism=mechanism-list 219 220 Install a kernel software provider into the system. The provider 221 should contain the base name only. The mechanism-list operand 222 specifies the complete list of mechanisms to be supported by this 223 provider. 224 225 The preferred way of installing a kernel software provider is to 226 build a package for providers. For more information, see the 227 Solaris Security for Developer's Guide. 228 229 230 cryptoadm uninstall provider=provider-name 231 232 Uninstall the specified provider and the associated mechanism 233 policy from the system. This subcommand applies only to a user- 234 level provider or a kernel software provider. 235 236 237 cryptoadm unload provider=provider-name 238 239 Unload the kernel software module specified by provider. 240 241 242 cryptoadm disable fips-140 243 244 Disable FIPS-140 mode in the Cryptographic Framework. 245 246 247 cryptoadm enable fips-140 248 249 Enable FIPS-140 mode in the Cryptographic Framework. This 250 subcommand does not disable the non-FIPS approved algorithms from 251 the user-level pkcs11_softtoken library and the kernel software 252 providers. It is the consumers of the framework that are 253 responsible for using only FIPS-approved algorithms. 254 255 Upon completion of this subcommand, a message is issued to inform 256 the administrator that any plugins added that are not within the 257 boundary might invalidate FIPS compliance and to check the Security 258 Policies for those plugins. In addition, a warning message is 259 issued to indicate that, in this release, the Cryptographic 260 Framework has not been FIPS 140-2 certified. 261 262 The system will require a reboot to perform Power-Up Self Tests 263 that include a cryptographic algorithm test and a software 264 integrity test. 265 266 267 cryptoadm list fips-140 268 269 Display the current setting of FIPS-140 mode in the Cryptographic 270 Framework. The status of FIPS-140 mode is enabled or disabled. The 271 default FIPS-140 mode is disabled. 272 273 274 cryptoadm refresh 275 cryptoadm start 276 cryptoadm stop 277 278 Private interfaces for use by smf(5), these must not be used 279 directly. 280 281 282 cryptoadm -help 283 284 Display the command usage. 285 286 287 OPERANDS 288 provider=provider-name 289 290 A user-level provider (a PKCS11 shared library), a kernel software 291 provider (a loadable kernel software module), or a kernel hardware 292 provider (a cryptographic hardware device). 293 294 A valid value of the provider operand is one entry from the output 295 of a command of the form: cryptoadm list. A provider operand for a 296 user-level provider is an absolute pathname of the corresponding 297 shared library. A provider operand for a kernel software provider 298 contains a base name only. A provider operand for a kernel hardware 299 provider is in a "name/number" form. 300 301 302 mechanism=mechanism-list 303 304 A comma separated list of one or more PKCS #11 mechanisms. A 305 process for implementing a cryptographic operation as defined in 306 PKCS #11 specification. You can substitute all for mechanism-list, 307 to specify all mechanisms on a provider. See the discussion of the 308 all keyword, below. 309 310 311 provider-feature 312 313 A cryptographic framework feature for the given provider. Currently 314 only random is accepted as a feature. For a user-level provider, 315 disabling the random feature makes the PKCS #11 routines 316 C_GenerateRandom and C_SeedRandom unavailable from the provider. 317 For a kernel provider, disabling the random feature prevents 318 /dev/random from gathering random numbers from the provider. 319 320 321 all 322 323 The keyword all can be used with with the disable and enable 324 subcommands to operate on all provider features. 325 326 327 token=token-label 328 329 The label of a token in one of the providers in the cryptographic 330 framework. 331 332 A valid value of the token operand is an item displayed under 333 "Token Label" from the output of the command cryptoadm list -v. 334 335 336 slot=slot-description 337 338 The description of a slot in one of the providers in the 339 cryptographic framework. 340 341 A valid value of the slot operand is an item displayed under 342 "Description" from the output of the command cryptoadm list -v. 343 344 345 default-keystore 346 347 The keyword default-keystore is valid only for metaslot. Specify 348 this keyword to set the persistent object store for metaslot back 349 to using the default store. 350 351 352 auto-key-migrate 353 354 The keyword auto-key-migrate is valid only for metaslot. Specify 355 this keyword to configure whether metaslot is allowed to move 356 sensitive token objects from the token object slot to other slots 357 for performing cryptographic operations. 358 359 360 361 The keyword all can be used in two ways with the disable and enable 362 subcommands: 363 364 o You can substitute all for mechanism=mechanism-list, as in: 365 366 # cryptoadm enable provider=dca/0 all 367 368 369 This command enables the mechanisms on the provider and any 370 other provider-features, such as random. 371 372 # cryptoadm enable provider=des mechanism=all 373 374 375 376 o You can also use all as an argument to mechanism, as in: 377 378 # cryptoadm enable provider=des mechanism=all 379 380 381 ...which enables all mechanisms on the provider, but enables 382 no other provider-features, such as random. 383 384 EXAMPLES 385 Example 1 Display List of Providers Installed in System 386 387 388 The following command displays a list of all installed providers: 389 390 391 example% cryptoadm list 392 user-level providers: 393 /usr/lib/security/$ISA/pkcs11_kernel.so 394 /usr/lib/security/$ISA/pkcs11_softtoken.so 395 /opt/lib/libcryptoki.so.1 396 /opt/SUNWconn/lib/$ISA/libpkcs11.so.1 397 398 kernel software providers: 399 des 400 aes 401 bfish 402 sha1 403 md5 404 405 kernel hardware providers: 406 dca/0 407 408 409 410 Example 2 Display Mechanism List for md5 Provider 411 412 413 The following command is a variation of the list subcommand: 414 415 416 example% cryptoadm list -m provider=md5 417 md5: CKM_MD5,CKM_MD5_HMAC,CKM_MD5_HMAC_GENERAL 418 419 420 421 Example 3 Disable Specific Mechanisms for Kernel Software Provider 422 423 424 The following command disables mechanisms CKM_DES3_ECB and CKM_DES3_CBC 425 for the kernel software provider des: 426 427 428 example# cryptoadm disable provider=des 429 430 431 432 Example 4 Display Mechanism Policy for a Provider 433 434 435 The following command displays the mechanism policy for the des 436 provider: 437 438 439 example% cryptoadm list -p provider=des 440 des: All mechanisms are enabled, except CKM_DES3_ECB, CKM_DES3_CBC 441 442 443 444 Example 5 Enable Specific Mechanism for a Provider 445 446 447 The following command enables the CKM_DES3_ECB mechanism for the kernel 448 software provider des: 449 450 451 example# cryptoadm enable provider=des mechanism=CKM_DES3_ECB 452 453 454 455 Example 6 Install User-Level Provider 456 457 458 The following command installs a user-level provider: 459 460 461 example# cryptoadm install provider=/opt/lib/libcryptoki.so.1 462 463 464 465 Example 7 Install User-Level Provider That Contains 32- and 64-bit 466 Versions 467 468 469 The following command installs a user-level provider that contains both 470 32-bit and 64-bit versions: 471 472 473 example# cryptoadm install \ 474 provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1 475 476 477 478 Example 8 Uninstall a Provider 479 480 481 The following command uninstalls the md5 provider: 482 483 484 example# cryptoadm uninstall provider=md5 485 486 487 488 Example 9 Disable metaslot 489 490 491 The following command disables the metaslot feature in the 492 cryptographic framework. 493 494 495 example# cryptoadm disable metaslot 496 497 498 499 Example 10 Specify metaslot to Use Specified Token as Persistent Object 500 Store 501 502 503 The following command specifies that metaslot use the Venus token as 504 the persistent object store. 505 506 507 example# cryptoadm enable metaslot token="SUNW,venus" 508 509 510 511 EXIT STATUS 512 The following exit values are returned: 513 514 0 515 516 Successful completion. 517 518 519 >0 520 521 An error occurred. 522 523 524 ATTRIBUTES 525 See attributes(5) for descriptions of the following attributes: 526 527 528 529 530 +--------------------+-----------------+ 531 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 532 +--------------------+-----------------+ 533 |Interface Stability | See below | 534 +--------------------+-----------------+ 535 536 537 The start, stop, and refresh options are Private interfaces. All other 538 options are Evolving. The utility name is Stable. 539 540 SEE ALSO 541 logadm(1M), svcadm(1M), syslogd(1M), libpkcs11(3LIB), exec_attr(4), 542 prof_attr(4), attributes(5), smf(5), random(7D) 543 544 545 546 Solaris Security for Developer's Guide 547 548 NOTES 549 If a hardware provider's policy was made explicitly (that is, some of 550 its mechanisms were disabled) and the hardware provider has been 551 detached, the policy of this hardware provider is still listed. 552 553 554 cryptoadm assumes that, minimally, a 32-bit shared object is delivered 555 for each user-level provider. If both a 32-bit and 64-bit shared object 556 are delivered, the two versions must provide the same functionality. 557 The same mechanism policy applies to both. 558 559 560 561 September 1, 2009 CRYPTOADM(1M)