Administering the Cryptographic Framework

This section describes how to administer the software providers and the hardware providers in the Solaris Cryptographic Framework. Software providers and hardware providers can be removed from use when desirable. For example, you can disable the implementation of an algorithm from one software provider. You can then force the system to use the algorithm from a different software provider.

How to List Available Providers

The Solaris Cryptographic Framework provides algorithms for several types of consumers:

• User-level providers provide a PKCS #11 cryptographic interface to applications that are linked with the libpkcs11 library

• Kernel software providers provide algorithms for IPsec, Kerberos, and other Solaris kernel components

• Kernel hardware providers provide algorithms that are available to kernel consumers and to applications through the pkcs11_kernel library

1. List the providers in a brief format.

   Only those mechanisms at the user level are available for use by regular users.

   % cryptoadm list
   user-level providers:
       /usr/lib/security/$ISA/pkcs11_kernel.so
       /usr/lib/security/$ISA/pkcs11_softtoken.so
   
   kernel software providers:
       des
       aes
       blowfish
       arcfour
       sha1
       md5
       rsa
   
   kernel hardware providers:
       dca/0

2. List the providers and their mechanisms in the Solaris Cryptographic Framework.

   All mechanisms are listed in the following output. However, some of the listed mechanisms might be unavailable for use. To list only the mechanisms that the administrator has approved for use, see Example 14-20.

   The output is reformatted for display purposes.

   % cryptoadm list -m
   user-level providers:
   =====================
   /usr/lib/security/$ISA/pkcs11_kernel.so: CKM_MD5,CKM_MD5_HMAC,
   CKM_MD5_HMAC_GENERAL,CKM_SHA_1,CKM_SHA_1_HMAC,CKM_SHA_1_HMAC_GENERAL,
   …
   /usr/lib/security/$ISA/pkcs11_softtoken.so: 
   CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
   CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
   CKM_AES_CBC,CKM_AES_CBC_PAD,CKM_AES_ECB,CKM_AES_KEY_GEN,
   …
   kernel software providers:
   ==========================
   des: CKM_DES_ECB,CKM_DES_CBC,CKM_DES3_ECB,CKM_DES3_CBC
   aes: CKM_AES_ECB,CKM_AES_CBC
   blowfish: CKM_BF_ECB,CKM_BF_CBC
   arcfour: CKM_RC4
   sha1: CKM_SHA_1,CKM_SHA_1_HMAC,CKM_SHA_1_HMAC_GENERAL
   md5: CKM_MD5,CKM_MD5_HMAC,CKM_MD5_HMAC_GENERAL
   rsa: CKM_RSA_PKCS,CKM_RSA_X_509,CKM_MD5_RSA_PKCS,CKM_SHA1_RSA_PKCS
   swrand: No mechanisms presented.
   
   kernel hardware providers:
   ==========================
   dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC

Example 14-19 Finding the Existing Cryptographic Mechanisms

In the following example, all mechanisms that the user-level library, pkcs11_softtoken, offers are listed.

% cryptoadm list -m provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so:
CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
…
CKM_SSL3_KEY_AND_MAC_DERIVE,CKM_TLS_KEY_AND_MAC_DERIVE

Example 14-20 Finding the Available Cryptographic Mechanisms

Policy determines which mechanisms are available for use. The administrator sets the policy. An administrator can choose to disable mechanisms from a particular provider. The -p option displays the list of mechanisms that are permitted by the policy that the administrator has set.

% cryptoadm list -p
user-level providers:
=====================
/usr/lib/security/$ISA/pkcs11_kernel.so: all mechanisms are enabled.
random is enabled.
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled.
random is enabled.

kernel software providers:
==========================
des: all mechanisms are enabled.
aes: all mechanisms are enabled.
blowfish: all mechanisms are enabled.
arcfour: all mechanisms are enabled.
sha1: all mechanisms are enabled.
md5: all mechanisms are enabled.
rsa: all mechanisms are enabled.
swrand: random is enabled.

