Tribblix: manual page: kmfcfg.1

KMFCFG(1) User Commands KMFCFG(1)

NAME

kmfcfg - Key Management Policy and Plugin Configuration Utility

SYNOPSIS

kmfcfg subcommand [option ...]

DESCRIPTION

The kmfcfg command allows users to configure Key Management Framework
(KMF) policy databases. The KMF policy database (DB) restricts the
use of keys and certificates that are managed through the KMF
framework.

kmfcfg provides the ability to list, create, modify, delete, import
and export policy definitions either in the system default database
file /etc/security/kmfpolicy.xml or a user-defined database file.

For plugin configuration, kmfcfg allows users to display plugin
information, install or uninstall a KMF plugin, and modify the plugin
option.

SUBCOMMANDS

The following subcommands are supported:

create

Adds a new policy into the policy database file.

The format for the create subcommand is as follows:

create [dbfile=dbfile] policy=policyname
[ignore-date=true|false]
[ignore-unknown-eku=true|false]
[ignore-trust-anchor=true|false]
[validity-adjusttime=adjusttime]
[ta-name=trust anchor subject DN]
[ta-serial=trust anchor serial number]
[ocsp-responder=URL]
[ocsp-proxy=URL]
[ocsp-use-cert-responder=true|false]
[ocsp-response-lifetime=timelimit]
[ocsp-ignore-response-sign=true|false]
[ocsp-responder-cert-name=Issuer DN]
[ocsp-responder-cert-serial=serial number]
[crl-basefilename=basefilename]
[crl-directory=directory]
[crl-get-crl-uri=true|false]
[crl-proxy=URL]
[crl-ignore-crl-sign=true|false]
[crl-ignore-crl-date=true|false]
[keyusage=digitalSignature|nonRepudiation
|keyEncipherment | dataEncipherment |
keyAgreement |keyCertSign |
cRLSign | encipherOnly | decipherOnly],[...]
[ekunames=serverAuth | clientAuth |
codeSigning | emailProtection |
ipsecEndSystem | ipsecTunnel |
ipsecUser | timeStamping |
OCSPSigning],[...]
[ekuoids=OID,OID,OID...]

The create subcommand supports the following options:

crl-basefilename=filename
crl-directory=directory

These two attributes are used to specify the location for CRL
files. The crl-basefilename attribute represents the base
filename for a CRL file. The crl-directory attribute
represents the directory for CRL files, which defaults to the
current directory.

If the crl-get-crl-uri attribute is set to true and the crl-
basefilename is not specified, the basefilename for the
cached CRL file is the basename of the URI used to fetch the
CRL file.

If the crl-get-crl-uri attribute is set to false the crl-
basefilename needs to be specified to indicate an input CRL
file. The setting for crl-get-crl-uri is false by default.

These two attributes only apply to the file-based CRL
plugins. The current file-based CRL plugins are file and
pkcs11 keystores. For the nss keystore, the CRL location is
always the NSS internal database.

crl-get-crl-uri=true | false

Configure if a CRL file is fetched and cached dynamically as
part of the certificate validation, using the URI information
from the certificate's distribution points extension.

The default for this attribute is false.

crl-ignore-crl-date=true | false

If crl-ignore-crl-date is set to true, the validity time
period of the CRL is not checked.

The default for this attribute is false.

crl-ignore-crl-sign=true | false

If crl-ignore-crl-sign is set to true, the signature of the
CRL is not checked.

The default for this attribute is false.

crl-proxy= URL

Sets the proxy server name and port for dynamically
retrieving a CRL file when crl-get-crl-uri is set to true.

The port number is optional. If the port number is not
specified, the default value is 8080. An example crl-proxy
setting might be: crl-proxy=webcache.example.org:8080.

dbfile=dbfile

The DB file to add the new policy. If not specified, the
default is the system KMF policy database file
/etc/security/kmfpolicy.xml.

ekuoids=EKUOIDS

A comma separated list of Extended Key Usage OIDs that are
required by the policy being defined. The OIDs are expressed
in dot notation, for example, 1.2.3.4. An example ekuoids
setting might be: ekuoids=1.2.3.4,9.8.7.6.5.

ekunames=EKUNAMES

A comma separated list of Extended Key Usage names that are
required by the policy being defined. The list of values
allowed for EKUNAMES are: serverAuth, clientAuth,
codeSigning, emailProtection, ipsecEndSystem, ipsecTunnel,
ipsecUser, timeStamping, and OCSPSigning

The OCSP, CRL, key usage and extended key usage checkings are
off by default. To turn on any one of them, specify one or
more attributes for the particular checking. For example, if
the ocsp-responder attribute is set, then the OCSP checking
is turned on. If the ekuname attribute or the ekuoids
attribute is set, then the extended key usage checking is
turned on.

