CRYPTOADM(8) Maintenance Commands and Procedures CRYPTOADM(8)

NAME

cryptoadm - cryptographic framework administration

SYNOPSIS

cryptoadm list [-mpv] [provider=provider-name]
[mechanism=mechanism-list]


cryptoadm disable
provider=provider-name mechanism=mechanism-list | random | all


cryptoadm enable
provider=provider-name mechanism=mechanism-list | random | all


cryptoadm install provider=provider-name


cryptoadm install provider=provider-name
[mechanism=mechanism-list]


cryptoadm uninstall provider=provider-name


cryptoadm unload provider=provider-name


cryptoadm disable fips-140


cryptoadm enable fips-140


cryptoadm list fips-140


cryptoadm refresh


cryptoadm start


cryptoadm stop


cryptoadm --help

DESCRIPTION

The cryptoadm utility displays cryptographic provider information for
a system, configures the mechanism policy for each provider, and
installs or uninstalls a cryptographic provider. The cryptographic
framework supports three types of providers: a user-level provider (a
PKCS11 shared library), a kernel software provider (a loadable kernel
software module), and a kernel hardware provider (a cryptographic
hardware device).


For kernel software providers, the cryptoadm utility provides the
unload subcommand. This subcommand instructs the kernel to unload a
kernel software providers.


For the cryptographic framework's metaslot, the cryptoadm utility
provides subcommands to enable and disable the metaslot's features,
list metaslot's configuration, specify alternate persistent object
storage, and configure the metaslot's mechanism policy.


The cryptoadm utility provides subcommands to enable and disable
FIPS-140 mode in the Cryptographic Framework. It also provides a list
subcommand to display the current status of FIPS-140 mode.


Administrators will find it useful to use syslog facilities (see
syslogd(8) and logadm(8)) to maintain the cryptographic subsystem.
Logging can be especially useful under the following circumstances:

o If kernel-level daemon is dead, all applications fail. You
can learn this from syslog and use svcadm(8) to restart
the svc:/system/cryptosvc service.

o If there are bad providers plugged into the framework, you
can learn this from syslog and remove the bad providers
from the framework.


With the exception of the subcommands or options listed below, the
cryptoadm command needs to be run by a privileged user.

o subcommand list, any options

o subcommand --help

OPTIONS

The cryptoadm utility has the various combinations of subcommands and
options shown below.

cryptoadm list

Display the list of installed providers.


cryptoadm list metaslot

Display the system-wide configuration for metaslot.


cryptoadm list -m [ provider=provider-name | metaslot ]

Display a list of mechanisms that can be used with the installed
providers or metaslot. If a provider is specified, display the
name of the specified provider and the mechanism list that can be
used with that provider. If the metaslot keyword is specified,
display the list of mechanisms that can be used with metaslot.


cryptoadm list -p [ provider=provider-name | metaslot ]

Display the mechanism policy (that is, which mechanisms are
available and which are not) for the installed providers. Also
display the provider feature policy or metaslot. If a provider is
specified, display the name of the provider with the mechanism
policy enforced on it only. If the metaslot keyword is specified,
display the mechanism policy enforced on the metaslot.


cryptoadm list -v provider=provider-name | metaslot

Display details about the specified provider if a provider is
specified. If the metaslot keyword is specified, display details
about the metaslot.


-v

For the various list subcommands described above (except for list
-p), the -v (verbose) option provides details about providers,
mechanisms and slots.


cryptoadm disable provider=provider-name
[ mechanism=mechanism-list | provider-feature ... | all ]

Disable the mechanisms or provider features specified for the
provider. See OPERANDS for a description of mechanism, provider-
feature, and the all keyword.


cryptoadm [ mechanism=mechanism-list ] [ auto-key-migrate ]

Disable the metaslot feature in the cryptographic framework or
disable some of metaslot's features. If no operand is specified,
this command disables the metaslot feature in the cryptographic
framework. If a list of mechanisms is specified, disable
mechanisms specified for metaslot. If all mechanisms are disabled
for metaslot, the metaslot will be disabled. See OPERANDS for a
description of mechanism. If the auto-key-migrate keyword is
specified, it disables the migration of sensitive token objects
to other slots even if it is necessary for performing crypto
operations. See OPERANDS for a description of auto-key-migrate.


cryptoadm enable provider=provider-name
[ mechanism=mechanism-list | provider-feature ... | all ]