kernel hardware providers:
==========================
dca/0: all mechanisms are enabled. random is enabled.

How to Add a Software Provider

1. Assume the Primary Administrator role, or become superuser.

   The Primary Administrator role includes the Primary Administrator profile. To create the role and assign the role to a user, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.

2. List the software providers that are available to the system.

   # cryptoadm list
   user-level providers:
           /usr/lib/security/$ISA/pkcs11_kernel.so
           /usr/lib/security/$ISA/pkcs11_softtoken.so
   
   kernel software providers:
       des
       aes
       blowfish
       arcfour
       sha1
       md5
       rsa
       swrand
   
   kernel hardware providers:
        dca/0

3. Add the provider's package by using the pkgadd command.

   # pkgadd -d /path/to/package pkginst

   The package must include software that has been signed by a certificate from Sun. To request a certificate from Sun and to sign a provider, see Appendix F, Packaging and Signing Cryptographic Providers, in Solaris Security for Developers Guide.

   The package should have scripts that notify the cryptographic framework that another provider with a set of mechanisms is available. For information about the packaging requirements, see Appendix F, Packaging and Signing Cryptographic Providers, in Solaris Security for Developers Guide.

4. Refresh the providers.

   You need to refresh providers if you added a software provider, or if you added hardware and specified policy for the hardware.

   # svcadm refresh svc:/system/cryptosvc

5. Locate the new provider on the list.

   In this case, a new kernel software provider was installed.

   # cryptoadm list 
   …
   kernel software providers:
       des
       aes
       blowfish
       arcfour
       sha1
       md5
       rsa
       swrand
       ecc <-- added provider
   …

Example 14-21 Adding a User-Level Software Provider

In the following example, a signed PKCS #11 library is installed.

# pkgadd -d /cdrom/cdrom0/SolarisNew
Answer the prompts
# svcadm refresh system/cryptosvc
# cryptoadm list
user-level providers:
==========================
    /usr/lib/security/$ISA/pkcs11_kernel.so
    /usr/lib/security/$ISA/pkcs11_softtoken.so
    /opt/SUNWconn/lib/$ISA/libpkcs11.so.1 <-- added provider

Developers who are testing a library with the cryptographic framework can install the library manually.

# cryptoadm install provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1

How to Prevent the Use of a User-Level Mechanism

If some of the cryptographic mechanisms from a library provider should not be used, you can remove selected mechanisms. This procedure uses the DES mechanisms in the pkcs11_softtoken library as an example.

1. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9-7.

2. List the mechanisms that are offered by a particular user-level software provider.

   % cryptoadm list -m provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
   /usr/lib/security/$ISA/pkcs11_softtoken.so:
   CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
   CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
   CKM_AES_CBC,CKM_AES_CBC_PAD,CKM_AES_ECB,CKM_AES_KEY_GEN,
   …

3. List the mechanisms that are available for use.

   $ cryptoadm list -p
   user-level providers:
   =====================
   …
   /usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled.
   random is enabled.
   …

4. Disable the mechanisms that should not be used.

   $ cryptoadm disable provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so \
   > mechanism=CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB

5. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
   /usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled,
   except CKM_DES_ECB,CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.

Example 14-22 Enabling a User-Level Software Provider Mechanism

In the following example, a disabled DES mechanism is again made available for use.

$ cryptoadm list -m provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so:
CKM_DES_CBC,CKM_DES_CBC_PAD,CKM_DES_ECB,CKM_DES_KEY_GEN,
CKM_DES3_CBC,CKM_DES3_CBC_PAD,CKM_DES3_ECB,CKM_DES3_KEY_GEN,
…
$ cryptoadm list -p provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled,
except CKM_DES_ECB,CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.
$ cryptoadm enable provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so \
> mechanism=CKM_DES_ECB
$ cryptoadm list -p provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled,
except CKM_DES_CBC_PAD,CKM_DES_CBC. random is enabled.

Example 14-23 Enabling All User-Level Software Provider Mechanisms