ignore-date=true | false

Set the Ignore Date option for this policy. By default this
value is false. If true is specified, the policy ignores the
validity periods defined in the certificates when evaluating
their validity.

ignore-unknown-eku=true | false

Set the Ignore Unknown EKU option for this policy. By default
this value is false. If true, the policy ignores any
unrecognized EKU values in the Extended Key Usage extension.

ignore-trust-anchor=true | false

Set the Ignore Trust Anchor option for this policy. By
default this value is false. If true is specified, the policy
does not verify the signature of the subject certificate
using trust anchor certificate at validation.

keyusage=KUVALUES

A comma separated list of key usage values that are required
by the policy being defined. The list of values allowed are:
digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign,
encipherOnly, decipherOnly

ocsp-ignore-response-sign=true | false

If this attribute is set to true, the signature of the OCSP
response is not verified. This attribute value is default to
false.

ocsp-proxy=URL

Set the proxy server name and port for OCSP. The port number
is optional. If the port number is not specified, the default
value is 8080. An example ocsp-proxy setting might be: ocsp-
proxy="webcache.example.org:8080"

ocsp-response-lifetime=timelimit

Set the freshness period that a response must be. The
timelimit can be specified by number-day, number-hour,
number-minute, or number-second. An example ocsp-response-
lifetime setting might be:ocsp-response-lifetime=6-hour.

ocsp-responder-cert-name=IssuerDN
ocsp-responder-cert-serial=serialNumber

These two attributes represent the OCSP responder
certificate. The ocsp-responder-cert-name is to specify the
issuer name of the certificate. See the ta-name option for
example. The ocsp-responder-cert-serial is for the serial
number and must be specified as a hex value, for example,
0x0102030405060708090a0b0c0d0e0f. If an OCSP responder is
different from the issuer of the certificate and if the OCSP
response needs to be verified, an OCSP responder certificate
information should be provided.

ocsp-responder=URL

Set the OCSP responder URL for use with the OCSP validation
method. For example, ocsp-
responder=http://ocsp.verisign.com/ocsp/status

ocsp-use-cert-responder=true | false

Configure this policy to always use the responder defined in
the certificate itself if possible.

policy=policyname

The policy record to be created. policyname is required.

validity-adjusttime=adjusttime

Set the adjust time for both ends of validity period for a
certificate. The time can be specified by number-day, number-
hour, number-minute, or number-second. An example validity-
adjusttime setting might be: validity-adjusttime=6-hour. ta-
name="Subject DN" ta-serial=serialNumber

These two attributes represent the trust anchor certificate
and are used to find the trust anchor certificate in the
keystore. The ta-name is to specify the distinguished name of
the trust anchor certificate subject name. For example, ta-
name="O=Sun Microsystems Inc., OU=Solaris Security
Technologies Group, L=Ashburn, ST=VA, C=US, CN=John Smith"
The serial number of the TA certificate. This, along with the
Issuer DN, is used to find the TA certificate in the
keystore. The serial number must be specified as a hex value,
for example, 0x0102030405060708090a0b0c0d0e The trust anchor
attributes need to be set, if the value of ignore-trust-
anchor attribute is false.

delete

Deletes any policy matching the indicated policy name. The system
default policy (default) cannot be deleted.

The format for the delete subcommand is as follows:

delete [dbfile=dbfile] policy=policyname

The delete subcommand supports the following options:

dbfile=dbfile
Read policy definitions from the indicated
file. If dbfile is not specified, the
default is the system KMF policy database
file: /etc/security/kmfpolicy.xml.

policy=policyname
The name of the policy to delete. policyname
is required, if using the system database.

export

Exports a policy from one policy database file to another policy
database file.

The format for the export subcommand is as follows:

kmfcfg export policy=policyname outfile=newdbfile [dbfile=dbfile]

The export subcommand supports the following options:

dbfile=dbfile
The DB file where the exported policy is
read. If dbfile is not specified, the
default is the system KMF policy database
file: /etc/security/kmfpolicy.xml.

outfile=outputdbfile
The DB file where the exported policy is
stored.

policy=policyname
The policy record to be exported.

help

Displays help for the kmfcfg command.

The format for the help subcommand is as follows:

help

import

Imports a policy from one policy database file to another policy
database file.

The format for the import subcommand is as follows:

kmfcfg import policy=policyname infile=inputdbfile [dbfile=dbfile]

The import subcommand supports the following options:

policy=policyname
The policy record to be imported.

infile=inputdbfile
The DB file to read the policy from.

