Developer's Guide to Oracle Solaris Security

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.

ProcedureTo 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.

  1. Request a certificate from Oracle 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 cryptographic framework. The directory should be secure. Use a different directory from the directory that holds the Oracle certificate.

    certificate-request

    Path to the certificate request.

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


    % 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  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.

  2. Submit the certificate request to Oracle.

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

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

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

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

ProcedureTo 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.

  1. Sign the provider. Use the elfsign sign command, the certificate from Oracle, and the private key for requesting certificates from Oracle.


    % elfsign sign -k private-keyfile -c Oracle-certificate -e provider-object
    
    -k

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

    -c

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

    -e

    Path to the provider, or binary, to be signed for use within the 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.

ProcedureTo Verify That a Provider Is Signed

  1. Collect the certificate that Oracle issued and the path to the signed provider.

  2. 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.

ProcedureTo 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.

  1. Sign the provider. Use the elfsign sign command, the certificate from Oracle, and the private key for requesting certificates from Oracle.


    % elfsign sign -a -k private-keyfile -c Oracle-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 Oracle Corporation.

    -c

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

    -e

    Path to the provider, or binary, to be signed for use within the 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