In the following example, all mechanisms from the user-level library are enabled.

$ cryptoadm enable provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so all
$ cryptoadm list -p provider=/usr/lib/security/'$ISA'/pkcs11_softtoken.so
/usr/lib/security/$ISA/pkcs11_softtoken.so: all mechanisms are enabled.
random is enabled.

Example 14-24 Permanently Removing User-Level Software Provider Availability

In the following example, the libpkcs11.so.1 library is removed.

$ cryptoadm uninstall provider=/opt/SUNWconn/lib/'$ISA'/libpkcs11.so.1
$ cryptoadm list
user-level providers:
    /usr/lib/security/$ISA/pkcs11_kernel.so
    /usr/lib/security/$ISA/pkcs11_softtoken.so

kernel software providers:
…

How to Prevent the Use of a Kernel Software Provider

If the cryptographic framework provides multiple modes of a provider such as AES, you might remove a slow mechanism from use, or a corrupted mechanism. This procedure uses the AES algorithm as an example.

1. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9-7.

2. List the mechanisms that are offered by a particular kernel software provider.

   $ cryptoadm list -m provider=aes
   aes: CKM_AES_ECB,CKM_AES_CBC

3. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=aes
   aes: all mechanisms are enabled.

4. Disable the mechanism that should not be used.

   $ cryptoadm disable provider=aes mechanism=CKM_AES_ECB

5. List the mechanisms that are available for use.

   $ cryptoadm list -p provider=aes
   aes: all mechanisms are enabled, except CKM_AES_ECB.

Example 14-25 Enabling a Kernel Software Provider Mechanism

In the following example, a disabled AES mechanism is again made available for use.

cryptoadm list -m provider=aes
aes: CKM_AES_ECB,CKM_AES_CBC
$ cryptoadm list -p provider=aes
aes: all mechanisms are enabled, except CKM_AES_ECB.
$ cryptoadm enable provider=aes mechanism=CKM_AES_ECB
$ cryptoadm list -p provider=aes
aes: all mechanisms are enabled.

Example 14-26 Temporarily Removing Kernel Software Provider Availability

In the following example, the AES provider is temporarily removed from use. The unload subcommand is useful to prevent a provider from being loaded automatically while the provider is being uninstalled. For example, the unload subcommand would be used when installing a patch that affects the provider.

$ cryptoadm unload provider=aes
$ cryptoadm list
...
kernel software providers:
         des
         aes (inactive)
         blowfish
         arcfour
         sha1
         md5
         rsa
         swrand

The AES provider is unavailable until the cryptographic framework is refreshed.

$ svcadm refresh system/cryptosvc
$ cryptoadm list
...
kernel software providers:
         des
         aes
         blowfish
         arcfour
         sha1
         md5
         rsa
         swrand

If a kernel consumer is using the kernel software provider, the software is not unloaded. An error message is displayed and the provider continues to be available for use.

Example 14-27 Permanently Removing Software Provider Availability

In the following example, the AES provider is removed from use. Once removed, the AES provider does not appear in the policy listing of kernel software providers.

$ cryptoadm uninstall provider=aes
$ cryptoadm list
…
kernel software providers:
         des
         blowfish
         arcfour
         sha1
         md5
         rsa
         swrand

If a kernel consumer is using the kernel software provider, an error message is displayed and the provider continues to be available for use.

Example 14-28 Reinstalling a Removed Kernel Software Provider

In the following example, the AES kernel software provider is reinstalled.

$ cryptoadm install provider=aes mechanism=CKM_AES_ECB,CKM_AES_CBC
$ cryptoadm list
…
kernel software providers:
         des
         aes
         blowfish
         arcfour
         sha1
         md5
         rsa
         swrand

How to List Hardware Providers

Hardware providers are automatically located and loaded. For more information, see driver.conf(4) man page.

Before You Begin

When you add hardware that expects to be used within the Solaris Cryptographic Framework, the hardware registers with the SPI in the kernel. The framework checks that the hardware driver is signed. Specifically, the framework checks that the object file of the driver is signed with a certificate that Sun issues.

