Oracle Solaris Security for Developers Guide

Appendix F Packaging and Signing Cryptographic Providers

This appendix describes how to package Solaris cryptographic provider applications and modules. The following topics are covered:

Packaging Cryptographic Provider Applications and Modules

In the Solaris operating system, application software is delivered in units that are called packages. A package is a collection of files that are required for the distribution and installation of a software product. Packages are usually designed and built by the application developer after the development of the application code is complete. For general information about packaging software applications, see Application Packaging Developer’s Guide.

Packaging a cryptographic provider has two additional requirements:

The developer must supply input files that add the application to the configuration files that manage the cryptographic framework.
The developer must supply an X.509 certificate to indicate compliance with the United States government's export laws. For testing purposes, the certificate can be generated prior to obtaining U.S. government approval. A package must have approval and a signed provider to be shipped.

Complying with U.S. Government Export Laws

The United States government restricts the export of open cryptographic interfaces, which are also referred to as crypto-with-a-hole. Due to this restriction, all vendors of providers must obtain export approval from the U.S. government. The vendor needs to request a certificate from Sun Microsystems, Inc. to indicate compliance with export laws. The vendor then signs the provider electronically and ships the software with the certificate.

In the export approval process, the strength of your encryption determines the countries in which the software can be used. The U.S. government defines two export categories for encryption products that are manufactured in the U.S.A.:

Retail encryption products – Retail encryption products are permitted to be shipped to all countries except for designated nations that are considered to be security threats.
Non-retail encryption products – Non-retail encryption products are permitted for domestic use only and to countries that have been exempted by the U.S. government.

If your provider has non-retail approval, you can make the provider eligible for retail approval. Retail approval can be obtained by disabling the use of your provider by certain callers such as IPsec. Sun provides two different certificates in this case, for restricted and unrestricted use. You indicate this situation in the certificate request process, To Request a Certificate for Signing a Provider. In addition, a special activation file must be generated, signed, and shipped with the provider. See To Generate an Activation File for Retail Export.

Packaging User-Level Provider Applications

A third-party developer of a user-level cryptographic provider application completes the following process:

Acquire a certificate from Sun Microsystems, Inc. Then, sign the library. See Adding Signatures to Providers.
Ship the certificate with the package. The certificate must be placed in the /etc/crypto/certs directory.
Add the pkcs11conf class into the CLASSES string of the pkginfo file. The following line should be added:
```
CLASS=none pkcs11conf
```
Create an input file pkcs11.conf in the etc/crypto directory.

The input file for user-level providers is named pkcs11.conf. This file specifies the path to the provider. The pkcs11.conf uses the following syntax for the entry:
```
filename
```
The entry is an absolute path to a file such as /opt/lib/$ISA/myProviderApp.so. This file is added to the configuration file when pkgadd is run. Note the $ISA expression in the path name. $ISA points to either a 32-bit version or a 64-bit version of the application, as needed.
Add the following line to the package's prototype file:
```
e pkcs11conf etc/crypto/pkcs11conf 0644 root sys
```

Packaging Kernel-Level Provider Modules

A third-party developer of a kernel-level cryptographic provider module completes the following process:

Acquire a certificate from Sun Microsystems, Inc. Then, sign the kernel software module or device driver. See Adding Signatures to Providers.
Ship the certificate with the package. The certificate should be placed in the /etc/crypto/certs directory.
Add the kcfconf class into the CLASSES string of the pkginfo file. The following line should be added:
```
CLASS=none kcfconf
```
Create an input file kcf.conf in the etc/crypto directory. This file is used to add software and hardware plug-ins to the kernel configuration file.
- If the provider is a kernel software module with cryptographic mechanisms, use the following syntax for the entry:
```
provider-name:supportedlist=mech1,mech2,...
```
  provider-name
  
  Base name for the kernel software module
  
  mech*
  
  Name of the cryptographic mechanism in the list
  
  The following entry is an example of a kernel software module:
```
des:supportedlist=CKM_DES_CBC,CKM_DES_ECB,CKM_DES_CFB
```
- If the provider is a device driver for cryptographic mechanisms, such as an accelerator card, then use the following syntax for the entry:
```
driver_names=devicedriver1,devicedriver2,...
```
  devicedriver*
  
  Name of a device driver for a cryptographic device.
  
  The following entry is an example of a device driver:
```
driver_names=dca
```

Adding Signatures to Providers

This section describes how to add a digital signature to a provider so that the provider can work within the framework. The section also describes how to verify that a provider has been properly signed. Providers can be one of the following objects: a PKCS #11 library, a loadable kernel module that implements an algorithm, or a device driver for a hardware accelerator.

To Request a Certificate for Signing a Provider

Typically, the developer of a provider requests the certificate. However, the system administrator might be called on to handle the request as part of a site's security policy.

Request a certificate from Sun by using the elfsign request command.

The command generates a private key along with the certificate request.

% elfsign request -k private-keyfile -r certificate-request

private-keyfile: Path to the location of the private key. This key is needed later when the system administrator signs providers for the Solaris cryptographic framework. The directory should be secure. Use a different directory from the directory that holds the Sun certificate.
certificate-request: Path to the certificate request.

