path: root/usr/src/man/man1m/cryptoadm.1m

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CRYPTOADM 1M "Sep 1, 2009"
.SH NAME
cryptoadm \- cryptographic framework administration
.SH SYNOPSIS
.nf
\fBcryptoadm\fR list [\fB-mpv\fR] [provider=\fIprovider-name\fR]
     [mechanism=\fImechanism-list\fR]
.fi

.LP
.nf
\fBcryptoadm\fR disable
     provider=\fIprovider-name\fR mechanism=\fImechanism-list\fR | random | all
.fi

.LP
.nf
\fBcryptoadm\fR enable
     provider=\fIprovider-name\fR mechanism=\fImechanism-list\fR | random | all
.fi

.LP
.nf
\fBcryptoadm\fR install provider=\fIprovider-name\fR
.fi

.LP
.nf
\fBcryptoadm\fR install provider=\fIprovider-name\fR
     [mechanism=\fImechanism-list\fR]
.fi

.LP
.nf
\fBcryptoadm\fR uninstall provider=\fIprovider-name\fR
.fi

.LP
.nf
\fBcryptoadm\fR unload provider=\fIprovider-name\fR
.fi

.LP
.nf
\fBcryptoadm\fR disable fips-140
.fi

.LP
.nf
\fBcryptoadm\fR enable fips-140
.fi

.LP
.nf
\fBcryptoadm\fR list fips-140
.fi

.LP
.nf
\fBcryptoadm\fR refresh
.fi

.LP
.nf
\fBcryptoadm\fR start
.fi

.LP
.nf
\fBcryptoadm\fR stop
.fi

.LP
.nf
\fBcryptoadm\fR \fB-\fR\fB-help\fR
.fi