1. List the hardware providers that are available on the system.

   % cryptoadm list
   … 
   kernel hardware providers:
      dca/0

2. List the mechanisms that the board provides.

   % cryptoadm list -m provider=dca/0
   dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC

3. List the mechanisms that are available for use on the board.

   % cryptoadm list -p provider=dca/0
   dca/0: all mechanisms are enabled. random is enabled.

How to Disable Hardware Provider Mechanisms and Features

You can selectively disable mechanisms and the random number feature from a hardware provider. To enable them again, see Example 14-29.

1. List the mechanisms and features that are available from the board.

   % cryptoadm list -p provider=dca/0
   dca/0: all mechanisms are enabled. random is enabled.

2. Become superuser or assume a role that includes the Crypto Management rights profile.

   To create a role that includes the Crypto Management rights profile and assign the role to a user, see Example 9-7.

3. Choose the mechanisms or feature to disable:
   • Disable selected mechanisms.

     # cryptoadm list -m provider=dca/0
     dca/0: CKM_RSA_PKCS, CKM_RSA_X_509, CKM_DSA, CKM_DES_CBC, CKM_DES3_CBC
     random is enabled.
     # cryptoadm disable provider=dca/0 mechanism=CKM_DES_CBC,CKM_DES3_CBC
     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are enabled except CKM_DES_CBC,CKM_DES3_CBC.
     random is enabled.

   • Disable the random number generator.

     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are enabled. random is enabled.
     # cryptoadm disable provider=dca/0 random
     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are enabled. random is disabled.

   • Disable all mechanisms. Do not disable the random number generator.

     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are enabled. random is enabled.
     # cryptoadm disable provider=dca/0 mechanism=all
     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are disabled. random is enabled.

   • Disable every feature and mechanism on the hardware.

     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are enabled. random is enabled.
     # cryptoadm disable provider=dca/0 all
     # cryptoadm list -p provider=dca/0
     dca/0: all mechanisms are disabled. random is disabled.

Example 14-29 Enabling Mechanisms and Features on a Hardware Provider

In the following examples, disabled mechanisms on a piece of hardware are selectively enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled except CKM_DES_ECB,CKM_DES3_ECB.
random is enabled.
# cryptoadm enable provider=dca/0 mechanism=CKM_DES3_ECB
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled except CKM_DES_ECB. random is enabled.

In the following example, only the random generator is enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,…. 
random is disabled.
# cryptoadm enable provider=dca/0 random
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,….
random is enabled.

In the following example, only the mechanisms are enabled. The random generator continues to be disabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_MD5,CKM_MD5_HMAC,…. 
random is disabled.
# cryptoadm enable provider=dca/0 mechanism=all
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled. random is disabled.

In the following example, every feature and mechanism on the board is enabled.

# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled, except CKM_DES_ECB,CKM_DES3_ECB.
random is disabled.
# cryptoadm enable provider=dca/0 all
# cryptoadm list -p provider=dca/0
dca/0: all mechanisms are enabled. random is enabled.

How to Refresh or Restart All Cryptographic Services

By default, the Solaris Cryptographic Framework is enabled. When the kcfd daemon fails for any reason, the service management facility can be used to restart cryptographic services. For more information, see the smf(5) and svcadm(1M) man pages. For the effect on zones of restarting cryptographic services, see Cryptographic Services and Zones.

1. Check the status of cryptographic services.

   % svcs \*cryptosvc\*
    STATE          STIME    FMRI
   offline         Dec_09   svc:/system/cryptosvc:default

2. Become superuser or assume an equivalent role to enable cryptographic services.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map).

   # svcadm enable svc:/system/cryptosvc

Example 14-30 Refreshing Cryptographic Services

In the following example, cryptographic services are refreshed in the global zone. Therefore, kernel-level cryptographic policy in every non-global zone is also refreshed.

# svcadm refresh system/cryptosvc