In the Solaris Express Community Edition, the Key Management Framework (KMF) provides tools and programming interfaces for managing public key objects. Public key objects include X.509 certificates and public/private key pairs. The formats for storing these objects can vary. KMF also provides a tool for managing policies that define the use of X.509 certificates by applications. In the Solaris Express Community Edition, KMF supports third-party plugins.Managing Public Key Technologies Key Management Framework Utilities Using the Key Management Framework (Tasks) key management framework (KMF)KMFpublic key technologiesPKIKMFmanagingpublic key technologies (PKI)PKImanaged by KMFThe Key Management Framework (KMF) provides a unified approach to managing public key technologies (PKI). The Solaris OS has several different applications that make use of PKI technologies. Each application provides its own programming interfaces, key storage mechanisms, and administrative utilities. If an application provides a policy enforcement mechanism, the mechanism applies to that application only. With KMF, applications use a unified set of administrative tools, a single set of programming interfaces, and a single policy enforcement mechanism. These features manage the PKI needs of all applications that adopt these interfaces.KMF unifies the management of public key technologies with the following interfaces:pktool commandmanaging PKI objectspktool command – This command manages PKI objects, such as certificates, in a variety of keystores. kmfcfg commandplugin subcommandskmfcfg command – This command manages the PKI policy database and third-party plugins.PKI policy decisions include operations such as the validation method for an operation. Also, PKI policy can limit the scope of a certificate. For example, PKI policy might assert that a certificate can be used only for specific purposes. Such a policy would prevent that certificate from being used for other requests. KMFlibraryKMF library – This library contains programming interfaces that abstract the underlying keystore mechanism.Applications do not have to choose one particular keystore mechanism, but can migrate from one mechanism to another mechanism. The supported keystores are PKCS #11, NSS, and OpenSSL. The library includes a pluggable framework so that new keystore mechanisms can be added. Therefore, applications that use the new mechanisms would require only minor modifications to use a new keystore. keystoresmanaged by KMF KMFutilities KMF provides methods for managing the storage of keys and provides the overall policy for the use of those keys. KMF manages the policy, keys, and certificates for three public key technologies:Tokens from PKCS #11 providers, that is, from the Solaris Cryptographic Framework NSS, that is, Network Security Services OpenSSL, a file-based keystore The kmfcfg tool can create, modify, or delete KMF policy entries. The tool also manages plugins to the framework. KMF manages keystores through the pktool command. For more information, see the kmfcfg1 and pktool1 man pages, and the following sections. KMFmanagingPKI policyPKIpolicy managed by KMFKMF policy is stored in a database. This policy database is accessed internally by all applications that use the KMF programming interfaces. The database can constrain the use of the keys and certificates that are managed by the KMF library. When an application attempts to verify a certificate, the application checks the policy database. The kmfcfg command modifies the policy database. kmfcfg commandplugin subcommands pluginsmanaged in KMF KMFmanagingplugins The kmfcfg command provides the following subcommands for plugins:list plugin – Lists plugins that are managed by KMF. install plugin – Installs the plugin by the module's path name and creates a keystore for the plugin. To remove the plugin from KMF, you remove the keystore. uninstall plugin – Removes the plugin from KMF by removing its keystore. modify plugin – Enables the plugin to be run with an option that is defined in the code for the plugin, such as debug. For more information, see the kmfcfg1 man page. For the procedure, see How to Manage Third-Party Plugins in KMF. KMFmanagingkeystoresmanagingkeystores with KMFNSSmanaging keystoreOpenSSLmanaging keystorePKCS #11 softtokensmanaging keystoreKMF manages the keystores for three public key technologies, PKCS #11 tokens, NSS, and OpenSSL. For all of these technologies, the pktool command enables you to do the following:Designate a keystore for each certificate and PIN. Generate a self-signed certificate. Generate a certificate request. Generate a symmetric key. Import objects into the keystore. List the objects in the keystore. Delete objects from the keystore. Download a CRL. KMFcreatingpassphrases for keystoresFor the PKCS #11 and NSS technologies, the pktool command also enables you to set a PIN by generating a passphrase:Generate a passphrase for the keystore. Generate a passphrase for an object in the keystore. For examples of using the pktool utility, see the pktool1 man page and Using the Key Management Framework (Task Map). task mapsUsing the Key Management Framework (Task Map) Using the Key Management Framework (Task Map) protectingby using passwords with cryptographic framework user proceduresusing pktool command The Key Management Framework (KMF) enables you to centrally manage public key technologies.Task Description For Instructions Create a certificate. Creates a certificate for use by PKCS #11, NSS, or SSL. How to Create a Certificate by Using the pktool gencert Command Export a certificate. Creates a file with the certificate and its supporting keys. The file can be protected with a password. How to Export a Certificate and Private Key in PKCS #12 Format Import a certificate. Imports a certificate from another system. How to Import a Certificate Into Your Keystore Imports a certificate in PKCS #12 format from another system. Example 15–2 Generate a passphrase. Generates a passphrase for access to a PKCS #11 keystore or an NSS keystore. How to Generate a Passphrase by Using the pktool setpin Command Generate a symmetric key. Generates symmetric keys for use in encrypting files, creating a MAC of a file, and for applications. How to Generate a Symmetric Key by Using the pktool Command Add a plugin to KMF. Installs, modifies, and lists a plugin. Also, removes the plugin from the KMF. How to Manage Third-Party Plugins in KMF This section describes how to use the pktool command to manage your public key objects, such as passwords, passphrases, files, keystores, certificates, and CRLs.pktool commandgencert subcommand gencert subcommandpktool command generatingcertificates with pktool command certificatesgenerating with pktool gencert command pktool commandcreating self-signed certificate KMFcreatingself-signed certificate user procedurescreating self-signed certificate This procedure creates a self-signed certificate and stores the certificate in the PKCS #11 keystore. As a part of this operation, an RSA public/private key pair is also created. The private key is stored in the keystore with the certificate. Generate a self-signed certificate.% pktool gencert [keystore=keystore] label=label-name \ subject=subject-DN serial=hex-serial-numberkeystore=keystoreSpecifies the keystore by type of public key object. The value can be nss, pkcs11, or ssl. This keyword is optional. label=label-nameIs a unique name that the issuer gives to the certificate. subject=subject-DNIs the distinguished name for the certificate. serial=hex-serial-numberIs the serial number in hexadecimal format. The issuer of the certificate chooses the number, such as 0x0102030405. keystoreslisting contentslistingcontents of keystorepktool commandlist subcommandlist subcommandpktool commandVerify the contents of the keystore.% pktool list Found number certificates. 1. (X.509 certificate) Label: label-name ID: Fingerprint that binds certificate to private key Subject: subject-DN Issuer: distinguished-name Serial: hex-serial-number n. ...This command lists all certificates in the keystore. In the following example, the keystore contains one certificate only. In the following example, a user at My Company creates a self-signed certificate and stores the certificate in a keystore for PKCS #11 objects. The keystore is initially empty. If the keystore has not been initialized, the PIN for the softtoken is changeme.% pktool gencert keystore=pkcs11 label="My Cert" \ subject="C=US, O=My Company, OU=Security Engineering Group, CN=MyCA" \ serial=0x000000001 Enter pin for Sun Software PKCS#11 softtoken:Type PIN for token% pktool list Found 1 certificates. 1. (X.509 certificate) Label: My Cert ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Serial: 0x01 pktool commandimport subcommand import subcommandpktool command certificatesimporting into keystore KMFimporting certificates into keystore keystoresimporting certificates user proceduresimporting certificates This procedure describes how to import a file with PKI information that is encoded with PEM or with raw DER into your keystore. For an export procedure, see Example 15–4. Import the certificate.% pktool import keystore=keystore infile=infile-name label=label-name If you are importing private PKI objects, provide passwords when prompted.At the prompt, provide the password for the file.If you are importing PKI information that is private, such as an export file in PKCS #12 format, the file requires a password. The creator of the file that you are importing provides you with the PKCS #12 password.Enter password to use for accessing the PKCS12 file:Type PKCS #12 password At the prompt, type the password for your keystore.Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token Verify the contents of the keystore.% pktool list Found number certificates. 1. (X.509 certificate) Label: label-name ID: Fingerprint that binds certificate to private key Subject: subject-DN Issuer: distinguished-name Serial: hex-serial-number 2. ... In the following example, the user imports a PKCS #12 file from a third party. The pktool import command extracts the private key and the certificate from the gracedata.p12 file, and stores them in the user's preferred keystore.% pktool import keystore=pkcs11 infile=gracedata.p12 label=GraceCert Enter password to use for accessing the PKCS12 file:Type PKCS #12 password Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token Found 1 certificate(s) and 1 key(s) in gracedata.p12 % pktool list Found 1 certificates. 1. (X.509 certificate) Label: GraceCert ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Serial: 0x01 In the following example, the user imports an X.509 certificate in PEM format into the user's preferred keystore. This public certificate is not protected with a password. The user's public keystore is also not protected by a password.% pktool import keystore=pkcs11 infile=somecert.pem label="TheirCompany Root Cert" % pktool list Found 1 certificates. 1. (X.509 certificate) Label: TheirCompany Root Cert ID: 21:ae:83:98:24:d1:1f:cb:65:5b:48:75:7d:02:47:cf:98:1f:ec:a0 Subject: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA Issuer: C=US, O=TheirCompany, OU=Security, CN=TheirCompany Root CA Serial: 0x01 pktool commandexport subcommand export subcommandpktool command certificatesexporting for use by another system KMFexporting certificates keystoresexporting certificates user proceduresexporting certificates You can create a file in PKCS #12 format to export private keys and their associated X.509 certificate to other systems. Access to the file is protected by a password. Find the certificate to export.% pktool list Found number certificates. 1. (X.509 certificate) Label: label-name ID: Fingerprint that binds certificate to private key Subject: subject-DN Issuer: distinguished-name Serial: hex-serial-number 2. ... Export the keys and certificate.Use the keystore and label from the pktool list command. Provide a file name for the export file. When the name contains a space, surround the name with double quotes.% pktool export keystore=keystore outfile=outfile-name label=label-name Protect the export file with a password.At the prompt, type the current password for the keystore. At this point, you create a password for the export file. The receiver must provide this password when importing the file.Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token Enter password to use for accessing the PKCS12 file:Create PKCS #12 passwordSend the password separately from the export file. Best practice suggests that you provide the password out of band, such as during a telephone call. protectingcontents of keystorepasswordsprotectingkeystorepasswordsprotectingPKCS #12 filePKCS #12 filesprotectingfilesPKCS #12In the following example, a user exports the private keys with their associated X.509 certificate into a standard PKCS #12 file. This file can be imported into other keystores. The PKCS #11 password protects the source keystore. The PKCS #12 password is used to protect private data in the PKCS #12 file. This password is required to import the file.% pktool list Found 1 certificates. 1. (X.509 certificate) Label: My Cert ID: 12:82:17:5f:80:78:eb:44:8b:98:e3:3c:11:c0:32:5e:b6:4c:ea:eb Subject: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Issuer: C=US, O=My Company, OU=Security Engineering Group, CN=MyCA Serial: 0x01% pktool export keystore=pkcs11 outfile=mydata.p12 label="My Cert" Enter pin for Sun Software PKCS#11 softtoken: Type PIN for token Enter password to use for accessing the PKCS12 file:Create PKCS #12 passwordThe user then telephones the recipient and provides the PKCS #12 password. pktool commandsetpin subcommand setpin subcommandpktool command generatingpassphrases with pktool command passphrasesgenerating in KMF KMFcreatingpassword for keystore keystoresprotecting with password in KMF user proceduresgenerating passphrase for keystore You can generate a passphrase for an object in a keystore, and for the keystore itself. The passphrase is required to access the object or keystore. For an example of generating a passphrase for an object in a keystore, see Example 15–4. Generate a passphrase for access to a keystore.% pktool setpin keystore=nss|pkcs11 dir=directory Answer the prompts.If the keystore does not have a password already set, press the Return key to create the password.Enter current token passphrase:Press the Return key Create new passphrase:Type the passphrase that you want to use Re-enter new passphrase:Retype the passphrase Passphrase changed.The keystore is now protected by passphrase. If you lose the passphrase, you lose access to the objects in the keystore. The following example shows how to set the passphrase for an NSS database. Because no passphrase has been created, the user presses the Return key at the first prompt.% pktool setpin keystore=nss dir=/var/nss Enter current token passphrase:Press the Return key Create new passphrase: has8n0NdaH Re-enter new passphrase: has8n0NdaH Passphrase changed. kmfcfg commandlist plugin subcommand list plugin subcommandkmcfg command addingplugins to KMF pluginsadding to KMF removingplugins from KMF pluginsremoving from KMF KMFadding plugin KMFlisting plugins KMFremoving plugin user proceduresadding plugins to KMF You identify your plugin by giving it a keystore name. When you add the plugin to KMF, the software identifies it by its keystore name. The plugin can be defined to accept an option. This procedure includes how to remove the plugin from KMF. Install the plugin.% /usr/bin/kmfcfg install keystore=keystore-name \ modulepath=path-to-plugin [option="option-string"]wherekeystore-name – Is a unique name for the keystore that you provide.path-to-plugin – Is the full path to the shared library object for the KMF plugin.option-string – Is an optional argument to the shared library object. List the plugins.% kmfcfg list plugin keystore-name:path-to-plugin [(built-in)] | [;option=option-string] To remove the plugin, uninstall it and verify its removal.% kmfcfg uninstall keystore=keystore-name % kmfcfg plugin list In the following example, the administrator stores a KMF plugin in a site-specific directory. The plugin is defined to accept a debug option. The administrator adds the plugin and verifies that the plugin is installed.# /usr/bin/kmfcfg install keystore=mykmfplug \ modulepath=/usr/lib/security/site-modules/mykmfplug.so # kmfcfg list plugin KMF plugin information: ----------------------- pkcs11:kmf_pkcs11.so.1 (built-in) file:kmf_openssl.so.1 (built-in) nss:kmf_nss.so.1 (built-in) mykmfplug:/usr/lib/security/site-modules/mykmfplug.so # kmfcfg modify plugin keystore=mykmfplug option="debug" # kmfcfg list plugin KMF plugin information: ----------------------- ... mykmfplug:/usr/lib/security/site-modules/mykmfplug.so;option=debugThe plugin now runs in debugging mode.