The following example shows how a typical request is submitted to Sun:

% elfsign request \
-k /securecrypt/private/MyCompany.private.key \
-r /reqcrypt/MyCompany.certrequest

Enter Company Name / Stock Symbol or some other globally unique identifier.
This will be the prefix of the Certificate DN:MYCORP

The government of the United States of America restricts the export of 
"open cryptographic interfaces", also known as "crypto-with-a-hole".
Due to this restriction, all providers for the Solaris cryptographic
framework must be signed, regardless of the country of origin.

The terms "retail" and "non-retail" refer to export classifications 
for products manufactured in the USA.  These terms define the portion of the
world where the product may be shipped.  Roughly speaking, "retail" is 
worldwide (minus certain excluded nations) and "non-retail" is domestic 
only (plus some highly favored nations).  If your provider is subject to
USA export control, then you must obtain an export approval (classification)
from the government of the USA before exporting your provider.  It is
critical that you specify the obtained (or expected, when used during 
development) classification to the following questions so that your provider
will be appropriately signed.

Do you have retail export approval for use without restrictions based
on the caller (for example, IPsec)? [Yes/No] N

If you have non-retail export approval for unrestricted use of your
provider by callers, are you also planning to receive retail approval
restricting which export sensitive callers (for example, IPsec) may
use your provider? [Y/N] Y

The private key is placed in the file name that you specify, for example, /etc/crypto/private/MyCompany.private.key file. The certificate request is also placed in a file name that you specify, for example, /reqcrypt/MyCompany.certrequest file.

Submit the certificate request to Sun.

Send the certificate request to the following email address: solaris-crypto-req@sun.com

Sun generates a certificate from your certificate request file. A copy of the certificate is sent back to you.

Store the certificate that you receive from Sun in the /etc/crypto/certs directory.

For security, the private key and the certificate request should be stored in other directories.

To Sign a Provider

Typically, the developer of the provider signs the provider. However, the system administrator might be called on to sign the developer's binary as part of your site security policy.

Sign the provider. Use the elfsign sign command, the certificate from Sun, and the private key for requesting certificates from Sun.
% elfsign sign -k private-keyfile -c Sun-certificate -e provider-object
-k

File that contains that private key that was used to generate the certificate request that was sent to Sun.

-c

Path to the certificate from Sun that was issued from the certificate request.

-e

Path to the provider, or binary, to be signed for use within the Solaris cryptographic framework.

The following example shows how to sign a provider.
% elfsign sign \ -k /securecrypt/private/MyCompany.private.key \ -c /etc/crypto/certs/MyCompany -e /path/to/provider.object
Note that using elfsign sign changes the object in the location that was specified. If an unsigned version of the object is needed, then the object should be copied to a different location before elfsign sign is applied.

To Verify That a Provider Is Signed

Collect the certificate that Sun issued and the path to the signed provider.

Verify that the provider is correctly signed by using the elfsign verify command.

The following example demonstrates verification with the assumption that the certificate is in the default directory, /etc/crypto/certs/MyCompany.
% elfsign verify \ -e /path/to/MyProvider.so.1 elfsign: verification of /path/to/MyProvider.so.1 passed
The following example demonstrates storage of the certificate in a non-default directory.
% elfsign verify \ -c /path/to/MyCerts \ -e /path/to/MyProvider.so.1 elfsign: verification of /path/to/MyProvider.so.1 passed
The following example demonstrates verification of a provider that has been signed with a restricted certificate.
% elfsign verify \ -e /path/to/MyRestrictedProvider.so.1 elfsign: verification of /path/to/MyRestrictedProvider.so.1 passed, \ but restricted.

To Generate an Activation File for Retail Export

This procedure is useful for when the same provider is to be shipped for both domestic use and restricted international use. You sign the provider with a key for a usage-restricted certificate for all customers. For those customers who use providers without caller-based restrictions, you generate and include a special activation file that permits use with IPsec. The activation file should reside in the same directory as the provider. The convention for naming the activation file is to combine the name of the driver with the extension .esa, for example, /kernel/drv/vca.esa.

Sign the provider. Use the elfsign sign command, the certificate from Sun, and the private key for requesting certificates from Sun.
% elfsign sign -a -k private-keyfile -c Sun-certificate -e provider-object
-a

Generate a signed ELF Sign Activation (.esa) file. This option is used when a cryptographic provider needs both non-retail export approval and retail approval. The retail approval is accomplished by restricting export-sensitive callers such as IPsec. This option assumes that the provider binary has previously been signed with a restricted certificate.

-k

File that contains that private key that was used to generate the certificate request that was sent to Sun Microsystems, Inc.

-c

Path to the certificate from Sun that was issued from the certificate request.

-e

Path to the provider, or binary, to be signed for use within the Solaris cryptographic framework.

The following example shows how to sign a provider.
% elfsign sign \ -a \ -k /securecrypt/private/MyCompany.private.key \ -c /etc/crypto/certs/MyCompany -e /path/to/provider.object