|
1 '\" te |
|
2 .\" Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. |
|
3 .TH openssl 7 "3 Mar 2017" "SunOS 5.11" "Standards, Environments, and Macros" |
|
4 .SH NAME |
|
5 openssl \- OpenSSL cryptographic and Secure Sockets Layer toolkit |
|
6 .SH DESCRIPTION |
|
7 .sp |
|
8 .LP |
|
9 OpenSSL is a cryptography toolkit that implements the Secure Sockets Layer (SSLv3) and Transport Layer Security (TLS v1) network protocols. |
|
10 .sp |
|
11 .LP |
|
12 The following features are omitted from the binaries for issues including 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. |
|
13 .SS "The Dynamic Engine Support" |
|
14 .sp |
|
15 .LP |
|
16 The dynamic engine support has been enabled, which enables an external engine, in the form of a shared library, to be dynamically bound and used by an OpenSSL-based application. |
|
17 .sp |
|
18 .LP |
|
19 Run the following command to see if the dynamic engine is supported: |
|
20 .sp |
|
21 .in +2 |
|
22 .nf |
|
23 $openssl engine dynamic |
|
24 (dynamic) Dynamic engine loading support |
|
25 .fi |
|
26 .in -2 |
|
27 .sp |
|
28 |
|
29 .SS "The PKCS#11 Engine" |
|
30 .sp |
|
31 .LP |
|
32 The PKCS#11 engine has been included with the ENGINE name \fBpkcs11\fR. The engine was developed within Oracle and is not integrated in the OpenSSL project. |
|
33 .sp |
|
34 .LP |
|
35 The PKCS#11 is a dynamic engine, and is configured to use the Oracle Solaris Cryptographic Framework. See \fBcryptoadm\fR(1M) for configuration information. |
|
36 .sp |
|
37 .LP |
|
38 The PKCS#11 engine can support the following set of mechanisms: \fBCKM_AES_CBC\fR, \fBCKM_AES_ECB\fR, \fBCKM_BLOWFISH_CBC\fR, \fBCKM_DES_CBC\fR, \fBCKM_DES_ECB\fR, \fBCKM_DES3_CBC\fR, \fBCKM_DES3_ECB\fR, \fBCKM_DSA\fR, \fBCKM_MD5\fR, \fBCKM_RC4\fR, \fBCKM_RSA_PKCS\fR, \fBCKM_RSA_X_509\fR, \fBCKM_SHA_1\fR, \fBCKM_SHA224\fR, \fBCKM_SHA256\fR, \fBCKM_SHA384\fR, \fBCKM_SHA512\fR, \fBCKM_SHA224_HMAC\fR, \fBCKM_SHA224_HMAC_GENERAL\fR, and \fBCKM_SHA224_KEY_DERIVATION\fR. |
|
39 .sp |
|
40 .LP |
|
41 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: |
|
42 .sp |
|
43 .in +2 |
|
44 .nf |
|
45 $ /usr/sfw/bin/openssl engine dynamic -pre |
|
46 SO_PATH:/lib/openssl/engines/64/libpk11.so -pre LOAD -t -c |
|
47 .fi |
|
48 .in -2 |
|
49 .sp |
|
50 |
|
51 .sp |
|
52 .LP |
|
53 In order to verify the use of the PKCS#11 engine and the use of hardware 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. |
|
54 .sp |
|
55 .in +2 |
|
56 .nf |
|
57 $ \fB/usr/bin/openssl speed -evp aes-128-cbc -engine pkcs11\fR |
|
58 .fi |
|
59 .in -2 |
|
60 .sp |
|
61 |
|
62 .sp |
|
63 .LP |
|
64 Due to the requirements of the PKCS#11 standard regarding \fBfork\fR(2) behavior, some applications that use the OpenSSL EVP interfaces and \fBfork()\fR function with active \fBcrypto\fR contexts might experience unexpected behavior. |
|
65 .SS "Using FIPS Mode" |
|
66 .sp |
|
67 .LP |
|
68 FIPS-140 capable OpenSSL is available in Oracle Solaris. |
|
69 .sp |
|
70 .LP |
|
71 The IPS package mediator feature is used to activate the non-FIPS-140 version or the FIPS-140 version of OpenSSL. |
|
72 .sp |
|
73 .LP |
|
74 By default, the non-FIPS-140 version (\fBdefault\fR implementation) is activated. Use the \fBpkg set-mediator\fR command to switch to the FIPS-140 version of OpenSSL. Before switching to the \fBfips-140\fR implementation, ensure that the \fBfips-140\fR implementation exists in the list shown by the \fBpkg mediator -a openssl\fR command. Otherwise, the system might become unusable. |
|
75 .sp |
|
76 .in +2 |
|
77 .nf |
|
78 # \fBpkg set-mediator -I fips-140 openssl\fR |
|
79 .fi |
|
80 .in -2 |
|
81 .sp |
|
82 |
|
83 .sp |
|
84 .LP |
|
85 To switch back to the default non-FIPS-140 version, use the following command: |
|
86 .sp |
|
87 .in +2 |
|
88 .nf |
|
89 # \fBpkg set-mediator -I default openssl\fR |
|
90 .fi |
|
91 .in -2 |
|
92 .sp |
|
93 |
|
94 .sp |
|
95 .LP |
|
96 It is recommended to perform the mediator implementation change in an alternate BE. |
|
97 .sp |
|
98 .LP |
|
99 For more information, see \fIManaging Encryption and Certificates in Oracle Solaris 11.3\fR. |
|
100 .sp |
|
101 .LP |
|
102 When the FIPS-140 version of OpenSSL is activated, an application can run in FIPS-140 mode or non-FIPS-140 mode. An application must explicitly call \fBFIPS_mode_set()\fR in order to activate FIPS-140 mode. |
|
103 .SS "Building an OpenSSL Application" |
|
104 .sp |
|
105 .LP |
|
106 To build an OpenSSL application, use the following \fBcc\fR command line options: |
|
107 .sp |
|
108 .in +2 |
|
109 .nf |
|
110 cc [ \fIflag\fR... ] \fIfile\fR... -lcrypto -lssl [ \fIlibrary\fR... ] |
|
111 .fi |
|
112 .in -2 |
|
113 |
|
114 .SS "Accessing RSA Keys in PKCS#11 Keystores" |
|
115 .sp |
|
116 .LP |
|
117 OpenSSL can access RSA keys in PKCS#11 keystores using the following functions of the ENGINE API: |
|
118 .sp |
|
119 .in +2 |
|
120 .nf |
|
121 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, |
|
122 const char *key_id, UI_METHOD *ui_method, |
|
123 void *callback_data) |
|
124 |
|
125 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, |
|
126 const char *key_id, UI_METHOD *ui_method, |
|
127 void *callback_data) |
|
128 .fi |
|
129 .in -2 |
|
130 |
|
131 .sp |
|
132 .LP |
|
133 \fBkey_id\fR, formerly for filenames only, can be now also set to a \fBPKCS#11 URI\fR. The \fBEVP_PKEY\fR structure is newly allocated and caller is responsible to free the structure later. To avoid clashes with existing filenames, \fBfile://\fR prefix for filenames is now also accepted but only when the PKCS#11 engine is in use. The PKCS#11 URI specification follows: |
|
134 .sp |
|
135 .in +2 |
|
136 .nf |
|
137 pkcs11:[token=<label>][:manuf=<label>][;serial=<label>] |
|
138 [;model=<label>][;object=<label>] |
|
139 [;objecttype=(public|private|cert)] |
|
140 [;passphrasedialog=(builtin|exec:<file>)] |
|
141 .fi |
|
142 .in -2 |
|
143 |
|
144 .sp |
|
145 .LP |
|
146 The ordering of keywords is not significant. The PKCS#11 engine uses the keystore for the slot chosen for public key operations, which is \fBmetaslot\fR on a standard configured machine. Currently, the PKCS#11 engine ignores the \fBobjecttype\fR keyword. The only mandatory keyword is \fBobject\fR which is the key object label. For information on how to use a different, possibly hardware, keystore with \fBmetaslot\fR, see \fBlibpkcs11\fR(3LIB). |
|
147 .sp |
|
148 .LP |
|
149 The token PIN is provided by way of the \fBpassphrasedialog\fR keyword and is either read from the terminal (\fBbuiltin\fR) or from the output of an external command (\fBexec:<file>\fR). The PIN is used to log into the token and by default is deleted from the memory then. The keyword \fBpin\fR is intentionally not provided due to inherent security problems of possible use of a password in the process arguments. |
|
150 .sp |
|
151 .LP |
|
152 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, \fBexec:<file>\fR option of the \fBpassphrasedialog\fR keyword can be used. Alternatively, an environment variable \fBOPENSSL_PKCS11_PIN_CACHING_POLICY\fR can be used to allow the PIN to be cached in memory and reused in the child. It can be set to \fBnone\fR which is the default, \fBmemory\fR to store the PIN in memory, and \fBmlocked-memory\fR to keep the PIN in a locked page using \fBmlock\fR(3C). \fBPRIV_PROC_LOCK_MEMORY\fR privilege is required in that case. |
|
153 .sp |
|
154 .LP |
|
155 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. |
|
156 .sp |
|
157 .LP |
|
158 To use the RSA keys by reference, high level API functions such as \fBRSA_public_decrypt()\fR, \fBEVP_PKEY_set1_RSA()\fR, or \fBEVP_SignInit()\fR must be used. Low level functions might go around the engine and fail to make use of the feature. |
|
159 .SS "OpenSSL Thread and Fork Safety" |
|
160 .sp |
|
161 .LP |
|
162 OpenSSL provides an interface \fBCRYPTO_set_locking_callback()\fR for any consumers to set its own locking callback function. However, setting of the callback function by a library can lead to segmentation fault, if the library is unloaded while other parts of the stack are still using OpenSSL. |
|
163 .sp |
|
164 .LP |
|
165 In order to prevent this issue, OpenSSL on Solaris sets up the mutexes and the locking callback function internally within OpenSSL. An application or library might still call \fBCRYPTO_set_locking_callback()\fR, but setting of their own callback function will be ignored. |
|
166 .SS "Additional Documentation" |
|
167 .sp |
|
168 .LP |
|
169 Extensive additional documentation for OpenSSL modules is available in the \fB/usr/share/man/man1openssl\fR, \fB/usr/share/man/man3openssl\fR, \fB/usr/share/man/man5openssl\fR, and \fB/usr/share/man/man7openssl\fR directories. |
|
170 .sp |
|
171 .LP |
|
172 To view the license terms, attribution, and copyright for OpenSSL, run \fBpkg info --license library/security/openssl\fR. |
|
173 .SH EXAMPLES |
|
174 .LP |
|
175 \fBExample 1 \fRGenerating and Printing a Public Key |
|
176 .sp |
|
177 .LP |
|
178 The following example generates and prints a public key stored in an already initialized PKCS#11 keystore. Notice the use of \fB-engine pkcs11\fR and \fB-inform e\fR. |
|
179 |
|
180 .sp |
|
181 .in +2 |
|
182 .nf |
|
183 $ pktool gencert keystore=pkcs11 label=mykey \e |
|
184 subject="CN=test" keytype=rsa keylen=1024 serial=01 |
|
185 $ openssl rsa -in "pkcs11:object=mykey;passphrasedialog=builtin"\e |
|
186 -pubout -text -engine pkcs11 -inform e |
|
187 .fi |
|
188 .in -2 |
|
189 |
|
190 .SH ATTRIBUTES |
|
191 .sp |
|
192 .LP |
|
193 See \fBattributes\fR(5) for a description of the following attributes: |
|
194 .sp |
|
195 |
|
196 .sp |
|
197 .TS |
|
198 tab() box; |
|
199 cw(2.75i) |cw(2.75i) |
|
200 lw(2.75i) |lw(2.75i) |
|
201 . |
|
202 ATTRIBUTE TYPEATTRIBUTE VALUE |
|
203 _ |
|
204 AvailabilityT{ |
|
205 library/security/openssl, library/security/openssl |
|
206 T} |
|
207 _ |
|
208 Interface StabilityCommitted |
|
209 .TE |
|
210 |
|
211 .SH SEE ALSO |
|
212 .sp |
|
213 .LP |
|
214 \fBcrle\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB), \fBattributes\fR(5), \fBprivileges\fR(5) |
|
215 .sp |
|
216 .LP |
|
217 \fB/usr/share/man/man1openssl/openssl.1openssl\fR, \fB/usr/share/man/man1openssl/CRYPTO_num_locks.3openssl\fR, \fB/usr/share/man/man3openssl/engine.3\fR, \fB/usr/share/man/man3openssl/evp.3\fR |