openssl(5) Standards, Environments, and Macros openssl(5)NAMEopenssl - OpenSSL cryptographic and Secure Sockets Layer toolkit
DESCRIPTION
OpenSSL is a cryptography toolkit that implements the Secure Sockets
Layer (SSLv2/v3) and Transport Layer Security (TLS v1) network proto‐
cols.
The following features are omitted from the binaries for issues includ‐
ing but not limited to patents, trademark, and US export restrictions:
ECC, IDEA, MDC2, RC3, RC5, Dynamic Engine Loading, 4758_CCA Engine, AEP
Engine, Atalla Engine, CHIL Engine, CSWIFT Engine, GMP Engine, NURON
Engine, PadLock Engine, Sureware Engine, and UBSEC 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 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, and
CKM_SHA512.
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 fol‐
lowing command:
/usr/sfw/bin/openssl engine -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.
Using FIPS Mode
A FIPS Capable OpenSSL is available in /lib/openssl/fips-140. To use
this version of OpenSSL on a per-application basis, LD_LIBRARY_PATH can
be set. crle(1) can be used to select this version of OpenSSL for all
applications.
Example:
# crle -a /lib/libcrypto.so.0.9.8 -o \
/lib/openssl/fips-140
# crle -64 -a /lib/64/libcrypto.so.0.9.8 -o \
/lib/openssl/fips-140/64
The FIPS Capable libcrypto and the non-FIPS Capable libcrypto are ABI
compatible. One exception to this is the use of the CRYPTO_NUM_LOCKS
preprocessor macro. Instead of using CRYPTO_NUM_LOCKS, the
CRYPTO_num_locks(3openssl) function should be used instead.
Even when a FIPS Capable OpenSSL is used applications cannot automati‐
cally claim FIPS compliance. See the OpenSSL FIPS 140-2 User Guide at
http://openssl.org/ for more information.
openssl(1openssl) can be run in FIPS mode. The environmental variable,
OPENSSL_FIPS, must be set and the FIPS Capable OpenSSL libraries must
be used.
Example:
# export LD_LIBRARY_PATH=/lib/openssl/fips-140
# export OPENSSL_FIPS=1
# openssl version
OpenSSL 0.9.8k-fips 25 Mar 2009 (security fixes for: CVE-
2009-1377 CVE-2009-1378 CVE-2009-1379)
Building an OpenSSL Application
To build an OpenSSL application, use the following cc command line
options:
cc [ flag... ] file... -lcrypto -lssl [ library... ]
To build an OpenSSL application which supports a FIPS mode of opera‐
tion, use the following cc command line options:
cc -I/usr/include/openssl/fips-140 -L/lib/openssl/fips-140 \
[ 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 responsi‐
ble to free the structure later. To avoid clashes with existing file‐
names, 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, seelibp‐
kcs11(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 exter‐
nal 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 intention‐
ally 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 environ‐
ment 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, see
/var/sadm/pkg/SUNWopensslr/install/copyright.
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 │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcrle(1), cryptoadm(1M), libpkcs11(3LIB), attributes(5), privileges(5)
/usr/share/man/man1openssl/openssl.1openssl,
/usr/share/man/man1openssl/CRYPTO_num_locks.3openssl,
/usr/share/man/man3openssl/engine.3, /usr/share/man/man3openssl/evp.3
OpenSSL FIPS 140-2 User Guide at http://openssl.org/
SunOS 5.11 23 Nov 2009 openssl(5)
