Oracle Solaris Key Management Framework Components

This section describes the following KMF components:

• The pktool(1) key management tool

• The KMF policy database

• The kmfcfg(1) policy definition and plugin configuration utility

• KMF data types defined in kmftypes.h and programming interfaces defined in kmfapi.h and libkmf(3LIB)

KMF Key Management Tool

The following pktool(1) subcommands specifically support KMF:

delete

Delete objects in the keystore.

download

Download a CRL or certificate file from an external source.

export

Export objects from the keystore to a file.

gencert

Create a self-signed X.509v3 certificate.

gencsr

Create a PKCS#10 Certificate Signing Request (CSR) file.

genkey

Create a symmetric key in the keystore.

help

Displays a help message.

import

Import objects from an external source.

inittoken

Initialize a PKCS#11 token.

list

List a summary of objects in the keystore.

setpin

Change user authentication passphrase for keystore access.

signcsr

Sign a PKCS#10 CSR.

tokens

List all visible PKCS#11 tokens.

KMF Policy Enforcement Mechanisms

KMF policy is a hierarchical tree of policies. A default policy is defined when the system is installed. The default policy applies unless the application asserts a different policy.

Policy parameters control the use of X.509 certificates by an application. KMF policy applies to all certificates and is not restricted to any particular keystore.

Use the kmfcfg(1) utility to manage the KMF policy database and configure plugins. You can use kmfcfg to list, create, modify, delete, import, and export policy definitions in the system default database file /etc/security/kmfpolicy.xml or in a user-defined database file. Note that you cannot modify the default policy in the system KMF policy database. For plugin configuration, you can use kmfcfg to display plugin information, install or uninstall a KMF plugin, and modify the plugin option.

The following list shows some of the KMF policy attributes. See the kmfcfg(1) man page for a complete list and descriptions of these policy attributes.

• Policy Name. Applications reference this name.

• Default Keystore. Examples include NSS, files, PKCS11.

• Ignore Date. Ignore the validity periods defined in the certificates when evaluating their validity.

• Ignore Unknown EKU. Ignore any unrecognized EKU values in the Extended Key Usage extension.

• Token Label. This attribute only applies to NSS or PKCS11 keystores.

• Validation Method. Examples include OCSP and CRL.

• Key Usage Values. This attribute is a comma separated list of key usage values that are required by the policy being defined. These bits must be set in order to use the certificate.

• Extended Key Usage Values. This attribute is a comma separated list of Extended Key Usage OIDs that are required by the policy being defined. These OIDS must be present in order to use the certificate.

See the kmfpolicy.h file for definitions of policy data types.

The following plugin libraries are provided in Oracle Solaris KMF:

• PKCS#11 keystore plugin: kmf_pkcs11

• OpenSSL keystore plugin: kmf_openssl

• NSS keystore plugin: kmf_nss

KMF Application Programming Interfaces

The Oracle Solaris KMF provides abstract APIs for PKI operations. Applications written to KMF can access multiple keystores such as files (OpenSSL), NSS, and PKCS11 tokens and multiple validation modules such as OCSP and CRL checking. The KMF API can be extended by third parties for proprietary and legacy implementations.

The KMF APIs are provided in the Key Management Framework Library, libkmf(3LIB). These APIs enable your application to create and manage public key objects such as public/private keypairs, certificates, CSRs, certificate validation, CRLs, and OCSP response processing.

• Keys, certificate, and CSR operations: create and delete, store and retrieve, search, import and export

• Common cryptographic operations: sign and verify, encrypt and decrypt using certificates as keys

• Access complex PKI objects: set and get X.509 attributes and extensions, and extract data in human-readable formats

The KMF APIs are defined in the kmfapi.h file, and structures and types are defined in the kmftypes.h file. The kmfapi.h file lists the functions in the following groups:

• Setup operations

• Key operations

• Certificate operations

• Cryptographic operations with key or certificate

• CRL operations

• CSR operations

• Get certificate operations

• Set certificate operations

• PK12 operations

• OCSP operations

• Policy operations

• Error handling

• Memory cleanup operations

• APIs for PKCS#11 tokens

• Attribute management operations