.SH DESCRIPTION
The \fBcryptoadm\fR 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).
.sp
.LP
For kernel software providers, the \fBcryptoadm\fR utility provides the
\fBunload\fR subcommand. This subcommand instructs the kernel to unload a
kernel software providers.
.sp
.LP
For the cryptographic framework's metaslot, the \fBcryptoadm\fR 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.
.sp
.LP
The \fBcryptoadm\fR utility provides subcommands to enable and disable FIPS-140
mode in the Cryptographic Framework. It also provides a \fBlist\fR subcommand
to display the current status of FIPS-140 mode.
.sp
.LP
Administrators will find it useful to use \fBsyslog\fR facilities (see
\fBsyslogd\fR(1M) and \fBlogadm\fR(1M)) to maintain the cryptographic
subsystem. Logging can be especially useful under the following circumstances:
.RS +4
.TP
.ie t \(bu
.el o
If kernel-level daemon is dead, all applications fail. You can learn this from
syslog and use \fBsvcadm\fR(1M) to restart the \fBsvc:/system/cryptosvc\fR
service.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If there are bad providers plugged into the framework, you can learn this from
syslog and remove the bad providers from the framework.
.RE
.sp
.LP
With the exception of the subcommands or options listed below, the
\fBcryptoadm\fR command needs to be run by a privileged user.
.RS +4
.TP
.ie t \(bu
.el o
subcommand \fBlist\fR, any options
.RE
.RS +4
.TP
.ie t \(bu
.el o
subcommand \fB-\fR\fB-help\fR
.RE
.SH OPTIONS
The \fBcryptoadm\fR utility has the various combinations of subcommands and
options shown below.
.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist\fR\fR
.ad
.sp .6
.RS 4n
Display the list of installed providers.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist metaslot\fR\fR
.ad
.sp .6
.RS 4n
Display the system-wide configuration for metaslot.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist\fR \fB-m\fR \fB[ provider=\fIprovider-name\fR |
metaslot ]\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist\fR \fB-p\fR \fB[ provider=\fIprovider-name\fR |
metaslot ]\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist\fR \fB-v\fR \fBprovider=\fIprovider-name\fR |
metaslot\fR\fR
.ad
.sp .6
.RS 4n
Display details about the specified provider if a provider is specified. If the
metaslot keyword is specified, display details about the metaslot.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
For the various \fBlist\fR subcommands described above (except for \fBlist\fR
\fB-p\fR), the \fB-v\fR (verbose) option provides details about providers,
mechanisms and slots.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBdisable provider=\fIprovider-name\fR\fR\fR
.ad
.br
.na
\fB[ mechanism=\fImechanism-list\fR | \fIprovider-feature\fR \fB\&... |\fR
\fBall\fR ]\fR
.ad
.sp .6
.RS 4n
Disable the mechanisms or provider features specified for the provider. See
OPERANDS for a description of \fImechanism\fR, \fIprovider-feature\fR, and the
\fBall\fR keyword.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fB[ mechanism=\fImechanism-list\fR ] [ auto-key-migrate
]\fR\fR
.ad
.sp .6
.RS 4n
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 \fBauto-key-migrate\fR 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 \fBauto-key-migrate\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBenable provider=\fIprovider-name\fR\fR\fR
.ad
.br
.na
\fB[ mechanism=\fImechanism-list\fR | \fIprovider-feature\fR \fB\&... |\fR
\fBall\fR ]\fR
.ad
.sp .6
.RS 4n
Enable the mechanisms or provider features specified for the provider. See
OPERANDS for a description of \fImechanism\fR, \fIprovider-feature\fR, and the
\fBall\fR keyword.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBenable metaslot [ mechanism=\fImechanism-list\fR ]
|\fR\fR
.ad
.br
.na
\fB\fB[ [ token=\fItoken-label\fR] [ slot=\fIslot-description\fR] |\fR\fR
.ad
.br
.na
\fB\fBdefault-keystore ] | [ auto-key-migrate ]\fR\fR
.ad
.sp .6
.RS 4n
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 \fItoken-label\fR is
specified, the specified token will be used as the persistent object store. If
the \fIslot-description\fR is specified, the specified slot will be used as the
persistent object store. If both the \fItoken-label\fR and the
\fIslot-description\fR are specified, the provider with the matching token
label and slot description is used as the persistent object store. If the
\fBdefault-keystore\fR keyword is specified, metaslot will use the default
persistent object store. If the \fBauto-key-migrate\fR 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, \fBdefault-keystore\fR, and \fBauto-key-migrate\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBinstall provider=\fIprovider-name\fR\fR\fR
.ad
.sp .6
.RS 4n
Install a user-level provider into the system. The \fIprovider\fR 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 \fB$ISA\fR. Note that \fB$ISA\fR is not a
reference to an environment variable. Note also that \fB$ISA\fR must be quoted
(with single quotes [for example, \fB\&'$ISA'\fR]) or the \fB$\fR must be
escaped to keep it from being incorrectly expanded by the shell. The user-level
framework expands \fB$ISA\fR to an empty string or an architecture-specific
directory, for example, \fBsparcv9\fR.
.sp
The preferred way of installing a user-level provider is to build a package for
the provider. For more information, see the \fISolaris Security for Developer's
Guide\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBinstall provider=\fIprovider-name\fR\fR\fR
.ad
.br
.na
\fBmechanism=\fImechanism-list\fR\fR
.ad
.sp .6
.RS 4n
Install a kernel software provider into the system. The provider should contain
the base name only. The \fImechanism-list\fR operand specifies the complete
list of mechanisms to be supported by this provider.
.sp
The preferred way of installing a kernel software provider is to build a
package for providers. For more information, see the \fISolaris Security for
Developer's Guide\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBuninstall provider=\fIprovider-name\fR\fR\fR
.ad
.sp .6
.RS 4n
Uninstall the specified \fIprovider\fR and the associated mechanism policy from
the system. This subcommand applies only to a user-level provider or a kernel
software provider.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBunload provider=\fIprovider-name\fR\fR\fR
.ad
.sp .6
.RS 4n
Unload the kernel software module specified by \fIprovider\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBdisable fips-140\fR\fR
.ad
.sp .6
.RS 4n
Disable FIPS-140 mode in the Cryptographic Framework.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBenable fips-140\fR\fR
.ad
.sp .6
.RS 4n
Enable FIPS-140 mode in the Cryptographic Framework. This subcommand does not
disable the non-FIPS approved algorithms from the user-level
\fBpkcs11_softtoken\fR library and the kernel software providers. It is the
consumers of the framework that are responsible for using only FIPS-approved
algorithms.
.sp
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.
.sp
The system will require a reboot to perform Power-Up Self Tests that include a
cryptographic algorithm test and a software integrity test.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBlist fips-140\fR\fR
.ad
.sp .6
.RS 4n
Display the current setting of FIPS-140 mode in the Cryptographic Framework.
The status of FIPS-140 mode is \fBenabled\fR or \fBdisabled\fR. The default
FIPS-140 mode is \fBdisabled\fR.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fBrefresh\fR\fR
.ad
.br
.na
\fB\fBcryptoadm\fR \fBstart\fR\fR
.ad
.br
.na
\fB\fBcryptoadm\fR \fBstop\fR\fR
.ad
.sp .6
.RS 4n
Private interfaces for use by \fBsmf\fR(5), these must not be used directly.
.RE

.sp
.ne 2
.na
\fB\fBcryptoadm\fR \fB-help\fR\fR
.ad
.sp .6
.RS 4n
Display the command usage.
.RE

.SH OPERANDS
.ne 2
.na
\fBprovider=\fIprovider-name\fR\fR
.ad
.sp .6
.RS 4n
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).
.sp
A valid value of the \fIprovider\fR operand is one entry from the output of a
command of the form: \fBcryptoadm\fR \fIlist\fR. A \fIprovider\fR operand for a
user-level provider is an absolute pathname of the corresponding shared
library. A \fIprovider\fR operand for a kernel software provider contains a
base name only. A \fIprovider\fR operand for a kernel hardware provider is in a
"\fIname\fR/\fInumber\fR" form.
.RE

.sp
.ne 2
.na
\fBmechanism=\fImechanism-list\fR\fR
.ad
.sp .6
.RS 4n
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 \fBall\fR for \fImechanism-list\fR, to specify all
mechanisms on a provider. See the discussion of the \fBall\fR keyword, below.
.RE

.sp
.ne 2
.na
\fB\fIprovider-feature\fR\fR
.ad
.sp .6
.RS 4n
A cryptographic framework feature for the given provider. Currently only
\fBrandom\fR is accepted as a feature. For a user-level provider, disabling the
random feature makes the PKCS #11 routines \fBC_GenerateRandom\fR and
\fBC_SeedRandom\fR unavailable from the provider. For a kernel provider,
disabling the random feature prevents \fB/dev/random\fR from gathering random
numbers from the provider.
.RE

.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.sp .6
.RS 4n
The keyword all can be used with with the \fBdisable\fR and \fBenable\fR
subcommands to operate on all provider features.
.RE

.sp
.ne 2
.na
\fB\fBtoken=\fR\fItoken-label\fR\fR
.ad
.sp .6
.RS 4n
The label of a token in one of the providers in the cryptographic framework.
.sp
A valid value of the token operand is an item displayed under "Token Label"
from the output of the command \fBcryptoadm list\fR \fB-v\fR.
.RE

.sp
.ne 2
.na
\fB\fBslot=\fR\fIslot-description\fR\fR
.ad
.sp .6
.RS 4n
The description of a slot in one of the providers in the cryptographic
framework.
.sp
A valid value of the slot operand is an item displayed under "Description" from
the output of the command \fBcryptoadm list\fR \fB-v\fR.
.RE

.sp
.ne 2
.na
\fB\fBdefault-keystore\fR\fR
.ad
.sp .6
.RS 4n
The keyword \fBdefault-keystore\fR is valid only for metaslot. Specify this
keyword to set the persistent object store for metaslot back to using the
default store.
.RE

.sp
.ne 2
.na
\fB\fBauto-key-migrate\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.LP
The keyword \fBall\fR can be used in two ways with the \fBdisable\fR and
\fBenable\fR subcommands:
.RS +4
.TP
.ie t \(bu
.el o
You can substitute \fBall\fR for \fBmechanism\fR=\fImechanism-list\fR, as in:
.sp
.in +2
.nf
# \fBcryptoadm enable provider=dca/0 all\fR
.fi
.in -2
.sp

This command enables the mechanisms on the provider \fBand\fR any other
provider-features, such as \fBrandom\fR.
.sp
.in +2
.nf
# \fBcryptoadm enable provider=des mechanism=all\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
You can also use \fBall\fR as an argument to \fBmechanism\fR, as in:
.sp
.in +2
.nf
# \fBcryptoadm enable provider=des mechanism=all\fR
.fi
.in -2
.sp

\&...which enables all mechanisms on the provider, but enables no other
provider-features, such as \fBrandom\fR.
.RE
.SH EXAMPLES
\fBExample 1 \fRDisplay List of Providers Installed in System
.sp
.LP
The following command displays a list of all installed providers:

.sp
.in +2
.nf
example% \fBcryptoadm list\fR
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
.fi
.in -2
.sp

.LP
\fBExample 2 \fRDisplay Mechanism List for \fBmd5\fR Provider
.sp
.LP
The following command is a variation of the \fBlist\fR subcommand:

.sp
.in +2
.nf
example% \fBcryptoadm list -m provider=md5\fR
md5: CKM_MD5,CKM_MD5_HMAC,CKM_MD5_HMAC_GENERAL
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDisable Specific Mechanisms for Kernel Software Provider
.sp
.LP
The following command disables mechanisms \fBCKM_DES3_ECB\fR and
\fBCKM_DES3_CBC\fR for the kernel software provider \fBdes\fR:

.sp
.in +2
.nf
example# \fBcryptoadm disable provider=des\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisplay Mechanism Policy for a Provider
.sp
.LP
The following command displays the mechanism policy for the \fBdes\fR provider:

.sp
.in +2
.nf
example% \fBcryptoadm list -p provider=des\fR
des: All mechanisms are enabled, except CKM_DES3_ECB, CKM_DES3_CBC
.fi
.in -2
.sp

.LP
\fBExample 5 \fREnable Specific Mechanism for a Provider
.sp
.LP
The following command enables the \fBCKM_DES3_ECB\fR mechanism for the kernel
software provider \fBdes\fR:

.sp
.in +2
.nf
example# \fBcryptoadm enable provider=des mechanism=CKM_DES3_ECB\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRInstall User-Level Provider
.sp
.LP
The following command installs a user-level provider:

.sp
.in +2
.nf
example# \fBcryptoadm install provider=/opt/lib/libcryptoki.so.1\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRInstall User-Level Provider That Contains 32- and 64-bit
Versions
.sp
.LP
The following command installs a user-level provider that contains both 32-bit
and 64-bit versions:

.sp
.in +2
.nf
example# \fBcryptoadm install \e\fR
provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1
.fi
.in -2
.sp

.LP
\fBExample 8 \fRUninstall a Provider
.sp
.LP
The following command uninstalls the \fBmd5\fR provider:

.sp
.in +2
.nf
example# \fBcryptoadm uninstall provider=md5\fR
.fi
.in -2
.sp

.LP
\fBExample 9 \fRDisable metaslot
.sp
.LP
The following command disables the metaslot feature in the cryptographic
framework.

.sp
.in +2
.nf
example# \fBcryptoadm disable metaslot\fR
.fi
.in -2
.sp

.LP
\fBExample 10 \fRSpecify metaslot to Use Specified Token as Persistent Object
Store
.sp
.LP
The following command specifies that metaslot use the Venus token as the
persistent object store.

.sp
.in +2
.nf
example# \fBcryptoadm enable metaslot token="SUNW,venus"\fR
.fi
.in -2
.sp

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below
.TE

.sp
.LP
The \fBstart\fR, \fBstop\fR, and \fBrefresh\fR options are Private interfaces.
All other options are Evolving. The utility name is Stable.
.SH SEE ALSO
\fBlogadm\fR(1M), \fBsvcadm\fR(1M), \fBsyslogd\fR(1M), \fBlibpkcs11\fR(3LIB),
\fBexec_attr\fR(4), \fBprof_attr\fR(4), \fBattributes\fR(5), \fBsmf\fR(5),
\fBrandom\fR(7D)

.sp
.LP
\fISolaris Security for Developer's Guide\fR
.SH 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.
.sp
.LP
\fBcryptoadm\fR 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.