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 set-
ting 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.sfbay: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/kmfpol-
icy.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 OCSP-
Signing
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 ver-
ify 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: digi-
talSignature, 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.sfbay: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 num-
ber-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/sta-
tus
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, num-
ber-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 pol-
icy 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. Thedefaultpolicy in the system KMF policy data-
base 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 pluginkeyword, 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 com-
mand 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
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWcsu |
+-----------------------------+-----------------------------+
|Interface Stability |Uncommitted |
+-----------------------------+-----------------------------+
SEE ALSO
attributes(5)
SunOS 5.11 3 Feb 2009 kmfcfg(1)