index.rst (51173B)
1 .. _mozilla_projects_nss_reference_nss_environment_variables: 2 3 NSS environment variables 4 ========================= 5 6 .. container:: 7 8 .. note:: 9 10 **Note: NSS Environment Variables are subject to be changed and/or removed from NSS.** 11 12 .. _run-time_environment_variables: 13 14 `Run-Time Environment Variables <#run-time_environment_variables>`__ 15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 16 17 .. container:: 18 19 These environment variables affect the RUN TIME behavior of NSS shared libraries. There is a 20 separate set of environment variables that affect how NSS is built, documented below. 21 22 +------------------------+------------------------+------------------------+------------------------+ 23 | Variable | Type | Description | Introduced in version | 24 +------------------------+------------------------+------------------------+------------------------+ 25 | ``NSRANDCOUNT`` | Integer | Sets the maximum | 3.12.3 | 26 | | (byte count) | number of bytes to | | 27 | | | read from the file | | 28 | | | named in the | | 29 | | | environment variable | | 30 | | | NSRANDFILE (see | | 31 | | | below). Makes | | 32 | | | NSRANDFILE usable with | | 33 | | | /dev/urandom. | | 34 +------------------------+------------------------+------------------------+------------------------+ 35 | ``NSRANDFILE`` | String | Uses this file to seed | Before 3.0 | 36 | | (file name) | the Pseudo Random | | 37 | | | Number Generator. | | 38 +------------------------+------------------------+------------------------+------------------------+ 39 | ``NSS_ALLO | Boolean | Enables the use of MD2 | 3.12.3 | 40 | W_WEAK_SIGNATURE_ALG`` | (any non-empty value | and MD4 inside | | 41 | | to enable) | signatures. This was | | 42 | | | allowed by default | | 43 | | | before NSS 3.12.3. | | 44 +------------------------+------------------------+------------------------+------------------------+ 45 | ``NSS | String | Name the PKCS#11 | 3.6 | 46 | _DEBUG_PKCS11_MODULE`` | (module name) | module to be traced. | | 47 | | | :ref:`mozilla | | 48 | | | _projects_nss_nss_tech | | 49 | | | _notes_nss_tech_note2` | | 50 +------------------------+------------------------+------------------------+------------------------+ 51 | ` | String | Determines the default | 3.12 | 52 | `NSS_DEFAULT_DB_TYPE`` | ("dbm", "sql", or | Database type to open | | 53 | | "extern") | if the app does not | | 54 | | | specify. | | 55 | | | `NSS_Shared_D | | 56 | | | B <http://wiki.mozilla | | 57 | | | .org/NSS_Shared_DB>`__ | | 58 +------------------------+------------------------+------------------------+------------------------+ 59 | ``NSS_DIS | String | Define this variable | 3.4 | 60 | ABLE_ARENA_FREE_LIST`` | (any non-empty value) | to get accurate leak | | 61 | | | allocation stacks when | | 62 | | | using leak reporting | | 63 | | | software. | | 64 | | | : | | 65 | | | ref:`mozilla_projects_ | | 66 | | | nss_memory_allocation` | | 67 +------------------------+------------------------+------------------------+------------------------+ 68 | ``NSS_DISABLE_UNLOAD`` | String | Disable unloading of | 3.11.8 | 69 | | (any non-empty value) | dynamically loaded NSS | | 70 | | | shared libraries | | 71 | | | during shutdown. | | 72 | | | Necessary on some | | 73 | | | platforms to get | | 74 | | | correct function names | | 75 | | | when using leak | | 76 | | | reporting software. | | 77 +------------------------+------------------------+------------------------+------------------------+ 78 | ``NSS_ENABLE_AUDIT`` | Boolean | Enable auditing of | 3.11.2 | 79 | | (1 to enable) | activities of the NSS | | 80 | | | cryptographic module | | 81 | | | in FIPS mode. `Audit | | 82 | | | Data <http://wiki. | | 83 | | | mozilla.org/FIPS_Opera | | 84 | | | tional_Environment>`__ | | 85 +------------------------+------------------------+------------------------+------------------------+ 86 | ``NS | Boolean | Use libPKIX, rather | 3.12 | 87 | S_ENABLE_PKIX_VERIFY`` | (any non-empty value | than the old cert | | 88 | | to enable) | library, to verify | | 89 | | | certificates. | | 90 +------------------------+------------------------+------------------------+------------------------+ 91 | ``NSS_FIPS`` | String | Will start NSS in FIPS | 3.12.5 | 92 | | (" | mode. | | 93 | | fips","true","on","1") | | | 94 +------------------------+------------------------+------------------------+------------------------+ 95 | `` | String | Specifies agorithms | 3.12.3 | 96 | NSS_HASH_ALG_SUPPORT`` | | allowed to be used in | | 97 | | | certain applications, | | 98 | | | such as in signatures | | 99 | | | on certificates and | | 100 | | | CRLs. See | | 101 | | | documentation at `this | | 102 | | | link <https://bugzill | | 103 | | | a.mozilla.org/show_bug | | 104 | | | .cgi?id=483113#c0>`__. | | 105 +------------------------+------------------------+------------------------+------------------------+ 106 | ``NSS_OUTPUT_FILE`` | String | Output file path name | 3.7 | 107 | | (filename) | for the | | 108 | | | :ref:`mozilla_ | | 109 | | | projects_nss_nss_tech_ | | 110 | | | notes_nss_tech_note2`. | | 111 | | | Default is stdout. | | 112 +------------------------+------------------------+------------------------+------------------------+ 113 | ``NSS_SDB_USE_CACHE`` | String | Controls whether NSS | 3.12 | 114 | | ("no","yes","auto") | uses a local cache of | | 115 | | | SQL database contents. | | 116 | | | Default is "auto". See | | 117 | | | `the | | 118 | | | source <http://bonsai | | 119 | | | .mozilla.org/cvsblame. | | 120 | | | cgi?file=/mozilla/secu | | 121 | | | rity/nss/lib/softoken/ | | 122 | | | sdb.c&rev=1.6#1797>`__ | | 123 | | | for more information. | | 124 +------------------------+------------------------+------------------------+------------------------+ 125 | `NS | String ("0", "1") | Controls the | | 126 | S_SSL_CBC_RANDOM_IV <h | | workaround for the | | 127 | ttps://dxr.mozilla.org | | `BEAST <https | | 128 | /security/search?q=NSS | | ://en.wikipedia.org/wi | | 129 | _SSL_CBC_RANDOM_IV>`__ | | ki/Transport_Layer_Sec | | 130 | | | urity#BEAST_attack>`__ | | 131 | | | attack on SSL 3.0 and | | 132 | | | TLS 1.0. "0" disables | | 133 | | | it, "1" enables it. It | | 134 | | | is also known as 1/n-1 | | 135 | | | record splitting. | | 136 | | | Default is "1". | | 137 +------------------------+------------------------+------------------------+------------------------+ 138 | ``NSS_SSL_ | String | (Definition for NSS | 3.12.5 | 139 | ENABLE_RENEGOTIATION`` | ([0|n|N], | 3.12.6 and above) | Modified in 3.12.6 | 140 | | [1|u|U], | Sets how TLS | | 141 | | [2|r|R], | renegotiation is | | 142 | | [3|t|T]) | handled | | 143 | | | | | 144 | | | - [1|u|U]: | | 145 | | | SSL_RE | | 146 | | | NEGOTIATE_UNRESTRICTED | | 147 | | | | | 148 | | | | Server and client | | 149 | | | are allowed to | | 150 | | | renegotiate without | | 151 | | | any restrictions. | | 152 | | | | This setting was the | | 153 | | | default prior 3.12.5 | | 154 | | | and makes products | | 155 | | | vulnerable. | | 156 | | | | | 157 | | | - [0|n|N]: | | 158 | | | | | 159 | | | SSL_RENEGOTIATE_NEVER | | 160 | | | | | 161 | | | Never allow | | 162 | | | renegotiation - That | | 163 | | | was the default for | | 164 | | | 3.12.5 release. | | 165 | | | | | 166 | | | - [3|t|T]: | | 167 | | | SSL_RE | | 168 | | | NEGOTIATE_TRANSITIONAL | | 169 | | | | | 170 | | | Disallows unsafe | | 171 | | | renegotiation in | | 172 | | | server sockets only, | | 173 | | | but allows clients to | | 174 | | | continue to | | 175 | | | renegotiate with | | 176 | | | vulnerable servers. | | 177 | | | This value should only | | 178 | | | be used during the | | 179 | | | transition period when | | 180 | | | few servers have been | | 181 | | | upgraded. | | 182 | | | | | 183 | | | - [2|r|R]: | | 184 | | | SSL_RE | | 185 | | | NEGOTIATE_REQUIRES_XTN | | 186 | | | (default) | | 187 | | | | | 188 | | | | Only allows | | 189 | | | renegotiation if the | | 190 | | | peer's hello bears | | 191 | | | the TLS | | 192 | | | renegotiation_info | | 193 | | | extension. | | 194 | | | | This is the safe | | 195 | | | renegotiation. | | 196 +------------------------+------------------------+------------------------+------------------------+ 197 | ``NSS_SSL_REQU | Boolean | It controls whether | 3.12.5 | 198 | IRE_SAFE_NEGOTIATION`` | (1 to enable) | safe renegotiation | | 199 | | | indication is required | | 200 | | | for initial handshake. | | 201 | | | In other words a | | 202 | | | connection will be | | 203 | | | dropped at initial | | 204 | | | handshake if a server | | 205 | | | or client do not | | 206 | | | support safe | | 207 | | | renegotiation. The | | 208 | | | default setting for | | 209 | | | this option is FALSE. | | 210 +------------------------+------------------------+------------------------+------------------------+ 211 | ``NSS_SSL_SERVER | Integer | Timeout time to detect | 3.4 | 212 | _CACHE_MUTEX_TIMEOUT`` | (seconds) | dead or hung process | | 213 | | | in multi-process SSL | | 214 | | | server. Default is 30 | | 215 | | | seconds. | | 216 +------------------------+------------------------+------------------------+------------------------+ 217 | ``NSS_STRICT_NOFORK`` | String | It is an error to try | 3.12.3 | 218 | | ("1", | to use a PKCS#11 | | 219 | | "DISABLED", | crypto module in a | | 220 | | or any other non-empty | process before it has | | 221 | | value) | been initialized in | | 222 | | | that process, even if | | 223 | | | the module was | | 224 | | | initialized in the | | 225 | | | parent process. | | 226 | | | Beginning in NSS | | 227 | | | 3.12.3, Softoken will | | 228 | | | detect this error. | | 229 | | | This environment | | 230 | | | variable controls | | 231 | | | Softoken's response to | | 232 | | | that error. | | 233 | | | | | 234 | | | - If set to "1" or | | 235 | | | unset, Softoken | | 236 | | | will trigger an | | 237 | | | assertion failure | | 238 | | | in debug builds, | | 239 | | | and will report an | | 240 | | | error in non-DEBUG | | 241 | | | builds. | | 242 | | | - If set to | | 243 | | | "DISABLED", | | 244 | | | Softoken will | | 245 | | | ignore forks, and | | 246 | | | behave as it did in | | 247 | | | older versions. | | 248 | | | - If set to any other | | 249 | | | non-empty value, | | 250 | | | Softoken will | | 251 | | | report an error in | | 252 | | | both DEBUG and | | 253 | | | non-DEBUG builds. | | 254 +------------------------+------------------------+------------------------+------------------------+ 255 | ` | String | will trigger an | 3.5 | 256 | `NSS_STRICT_SHUTDOWN`` | (any non-empty value) | assertion failure in | | 257 | | | debug builds when a | | 258 | | | program tries to | | 259 | | | shutdown NSS before | | 260 | | | freeing all the | | 261 | | | resources it acquired | | 262 | | | from NSS while NSS was | | 263 | | | initialized. | | 264 +------------------------+------------------------+------------------------+------------------------+ 265 | ``NSS_TRACE_OCSP`` | Boolean | Enables OCSP tracing. | 3.12 | 266 | | (any value to enable) | The trace information | | 267 | | | is written to the file | | 268 | | | pointed by | | 269 | | | NSPR_LOG_FILE (default | | 270 | | | stderr). See `NSS | | 271 | | | trac | | 272 | | | ing <http://wiki.mozil | | 273 | | | la.org/NSS:Tracing>`__ | | 274 +------------------------+------------------------+------------------------+------------------------+ 275 | ``NSS_USE_ | Boolean | Tells NSS to send EC | 3.12.3 | 276 | DECODED_CKA_EC_POINT`` | (any value to enable) | key points across the | | 277 | | | PKCS#11 interface in | | 278 | | | the non-standard | | 279 | | | unencoded format that | | 280 | | | was used by default | | 281 | | | before NSS 3.12.3. | | 282 +------------------------+------------------------+------------------------+------------------------+ 283 | ``NSS_US | Boolean | Tells NSS to allow | 3.12.3 | 284 | E_SHEXP_IN_CERT_NAME`` | (any value to enable) | shell-style wildcard | | 285 | | | patterns in | | 286 | | | certificates to match | | 287 | | | SSL server host names. | | 288 | | | This behavior was the | | 289 | | | default before NSS | | 290 | | | 3.12.3. | | 291 +------------------------+------------------------+------------------------+------------------------+ 292 | ``PKIX_OBJECT_LEA | String | Debug variable for | 3.12 | 293 | K_TEST_ABORT_ON_LEAK`` | (any non-empty value) | PKIX leak checking. | | 294 | | | Note: *The code must | | 295 | | | be built with | | 296 | | | PKIX_OBJECT_LEAK_TEST | | 297 | | | defined to use this | | 298 | | | functionality.* | | 299 +------------------------+------------------------+------------------------+------------------------+ 300 | ``SOCKETTRACE`` | Boolean | Controls tracing of | 3.12 | 301 | | (1 to enable) | socket activity by | | 302 | | | libPKIX. Messages sent | | 303 | | | and received will be | | 304 | | | timestamped and dumped | | 305 | | | (to stdout) in | | 306 | | | standard hex-dump | | 307 | | | format. | | 308 +------------------------+------------------------+------------------------+------------------------+ 309 | ``SQLITE | Boolean | 1 means force always | 3.12.6 | 310 | _FORCE_PROXY_LOCKING`` | (1 to enable) | use proxy, 0 means | | 311 | | | never use proxy, NULL | | 312 | | | means use proxy for | | 313 | | | non-local files only. | | 314 +------------------------+------------------------+------------------------+------------------------+ 315 | ``SSLBYPASS`` | Boolean | Uses PKCS#11 bypass | 3.11 | 316 | | (1 to enable) | for performance | | 317 | | | improvement. | | 318 | | | Do not set this | | 319 | | | variable if FIPS is | | 320 | | | enabled. | | 321 +------------------------+------------------------+------------------------+------------------------+ 322 | ``SSLDEBUG`` | Integer | Debug level | Before 3.0 | 323 | | | Note: *The code must | | 324 | | | be built with DEBUG | | 325 | | | defined to use this | | 326 | | | functionality.* | | 327 +------------------------+------------------------+------------------------+------------------------+ 328 | ``SSLDEBUGFILE`` | String | File where debug or | 3.12 | 329 | | (file name) | trace information is | | 330 | | | written. | | 331 | | | If not set, the debug | | 332 | | | or trace information | | 333 | | | is written to stderr. | | 334 | | | | | 335 | | | Note: *SSLDEBUG or | | 336 | | | SSLTRACE have to be | | 337 | | | set to use this | | 338 | | | functionality.* | | 339 +------------------------+------------------------+------------------------+------------------------+ 340 | ``SSLFORCELOCKS`` | Boolean | Forces NSS to use | 3.11 | 341 | | (1 to enable) | locks for protection. | | 342 | | | Overrides the effect | | 343 | | | of SSL_NO_LOCKS (see | | 344 | | | ssl.h). | | 345 +------------------------+------------------------+------------------------+------------------------+ 346 | ``SSLKEYLOGFILE`` | String | Key log file. If set, | 3.12.6 | 347 | | (file name) | NSS logs RSA | | 348 | | | pre-master secrets to | | 349 | | | this file. This allows | | 350 | | | packet sniffers to | | 351 | | | decrypt TLS | | 352 | | | connections. See | | 353 | | | :ref:`mozilla_project | | 354 | | | s_nss_key_log_format`. | | 355 +------------------------+------------------------+------------------------+------------------------+ 356 | ``SSLTRACE`` | Integer | Tracing level | Before 3.0 | 357 | | | Note: *The code must | | 358 | | | be built with TRACE | | 359 | | | defined to use this | | 360 | | | functionality.* | | 361 +------------------------+------------------------+------------------------+------------------------+ 362 363 .. _build-time_environment_variables: 364 365 `Build-Time Environment Variables <#build-time_environment_variables>`__ 366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 367 368 .. container:: 369 370 These environment variables affect the build (compilation) of NSS. 371 372 .. note:: 373 374 **Note: This section is a work in progress and is not yet complete.** 375 376 +------------------------+------------------------+------------------------+------------------------+ 377 | Variable | Type | Description | Introduced in version | 378 +------------------------+------------------------+------------------------+------------------------+ 379 | ``BUILD_OPT`` | Boolean | Do an optimized (not | Before 3.0 | 380 | | (1 to enable) | DEBUG) build. Default | | 381 | | | is to do a DEBUG | | 382 | | | build. | | 383 +------------------------+------------------------+------------------------+------------------------+ 384 | ``MOZ_DEBUG_SYMBOLS`` | Boolean | Needed on Windows to | 3.11 | 385 | | (1 to enable) | build with versions of | | 386 | | | MSVC (such as VC8 and | | 387 | | | VC9) that do not | | 388 | | | understand /PDB:NONE | | 389 +------------------------+------------------------+------------------------+------------------------+ 390 | ``MOZ_DEBUG_FLAGS`` | String | When | 3.12.8 | 391 | | | ``MOZ_DEBUG_SYMBOLS`` | | 392 | | | is set, you may use | | 393 | | | ``MOZ_DEBUG_FLAGS`` to | | 394 | | | specify alternative | | 395 | | | compiler flags to | | 396 | | | produce symbolic | | 397 | | | debugging information | | 398 | | | in a particular | | 399 | | | format. | | 400 +------------------------+------------------------+------------------------+------------------------+ 401 | ``NSDISTMODE`` | String | On operating systems | Before 3.0 | 402 | | | other than Windows, | | 403 | | | this controls whether | | 404 | | | copies, absolute | | 405 | | | symlinks, or relative | | 406 | | | symlinks of the output | | 407 | | | files should be | | 408 | | | published to | | 409 | | | mozilla/dist. The | | 410 | | | possible values are: | | 411 | | | | | 412 | | | - copy: copies of | | 413 | | | files are published | | 414 | | | - absolute_symlink: | | 415 | | | symlinks whose | | 416 | | | targets are | | 417 | | | absolute pathnames | | 418 | | | are published | | 419 | | | | | 420 | | | If not specified, | | 421 | | | default to relative | | 422 | | | symlinks (symlinks | | 423 | | | whose targets are | | 424 | | | relative pathnames). | | 425 | | | On Windows, copies of | | 426 | | | files are always | | 427 | | | published. | | 428 +------------------------+------------------------+------------------------+------------------------+ 429 | ``NS_USE_GCC`` | Boolean | On systems where GCC | Before 3.0 | 430 | | (1 to enable) | is not the default | | 431 | | | compiler, this tells | | 432 | | | NSS to build with gcc. | | 433 +------------------------+------------------------+------------------------+------------------------+ 434 | `N | Boolean | Enable NSS support in | 3.24 | 435 | SS_ALLOW_SSLKEYLOGFILE | (1 to enable) | optimized builds for | | 436 | <https://dxr.mozilla. | | logging SSL/TLS key | | 437 | org/nss/search?q=NSS_A | | material to a logfile | | 438 | LLOW_SSLKEYLOGFILE>`__ | | if the SSLKEYLOGFILE | | 439 | | | environment variable. | | 440 | | | As of NSS 3.24 this is | | 441 | | | disabled by default. | | 442 +------------------------+------------------------+------------------------+------------------------+ 443 | ``NSS_BUI | Boolean | Continue building NSS | 3.12.4 | 444 | LD_CONTINUE_ON_ERROR`` | (1 to enable) | source directories | | 445 | | | when a build error | | 446 | | | occurs. | | 447 +------------------------+------------------------+------------------------+------------------------+ 448 | ``N | Boolean | Use the system | 3.12.6 | 449 | SS_USE_SYSTEM_SQLITE`` | (1 to enable) | installed sqlite | | 450 | | | library instead of the | | 451 | | | in-tree version. | | 452 +------------------------+------------------------+------------------------+------------------------+ 453 | ``NSS_DISA | Boolean | Disable Elliptic Curve | 3.16 | 454 | BLE_ECC (deprecated)`` | (1 to disable) | Cryptography features. | | 455 | | | As of NSS 3.16, ECC | | 456 | | | features are enabled | | 457 | | | by default. As of NSS | | 458 | | | 3.33 this variable has | | 459 | | | no effect. | | 460 +------------------------+------------------------+------------------------+------------------------+ 461 | ``NSS_ENA | Boolean | Enable building of | Before 3.16; since | 462 | BLE_ECC (deprecated)`` | (1 to enable) | code that uses | 3.11. | 463 | | | Elliptic Curve | | 464 | | | Cryptography. Unused | | 465 | | | as of NSS 3.16; see | | 466 | | | NSS_DISABLE_ECC. | | 467 +------------------------+------------------------+------------------------+------------------------+ 468 | ```NSS_FOR | | Boolean | Allows enabling FIPS | 3.24 | 469 | CE_FIPS`` <https://dxr | | (1 to enable) | mode using | | 470 | .mozilla.org/nss/searc | | ``NSS_FIPS`` | | 471 | h?q=NSS_FORCE_FIPS>`__ | | | | 472 +------------------------+------------------------+------------------------+------------------------+ 473 | ``OS_TARGET`` | String | For cross-compilation | Before 3.0 | 474 | | (target OS) | environments only, | | 475 | | | when the target OS is | | 476 | | | not the default for | | 477 | | | the system on which | | 478 | | | the build is | | 479 | | | performed. | | 480 +------------------------+------------------------+------------------------+------------------------+ 481 | ``USE_64`` | Boolean | On platforms that has | Before 3.0 | 482 | | (1 to enable) | separate 32-bit and | | 483 | | | 64-bit ABIs, NSS | | 484 | | | builds for the 32-bit | | 485 | | | ABI by default. This | | 486 | | | tells NSS to build for | | 487 | | | the 64-bit ABI. | | 488 +------------------------+------------------------+------------------------+------------------------+ 489 | ``USE_DEBUG_RTL`` | Boolean | On Windows, MSVC has | Before 3.0 | 490 | | (1 to enable) | options to build with | | 491 | | | a normal Run Time | | 492 | | | Library or a debug Run | | 493 | | | Time Library. This | | 494 | | | tells NSS to build | | 495 | | | with the Debug Run | | 496 | | | Time Library. | | 497 +------------------------+------------------------+------------------------+------------------------+ 498 | ``USE_PTHREADS`` | Boolean | On platforms where | Before 3.0 | 499 | | (1 to enable) | POSIX threads are | | 500 | | | available, but are not | | 501 | | | the OS'es preferred | | 502 | | | threads library, this | | 503 | | | tells NSS and NSPR to | | 504 | | | build using pthreads. | | 505 +------------------------+------------------------+------------------------+------------------------+ 506 | `` | String | Disables at | Before 3.15 | 507 | NSS_NO_PKCS11_BYPASS`` | (1 to enable) | compile-time the NS | | 508 | | | ssl code to bypass the | | 509 | | | pkcs11 layer. When set | | 510 | | | the SSLBYPASS run-time | | 511 | | | variable won't take | | 512 | | | effect | | 513 +------------------------+------------------------+------------------------+------------------------+