openssl - OpenSSL cryptographic and Secure Sockets Layer toolkit
Please see following description for synopsis
Standards, Environments, and Macros openssl(7)
NAME
openssl - OpenSSL cryptographic and Secure Sockets Layer toolkit
DESCRIPTION
OpenSSL is a cryptography toolkit that implements the Transport Layer
Security (TLS v1) network protocols. This version of OpenSSL no longer
supports the Secure Sockets Layer (SSLv2/v3) network protocols.
The following features are omitted from the binaries for issues includ-
ing but not limited to patents, trademark, and US export restrictions:
IDEA, MDC2, RC3, RC5, 4758_CCA Engine, AEP Engine, Atalla Engine, CAPI
Engine, CHIL Engine, CSWIFT Engine, GMP Engine, GOST Engine, NURON
Engine, PadLock Engine, Sureware Engine, and UBSEC Engine.
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 PKCS#11 Engine
The PKCS#11 engine has been included with the ENGINE name pkcs11. The
engine was developed within Oracle and is not integrated in the OpenSSL
project.
The PKCS#11 engine is a dynamic engine, and it is configured to use the
Oracle Solaris Cryptographic Framework. See cryptoadm(8) for configura-
tion information.
The PKCS#11 engine can support the following set of mechanisms:
AES-128-CBC, AES-192-CBC, AES-256-CBC, AES-128-CTR, AES-192-CTR,
AES-256-CTR, AES-128-ECB, AES-192-ECB, AES-256-ECB, BF-CBC, DES-CBC,
DES-ECB, DES-EDE3, DES-EDE3-CBC, DH, DSA, MD5, RAND, RC4, RSA, SHA1,
SHA224, SHA256, SHA384 and 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/bin/openssl engine dynamic -pre SO_PATH:/lib/openssl/engines/64/libpk11.so -pre LOAD -t -c
In order to verify the use of the PKCS#11 engine and the use of hard-
ware acceleration with the OpenSSL application, you must specify the
EVP option. EVP stands for EnVeloPE API, which is the API applications
such as Apache use to access OpenSSL cryptography. Use the EVP option
to get the most accurate openssl speed results.
$ /usr/bin/openssl speed -evp aes-128-cbc -engine pkcs11
Due to the requirements of the PKCS#11 standard regarding fork(2)
behavior, some applications that use the OpenSSL EVP interfaces and
fork() function with active crypto contexts might experience unexpected
behavior.
Using FIPS Mode
FIPS-140 capable OpenSSL is available in Oracle Solaris.
The IPS package mediator feature is used to activate the non-FIPS-140
version or the FIPS-140 version of OpenSSL.
By default, the non-FIPS-140 version (default implementation) is acti-
vated. Before switching to the FIPS-140 implementation, ensure that
the FIPS-140 implementation exists in the list shown by the pkg media-
tor -a openssl command. Otherwise, the system might become unusable.
Use the pkg set-mediator command to switch to the FIPS-140 version of
OpenSSL:
# pkg set-mediator -I fips-140@1.0 openssl
To switch back to the default non-FIPS-140 version, use the following
command:
# pkg set-mediator -I default@1.0 openssl
Reboot is required to enforce the change system-wide. It is recom-
mended to perform the mediator implementation change in an alternate
BE.
See Managing Encryption and Certificates in Oracle Solaris for more
details.
When the FIPS-140 version of OpenSSL is activated, an application will
be in FIPS-140 mode. It is no longer needed to call FIPS_mode_set() in
order to activate FIPS-140 mode.
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 responsi-
ble to free the structure later. See the pkcs11_parse_uri(7) man page
for the PKCS#11 URI attributes supported by Solaris.
The PKCS#11 engine uses the keystore for the slot chosen for public key
operations, which is metaslot on a standard configured machine. 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, see libpkcs11(3LIB).
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. Alternatively, an environment vari-
able 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.
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.
OpenSSL Thread and Fork Safety
OpenSSL provides the following interface for consumers to set the call-
back functions for its own implementation of locking and thread identi-
fication:
CRYPTO_set_locking_callback()
CRYPTO_set_dynlock_create_callback()
CRYPTO_set_dynlock_lock_callback()
CRYPTO_set_dynlock_destroy_callback()
CRYPTO_set_add_lock_callback()
CRYPTO_THREADID_set_callback()
CRYPTO_set_id_callback()
Setting of the callback functions by a library can lead to segmentation
fault if the library is unloaded while other parts of the stack are
still using OpenSSL.
In order to prevent this issue, OpenSSL on Oracle Solaris implements
those locking and thread identification functions internally within
OpenSSL. An application or library may still call those functions but
setting of their own callback function will be ignored.
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 initialized 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?pin-source=builtin-dialog" -pubout -text -engine pkcs11 -inform e
ATTRIBUTES
See attributes(7) for a description of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |library/security/openssl |
+-----------------------------+-----------------------------+
|Interface Stability |Pass-through Uncommitted |
+-----------------------------+-----------------------------+
SEE ALSO
crle(1), cryptoadm(8), libpkcs11(3LIB), pkcs11_parse_uri(7),
attributes(7), privileges(7)
/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
Solaris 11.4 15 Nov 2019 openssl(7)