1=pod
2
3=head1 NAME
4
5openssl-env - OpenSSL environment variables
6
7=head1 DESCRIPTION
8
9The OpenSSL libraries and commands use environment variables to override
10compiled-in defaults for various aspects of their behaviour.
11To avoid security risks, the environment is not consulted
12for security-sensitive environment variables when the executable
13is set-user-ID or set-group-ID.
14
15=over 4
16
17=item B<CTLOG_FILE>
18
19Specifies the path to a certificate transparency log list.
20See L<CTLOG_STORE_new(3)>.
21
22This variable is considered a security-sensitive environment variable.
23
24=item B<HOME>, B<SYSTEMROOT>, B<USERPROFILE>
25
26Path which L<RAND_file_name(3)> uses as a directory for the random seed file
27name when the B<RANDFILE> environment variable is not set.
28B<HOME> is the only variable that is considered on Unix-like systems;
29B<USERPROFILE> and B<SYSTEMROOT> are used as fallbacks on Windows platforms.
30
31B<HOME> variable is considered a security-sensitive environment variable.
32
33=item B<HTTPS_PROXY>, B<HTTP_PROXY>, B<NO_PROXY>, B<https_proxy>, B<http_proxy>, B<no_proxy>
34
35Specify a proxy hostname.
36See L<OSSL_HTTP_parse_url(3)>.
37
38These variables are considered security-sensitive environment variables.
39
40=item B<LEGACY_GOST_PKCS12>
41
42Affects the way MAC is generated in PKCS#12 containers for GOST algorithms.
43See L<PKCS12_gen_mac(3)>.
44
45This variable is considered a security-sensitive environment variable.
46
47=item B<OPENSSL>
48
49Specifies the path to the B<openssl> executable. Used by
50the B<rehash> script (see L<openssl-rehash(1)/Script Configuration>)
51and by the B<CA.pl> script (see L<CA.pl(1)/NOTES>
52
53This variable is not considered security-sensitive.
54
55=item B<OPENSSL_CONF>, B<OPENSSL_CONF_INCLUDE>
56
57Specifies the path to a configuration file and the directory for
58included files.
59See L<config(5)>.
60
61These variables are considered security-sensitive environment variables.
62
63=item B<OPENSSL_CONFIG>
64
65Specifies a configuration option and filename for the B<req> and B<ca>
66commands invoked by the B<CA.pl> script.
67See L<CA.pl(1)>.
68
69This variable is not considered security-sensitive.
70
71=item B<OPENSSL_DEBUG_DECC_INIT>
72
73On VMS only:  if this variable is set, enables verbose output of parsing
74of C<DECC$*> logical names, that contain C RTL features, during library
75initialisation (C<LIB$INITIALIZE>).  If the value of the variable is more
76than 1, outputs information about every processed feature.
77
78This variable is not considered security-sensitive.
79
80=item B<OPENSSL_ENGINES>
81
82Specifies the directory from which dynamic engines are loaded.
83See L<openssl-engine(1)>.
84
85This variable is considered a security-sensitive environment variable.
86
87=item B<OPENSSL_MALLOC_FAILURES>, B<OPENSSL_MALLOC_FD>, B<OPENSSL_MALLOC_SEED>
88
89If built with debugging, this allows memory allocation to fail.
90See L<OPENSSL_malloc(3)>.
91
92These variables are not considered security-sensitive.
93
94=item B<OPENSSL_MODULES>
95
96Specifies the directory from which cryptographic providers are loaded.
97Equivalently, the generic B<-provider-path> command-line option may be used.
98
99This variable is considered a security-sensitive environment variable.
100
101=item B<OPENSSL_SEC_MEM>
102
103Initializes the secure memory at the beginning of the application which makes
104the secure memory calls not to fall back to regular memory calls. The value
105indicates the B<size> parameter in bytes. The value can be expressed in
106binary, octal, decimal and hexadecimal. For formatting see B<strtol(3)>.
107For further restrictions see L<CRYPTO_secure_malloc_init(3)>.
108
109This variable is not considered security-sensitive.
110
111=item B<OPENSSL_SEC_MEM_MINSIZE>
112
113An optional variable used with B<OPENSSL_SEC_MEM>. The value indicates
114B<minsize> parameter in bytes. The same formatting applies as above.
115Default is 0. For more info see L<CRYPTO_secure_malloc_init(3)>.
116
117This variable is not considered security-sensitive.
118
119=item B<OPENSSL_TEST_LIBCTX>
120
121This test-only environment variable, that is recognised by the L<openssl(1)>
122command, when is set to "1", leads to creation of a nondefault library context
123by the command, for which the B<-config> option then takes effect.
124
125This variable is not considered security-sensitive.
126
127=item B<OPENSSL_TRACE>
128
129By default the OpenSSL trace feature is disabled statically.
130To enable it, OpenSSL must be built with tracing support,
131which may be configured like this: C<./config enable-trace>
132
133Unless OpenSSL tracing support is generally disabled,
134enable trace output of specific parts of OpenSSL libraries, by name.
135This output usually makes sense only if you know OpenSSL internals well.
136
137The value of this environment variable is a comma-separated list of names,
138with the following available:
139
140=over 4
141
142=item B<ALL>
143
144Traces everything.
145
146=item B<BN_CTX>
147
148Traces BIGNUM context operations.
149
150=item B<CMP>
151
152Traces CMP client and server activity.
153
154=item B<CONF>
155
156Show details about provider and engine configuration.
157
158=item B<DECODER>
159
160Traces decoder operations.
161
162=item B<ENCODER>
163
164Traces encoder operations.
165
166=item B<ENGINE_REF_COUNT>
167
168Reference counts in the ENGINE structure will be monitored with a line
169of generated for each change.
170
171=item B<ENGINE_TABLE>
172
173The function that is used by RSA, DSA (etc) code to select registered
174ENGINEs, cache defaults and functional references (etc), will generate
175debugging summaries.
176
177=item B<HTTP>
178
179Traces the HTTP client and server, such as messages being sent and received.
180
181=item B<INIT>
182
183Traces OpenSSL library initialization and cleanup.
184
185=item B<PKCS12_DECRYPT>
186
187Traces PKCS#12 decryption.
188
189=item B<PKCS12_KEYGEN>
190
191Traces PKCS#12 key generation.
192
193=item B<PKCS5V2>
194
195Traces PKCS#5 v2 key generation.
196
197=item B<PROVIDER>
198
199Traces various operations that are performed on OpenSSL providers during their
200handling by the library (see L<provider(7)>), such as initialisation, tear down,
201parameter and capability retrieval, self-test, and so on.
202
203=item B<QUERY>
204
205Traces operation related to addition, removal, and fetching of methods
206in the so-called method store, that holds pointers to functions provided
207by various providers.
208
209=item B<REF_COUNT>
210
211Traces reference count changes in various structures,
212including C<BIO>, C<DH>, C<DSA>, C<EC_KEY>, C<ECX_KEY>,
213C<EVP_PKEY>, C<EVP_SKEY>, C<RSA>, C<SSL>, C<SSL_CTX>, C<SSL_SESSION>,
214C<X509_CRL>, C<X509_STORE>, C<X509>, and some others.
215
216=item B<STORE>
217
218Traces STORE operations.
219
220=item B<TLS>
221
222Traces the TLS/SSL protocol.
223
224=item B<TLS_CIPHER>
225
226Traces the ciphers used by the TLS/SSL protocol.
227
228=item B<TRACE>
229
230Traces the OpenSSL trace API itself.
231
232=item B<X509V3_POLICY>
233
234Generates the complete policy tree at various points during X.509 v3
235policy evaluation.
236
237=back
238
239This variable is not considered security-sensitive.
240
241=item B<OPENSSL_WIN32_UTF8>
242
243If set, then L<UI_OpenSSL(3)> returns UTF-8 encoded strings, rather than
244ones encoded in the current code page, and
245the L<openssl(1)> program also transcodes the command-line parameters
246from the current code page to UTF-8.
247This environment variable is only checked on Microsoft Windows platforms.
248
249=item B<OPENSSL_armcap>, B<OPENSSL_ia32cap>, B<OPENSSL_ppccap>, B<OPENSSL_riscvcap>, B<OPENSSL_s390xcap>, B<OPENSSL_sparcv9cap>
250
251OpenSSL supports a number of different algorithm implementations for
252various machines and, by default, it determines which to use based on the
253processor capabilities and run time feature enquiry.  These environment
254variables can be used to exert more control over this selection process.
255See L<OPENSSL_ia32cap(3)>, L<OPENSSL_riscvcap(3)>, and L<OPENSSL_s390xcap(3)>.
256
257These variables are not considered security-sensitive.
258
259=item B<OSSL_QFILTER>
260
261Used to set a QUIC qlog filter specification. See L<openssl-qlog(7)>.
262
263This variable is considered a security-sensitive environment variable.
264
265=item B<QLOGDIR>
266
267Specifies a QUIC qlog output directory. See L<openssl-qlog(7)>.
268
269This variable is considered a security-sensitive environment variable.
270
271=item B<RANDFILE>
272
273The state file for the random number generator.
274This should not be needed in normal use.
275See L<RAND_load_file(3)>.
276
277This variable is considered a security-sensitive environment variable.
278
279=item B<SSLKEYLOGFILE>
280
281Used to produce the standard format output file for SSL key logging.  Optionally
282set this variable to a filename to log all secrets produced by SSL connections.
283Note, use of the environment variable is predicated on configuring OpenSSL at
284build time with the enable-sslkeylog feature.  The file format standard can be
285found at L<https://datatracker.ietf.org/doc/draft-ietf-tls-keylogfile/>.
286Note: the use of B<SSLKEYLOGFILE> poses an explicit security risk.  By recording
287the exchanged keys during an SSL session, it allows any available party with
288read access to the file to decrypt application traffic sent over that session.
289Use of this feature should be restricted to test and debug environments only.
290
291This variable is considered a security-sensitive environment variable.
292
293=item B<SSL_CERT_DIR>, B<SSL_CERT_FILE>
294
295Specify the default directory or file containing CA certificates.
296See L<SSL_CTX_load_verify_locations(3)>.
297
298These variables are considered security-sensitive environment variables,
299except in L<openssl-rehash(1)>, where B<SSL_CERT_DIR> is not considered
300security-sensitive.
301
302=item B<SSL_CIPHER>
303
304Used by L<openssl-s_time(1)> in case B<-cipher> option (that allows modifying
305TLSv1.2 and below cipher list sent by the client) is not provided,
306for specification of the aforementioned ciphers.
307
308This variable is not considered security-sensitive.
309
310=item B<TSGET>
311
312Additional arguments for the L<tsget(1)> command.
313
314This variable is not considered security-sensitive.
315
316=back
317
318=head1 HISTORY
319
320This section contains environment variables that are no longer considered
321by the OpenSSL libraries and commands.
322
323=over 4
324
325=item B<HARNESS_OSSL_PREFIX>
326
327This environment variable, existed in OpenSSL versions from 1.1.1 up to 3.5,
328allowed specification of a prefix prepended to each line sent to the I<stdout>
329by L<openssl(1)>, used by the test harness to avoid commingling the command
330under test output with the output for the TAP consumer.
331
332This variable was not considered security-sensitive.
333
334=back
335
336=head1 COPYRIGHT
337
338Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
339
340Licensed under the Apache License 2.0 (the "License").  You may not use
341this file except in compliance with the License.  You can obtain a copy
342in the file LICENSE in the source distribution or at
343L<https://www.openssl.org/source/license.html>.
344
345=cut
346