dbfile=outdbfile
The DB file to add the new policy. If not
specified, the default is the system KMF
policy database file
/etc/security/kmfpolicy.xml.

list

Without arguments, lists all policy definitions from the default
system database.

The format for the list subcommand is as follows:

list [dbfile=dbfile] [policy=policyname]

The list subcommand supports the following options:

dbfile=dbfile
Reads policy definitions from the indicated
file. If not specified, the default is the
system KMF policy database file
/etc/security/kmfpolicy.xml.

policy=policyname
Only display policy definition for the named
policy.

modify

Modifies any policy matching the indicated name. The system
default policy (default) cannot be modified.

The format for the modify subcommand is as follows:

modify [dbfile=dbfile] policy=policyname
[ignore-date=true|false]
[ignore-unknown-eku=true|false]
[ignore-trust-anchor=true|false]
[validity-adjusttime=adjusttime]
[ta-name=trust anchor subject DN]
[ta-serial=trust anchor serial number]
[ocsp-responder=URL]
[ocsp-proxy=URL]
[ocsp-use-cert-responder=true|false]
[ocsp-response-lifetime=timelimit]
[ocsp-ignore-response-sign=true|false]
[ocsp-responder-cert-name=Issuer DN]
[ocsp-responder-cert-serial=serial number]
[ocsp-none=true|false]
[crl-basefilename=basefilename]
[crl-directory=directory]
[crl-get-crl-uri=true|false]
[crl-proxy=URL]
[crl-ignore-crl-sign=true|false]
[crl-ignore-crl-date=true|false]
[crl-none=true|false]
[keyusage=digitalSignature| nonRepudiation
|keyEncipherment | dataEncipherment |
keyAgreement |keyCertSign |
cRLSign | encipherOnly | decipherOnly],[...]
[keyusage-none=true|false]
[ekunames=serverAuth | clientAuth |
codeSigning | emailProtection |
ipsecEndSystem | ipsecTunnel |
ipsecUser | timeStamping |
OCSPSigning],[...]
[ekuoids=OID,OID,OID]
[eku-none=true|false]

The modify subcommand supports many of the same options as the
create subcommand. For descriptions of shared options, see the
create subcommand.

The modify subcommand supports the following unique options:

crl-none=true | false
If crl-none is set to true, CRL
checking is turned off. If this
attribute is set to true, other CRL
attributes cannot be set.

dfile=[dbfile]
The database file to modify a
policy. If not specified, the
default is the system KMF policy
database file
/etc/security/kmfpolicy.xml.

eku-none=true | false
If eku-none is set to true,
extended key usage checking is
turned off. The extended key usage
attributes, ekuname and ekuoids
cannot be set at the same time if
eku-none is set to true.

keyusage-none=true | false
If keyusage-none is set to true,
key usage checking is turned off.

The keyusage attribute cannot be
set at the same time if this
attribute is set to true.

ocsp-none=true | false
If ocsp-none is set to true, OCSP
checking is turned off. Any other
OCSP attribute is not set at the
same time if this attribute is set
to true.

policy=policyname
The name of the policy to modify.
policyname is required. The
default policy in the system KMF
policy database cannot be modified.

Plugin Subcommands

install keystore=keystore_name modulepath=pathname\
[option=option_str]

Install a plugin into the system. The modulepath field specifies
the pathname to a KMF plugin shared library object. If pathname
is not specified as an absolute pathname, shared library objects
are assumed to be relative to /lib/security/$ISA/. The ISA token
is replaced by an implementation defined directory name which
defines the pathname relative to the calling program's
instruction set architecture.

list plugin

Display KMF plugin information.

Without the plugin keyword, kmfcfg list shows the policy
information as described in the SUBCOMMANDS section.

modify plugin keystore=keystore_name option=option_str

Modify the plugin option. The plugin option is defined by the
plugin and is interpreted by the plugin specifically, therefore
this command accepts any option string.

Without the plugin keyword, kmfcfg modify updates the policy
configuration as described in the SUBCOMMANDS section.

uninstall keystore=keystore_name

Uninstall the plugin with the keystore_name.

EXAMPLES

Example 1: Creating a New Policy

The following example creates a new policy called IPSEC in the system
database:

$ kmfcfg create IPSEC \
ignore-trust-anchor=true \
ocsp-use-cert-responder=true \
keyusage=keyAgreement,keyEncipherment,dataEncipherment \
ekuname=ipsecTunnel,ipsecUser

EXIT STATUS

The following exit values are returned:

0
Successful completion.

>0
An error occurred.

FILES

/etc/security/kmfpolicy.xml

Default system policy database

ATTRIBUTES