Enable the mechanisms or provider features specified for the
provider. See OPERANDS for a description of mechanism, provider-
feature, and the all keyword.


cryptoadm enable metaslot [ mechanism=mechanism-list ] |
[ [ token=token-label] [ slot=slot-description] |
default-keystore ] | [ auto-key-migrate ]

If no operand is specified, this command enables the metaslot
feature in the cryptographic framework. If a list of mechanisms
is specified, it enables only the list of specified mechanisms
for metaslot. If token-label is specified, the specified token
will be used as the persistent object store. If the slot-
description is specified, the specified slot will be used as the
persistent object store. If both the token-label and the slot-
description are specified, the provider with the matching token
label and slot description is used as the persistent object
store. If the default-keystore keyword is specified, metaslot
will use the default persistent object store. If the auto-key-
migrate keyword is specified, sensitive token objects will
automatically migrate to other slots as needed to complete
certain crypto operations. See OPERANDS for a description of
mechanism, token, slot, default-keystore, and auto-key-migrate.


cryptoadm install provider=provider-name

Install a user-level provider into the system. The provider
operand must be an absolute pathname of the corresponding shared
library. If there are both 32-bit and 64-bit versions for a
library, this command should be run once only with the path name
containing $ISA. Note that $ISA is not a reference to an
environment variable. Note also that $ISA must be quoted (with
single quotes [for example, '$ISA']) or the $ must be escaped to
keep it from being incorrectly expanded by the shell. The user-
level framework expands $ISA to an empty string or an
architecture-specific directory, for example, sparcv9.

The preferred way of installing a user-level provider is to build
a package for the provider. For more information, see the Solaris
Security for Developer's Guide.


cryptoadm install provider=provider-name
mechanism=mechanism-list

Install a kernel software provider into the system. The provider
should contain the base name only. The mechanism-list operand
specifies the complete list of mechanisms to be supported by this
provider.

The preferred way of installing a kernel software provider is to
build a package for providers. For more information, see the
Solaris Security for Developer's Guide.


cryptoadm uninstall provider=provider-name

Uninstall the specified provider and the associated mechanism
policy from the system. This subcommand applies only to a user-
level provider or a kernel software provider.


cryptoadm unload provider=provider-name

Unload the kernel software module specified by provider.


cryptoadm disable fips-140

Disable FIPS-140 mode in the Cryptographic Framework.


cryptoadm enable fips-140

Enable FIPS-140 mode in the Cryptographic Framework. This
subcommand does not disable the non-FIPS approved algorithms from
the user-level pkcs11_softtoken library and the kernel software
providers. It is the consumers of the framework that are
responsible for using only FIPS-approved algorithms.

Upon completion of this subcommand, a message is issued to inform
the administrator that any plugins added that are not within the
boundary might invalidate FIPS compliance and to check the
Security Policies for those plugins. In addition, a warning
message is issued to indicate that, in this release, the
Cryptographic Framework has not been FIPS 140-2 certified.

The system will require a reboot to perform Power-Up Self Tests
that include a cryptographic algorithm test and a software
integrity test.


cryptoadm list fips-140

Display the current setting of FIPS-140 mode in the Cryptographic
Framework. The status of FIPS-140 mode is enabled or disabled.
The default FIPS-140 mode is disabled.


cryptoadm refresh
cryptoadm start
cryptoadm stop

Private interfaces for use by smf(7), these must not be used
directly.


cryptoadm -help

Display the command usage.

OPERANDS

provider=provider-name

A user-level provider (a PKCS11 shared library), a kernel
software provider (a loadable kernel software module), or a
kernel hardware provider (a cryptographic hardware device).

A valid value of the provider operand is one entry from the
output of a command of the form: cryptoadm list. A provider
operand for a user-level provider is an absolute pathname of the
corresponding shared library. A provider operand for a kernel
software provider contains a base name only. A provider operand
for a kernel hardware provider is in a "name/number" form.


mechanism=mechanism-list

A comma separated list of one or more PKCS #11 mechanisms. A
process for implementing a cryptographic operation as defined in
PKCS #11 specification. You can substitute all for mechanism-
list, to specify all mechanisms on a provider. See the discussion
of the all keyword, below.


provider-feature

A cryptographic framework feature for the given provider.
Currently only random is accepted as a feature. For a user-level
provider, disabling the random feature makes the PKCS #11
routines C_GenerateRandom and C_SeedRandom unavailable from the
provider. For a kernel provider, disabling the random feature
prevents /dev/random from gathering random numbers from the
provider.


