Description

openssl

- OpenSSL cryptographic and Secure Sockets Layer toolkit

OpenSSL is a cryptography toolkit that implements the Secure Sockets Layer (SSLv2/v3) and Transport Layer Security (TLS v1) network protocols.

The following features are omitted from the binaries for issues including but not limited to patents, trademark, and US export restrictions: ECC, IDEA, MDC2, RC3, RC5, 4758_CCA Engine, AEP Engine, Atalla Engine, CHIL Engine, CSWIFT Engine, GMP Engine, NURON Engine, PadLock Engine, Sureware Engine, and UBSEC Engine.

The PKCS#11 Engine

A new PKCS#11 engine has been included with ENGINE name pkcs11. The engine was developed in Sun and is not integrated in the OpenSSL project.

The PKCS#11 engine is configured to use the Oracle Solaris Cryptographic Framework. See cryptoadm(1M) for configuration information.

The PKCS#11 engine can support the following set of mechanisms: CKM_AES_CBC, CKM_AES_ECB, CKM_BLOWFISH_CBC, CKM_DES_CBC, CKM_DES_ECB, CKM_DES3_CBC, CKM_DES3_ECB, CKM_DSA, CKM_MD5, CKM_RC4, CKM_RSA_PKCS, CKM_RSA_X_509, CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512, CKM_SHA224_HMAC, CKM_SHA224_HMAC_GENERAL, and CKM_SHA224_KEY_DERIVATION.

The set of mechanisms available depends on installed Crypto Framework providers. To see what mechanisms can be offloaded to the Cryptographic Framework through the PKCS#11 engine on a given machine, run the following command:

/usr/sfw/bin/openssl engine pkcs11 -vvv -t -c

Due to requirements of the PKCS#11 standard regarding fork(2) behavior, some applications that use the OpenSSL EVP interfaces and fork() with active crypto contexts might experience unexpected behavior.

The Dynamic Engine Support

The dynamic engine support has been enabled, which allows an external engine, in the form of a shared library, to be dynamically bound and used by an OpenSSL-based application.

Run the following command to see if the dynamic engine is supported:

$openssl engine dynamic
(dynamic) Dynamic engine loading support

The `devcrypto` Engine

This engine is implemented as a separate shared library, and it can be used by an OpenSSL application through the OpenSSL dynamic engine support. This engine was developed in Sun and is not integrated in the OpenSSL project.

Files for the devcrypto engine library are:

/lib/openssl/engines/libdevcrypto.so 
/lib/openssl/engines/64/libdevcrypto.so

The devcrypto engine accesses only the kernel hardware providers from the Oracle Solaris Cryptographic Framework. To see the hardware provider information on a system, use the cryptoadm(1M) command.

The devcrypto engine supports the following set of mechanisms: CKM_AES_CBC, CKM_AES_CTR, CKM_AES_ECB, CKM_BLOWFISH_CBC, CKM_DES_CBC, CKM_DES_ECB, CKM_DES3_CBC, CKM_DES3_ECB, and CKM_RC4.

The set of mechanisms available depends on hardware providers installed and enabled in the Cryptographic Framework. To see what mechanisms are supported by the devcrypto engine on a particular machine, run the following command:

$openssl engine dynamic -pre SO_PATH:/lib/openssl/engines/libdevcrypto.so\
-pre LOAD -t -c

Using FIPS Mode

Currently a FIPS-140 certified mode is not available in Oracle Solaris.

Building an OpenSSL Application

To build an OpenSSL application, use the following cc command line options:

cc [ flag... ] file... -lcrypto -lssl [ library... ]

Accessing RSA Keys in PKCS#11 Keystores

OpenSSL can access RSA keys in PKCS#11 keystores using the following functions of the ENGINE API:

EVP_PKEY *ENGINE_load_private_key(ENGINE *e,
 const char *key_id, UI_METHOD *ui_method,
 void *callback_data)

EVP_PKEY *ENGINE_load_public_key(ENGINE *e,
 const char *key_id, UI_METHOD *ui_method,
 void *callback_data)

key_id, formerly for filenames only, can be now also set to a PKCS#11 URI. The EVP_PKEY structure is newly allocated and caller is responsible to free the structure later. To avoid clashes with existing filenames, file:// prefix for filenames is now also accepted but only when the PKCS#11 engine is in use. The PKCS#11 URI specification follows:

pkcs11:[token=<label>][:manuf=<label>][;serial=<label>]
   [;model=<label>][;object=<label>]
   [;objecttype=(public|private|cert)]
   [;passphrasedialog=(builtin|exec:<file>)]

The ordering of keywords is not significant. The PKCS#11 engine uses the keystore for the slot chosen for public key operations, which is metaslot on a standard configured machine. Currently, the PKCS#11 engine ignores the objecttype keyword. The only mandatory keyword is object which is the key object label. For information on how to use a different, possibly hardware, keystore with metaslot, seelibpkcs11(3LIB).

The token PIN is provided by way of the passphrasedialog keyword and is either read from the terminal (builtin) or from the output of an external command (exec:<file>). The PIN is used to log into the token and by default is deleted from the memory then. The keyword pin is intentionally not provided due to inherent security problems of possible use of a password in the process arguments.

Due to fork safety issues the application must re-login if the child continues to use the PKCS#11 engine. It is done inside of the engine automatically if fork is detected and in that case, exec:<file> option of the passphrasedialog keyword can be used. Alternatively, an environment variable OPENSSL_PKCS11_PIN_CACHING_POLICY can be used to allow the PIN to be cached in memory and reused in the child. It can be set to none which is the default, memory to store the PIN in memory, and mlocked-memory to keep the PIN in a locked page using mlock(3C). PRIV_PROC_LOCK_MEMORY privilege is required in that case.

Sensitive parts of private keys are never read from the token to the process memory no matter whether the key is tagged with sensitive flag or not. The PKCS#11 engine uses the public components as a search key to get a PKCS#11 object handle to the private key.

To use the RSA keys by reference, high level API functions such as RSA_public_decrypt(), EVP_PKEY_set1_RSA(), or EVP_SignInit() must be used. Low level functions might go around the engine and fail to make use of the feature.

Additional Documentation

Extensive additional documentation for OpenSSL modules is available in the /usr/share/man/man1openssl, /usr/share/man/man3openssl, /usr/share/man/man5openssl, and /usr/share/man/man7openssl directories.

To view the license terms, attribution, and copyright for OpenSSL, run pkg info --license library/security/openssl.

Examples

Example 1 Generating and Printing a Public Key

The following example generates and prints a public key stored in an already initilized PKCS#11 keystore. Notice the use of -engine pkcs11 and -inform e.

$ pktool gencert keystore=pkcs11 label=mykey \
   subject="CN=test" keytype=rsa keylen=1024 serial=01
$ openssl rsa -in "pkcs11:object=mykey;passphrasedialog=builtin"\
   -pubout -text -engine pkcs11 -inform e

Attributes

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	library/security/openssl, library/security/openssl
Interface Stability	Volatile

Skip Navigation Links
Exit Print View
	man pages section 5: Standards, Environments, and Macros Oracle Solaris 11.1 Information Library