all

The keyword all can be used with with the disable and enable
subcommands to operate on all provider features.


token=token-label

The label of a token in one of the providers in the cryptographic
framework.

A valid value of the token operand is an item displayed under
"Token Label" from the output of the command cryptoadm list -v.


slot=slot-description

The description of a slot in one of the providers in the
cryptographic framework.

A valid value of the slot operand is an item displayed under
"Description" from the output of the command cryptoadm list -v.


default-keystore

The keyword default-keystore is valid only for metaslot. Specify
this keyword to set the persistent object store for metaslot back
to using the default store.


auto-key-migrate

The keyword auto-key-migrate is valid only for metaslot. Specify
this keyword to configure whether metaslot is allowed to move
sensitive token objects from the token object slot to other slots
for performing cryptographic operations.


The keyword all can be used in two ways with the disable and enable
subcommands:

o You can substitute all for mechanism=mechanism-list, as
in:

# cryptoadm enable provider=dca/0 all


This command enables the mechanisms on the provider and
any other provider-features, such as random.

# cryptoadm enable provider=des mechanism=all


o You can also use all as an argument to mechanism, as in:

# cryptoadm enable provider=des mechanism=all


...which enables all mechanisms on the provider, but
enables no other provider-features, such as random.

EXAMPLES

Example 1: Display List of Providers Installed in System

The following command displays a list of all installed providers:


example% cryptoadm list
user-level providers:
/usr/lib/security/$ISA/pkcs11_kernel.so
/usr/lib/security/$ISA/pkcs11_softtoken.so
/opt/lib/libcryptoki.so.1
/opt/SUNWconn/lib/$ISA/libpkcs11.so.1

kernel software providers:
des
aes
bfish
sha1
md5

kernel hardware providers:
dca/0

Example 2: Display Mechanism List for md5 Provider

The following command is a variation of the list subcommand:


example% cryptoadm list -m provider=md5
md5: CKM_MD5,CKM_MD5_HMAC,CKM_MD5_HMAC_GENERAL

Example 3: Disable Specific Mechanisms for Kernel Software Provider

The following command disables mechanisms CKM_DES3_ECB and
CKM_DES3_CBC for the kernel software provider des:


example# cryptoadm disable provider=des

Example 4: Display Mechanism Policy for a Provider

The following command displays the mechanism policy for the des
provider:


example% cryptoadm list -p provider=des
des: All mechanisms are enabled, except CKM_DES3_ECB, CKM_DES3_CBC

Example 5: Enable Specific Mechanism for a Provider

The following command enables the CKM_DES3_ECB mechanism for the
kernel software provider des:


example# cryptoadm enable provider=des mechanism=CKM_DES3_ECB

Example 6: Install User-Level Provider

The following command installs a user-level provider:


example# cryptoadm install provider=/opt/lib/libcryptoki.so.1

Example 7: Install User-Level Provider That Contains 32- and 64-bit

Versions


The following command installs a user-level provider that contains
both 32-bit and 64-bit versions:


example# cryptoadm install \
provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1

Example 8: Uninstall a Provider

The following command uninstalls the md5 provider:


example# cryptoadm uninstall provider=md5

Example 9: Disable metaslot

The following command disables the metaslot feature in the
cryptographic framework.


example# cryptoadm disable metaslot

Example 10: Specify metaslot to Use Specified Token as Persistent

Object Store


The following command specifies that metaslot use the Venus token as
the persistent object store.


example# cryptoadm enable metaslot token="SUNW,venus"

EXIT STATUS

The following exit values are returned:

0

Successful completion.


>0

An error occurred.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below |
+--------------------+-----------------+


The start, stop, and refresh options are Private interfaces. All
other options are Evolving. The utility name is Stable.

SEE ALSO

libpkcs11(3LIB), random(4D), exec_attr(5), prof_attr(5),
attributes(7), smf(7), logadm(8), svcadm(8), syslogd(8)


Solaris Security for Developer's Guide

NOTES

If a hardware provider's policy was made explicitly (that is, some of
its mechanisms were disabled) and the hardware provider has been
detached, the policy of this hardware provider is still listed.


cryptoadm assumes that, minimally, a 32-bit shared object is
delivered for each user-level provider. If both a 32-bit and 64-bit
shared object are delivered, the two versions must provide the same
functionality. The same mechanism policy applies to both.

September 1, 2009 CRYPTOADM(8)