You are viewing information archived from Mozilla.org on 2014-10-02.

Package nss :: Module ssl

[frames] | no frames]

Module ssl

This module implements the SSL functionality in NSS

Classes

[hide private]

SSLSocket
SSLSocket(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)

Functions

[hide private]

clear_session_cache()
You must call ssl.clear_session_cache() after you use one of the SSL Export Policy Functions to change cipher suite policy settings or use ssl.set_default_cipher_pref() to enable or disable any cipher suite.

config_mp_server_sid_cache(max_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None)
This function sets up a Server Session ID (SID) cache that is safe for access by multiple processes on the same system.

config_server_session_id_cache(max_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None)
If you are writing an application which will use SSL sockets to handshake as a server, you must call config_server_session_id_cache() to configure the session caches for server sessions.

config_server_session_id_cache_with_opt(max_cache_entries=0, max_cert_cache_entries=0, max_server_name_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None, enable_mp_cache=False)
Configure a secure server's session-id cache.

policy

get_cipher_policy(cipher)
Returns the cipher policy.

enabled

get_default_cipher_pref(cipher)
Returns the application default preference for the specified SSL2, SSL3, or TLS cipher.

int

get_max_server_cache_locks()
Get the configured maximum number of mutexes used for the server's store of SSL sessions.

get_ssl_default_option(value)
Gets the default value of a specified SSL option for all subsequently opened sockets as long as the current application program is running.

nss_init(cert_dir)
WARNING: nss_init() has been moved to the nss module, use nss.nss_init() instead of ssl.nss_init()

nss_shutdown()
WARNING: nss_shutdown() has been moved to the nss module, use nss.nss_shutdown() instead of ssl.nss_shutdown()

nssinit(cert_dir)
WARNING: nssinit() has been moved to the nss module, use nss.nss_init() instead of ssl.nssinit()

set_cipher_policy(cipher, enabled)
Tells the SSL library that the specified cipher suite is allowed by the application's export license, or is not allowed by the application's export license, or is allowed to be used only with a Step-Up certificate.

set_default_cipher_pref(cipher, enabled)
Sets the application default preference for the specified SSL2, SSL3, or TLS cipher.

set_domestic_policy()
Configures cipher suites to conform with current U.S.

set_export_policy()
Configures the SSL cipher suites to conform with current U.S.

set_france_policy()
Configures the SSL cipher suites to conform with French import regulations related to software products with encryption features.

set_max_server_cache_locks(max_locks)
Set the configured maximum number of mutexes used for the server's store of SSL sessions.

set_ssl_default_option(option, value)
Changes the default value of a specified SSL option for all subsequently opened sockets as long as the current application program is running.

shutdown_server_session_id_cache()

Variables

[hide private]

SSL_ALLOWED = 1

SSL_BYPASS_PKCS11 = 16

SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = 17

SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA = 19

SSL_DHE_DSS_WITH_DES_CBC_SHA = 18

SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = 20

SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA = 22

SSL_DHE_RSA_WITH_DES_CBC_SHA = 21

SSL_DH_ANON_EXPORT_WITH_DES40_CBC_SHA = 25

SSL_DH_ANON_EXPORT_WITH_RC4_40_MD5 = 23

SSL_DH_ANON_WITH_3DES_EDE_CBC_SHA = 27

SSL_DH_ANON_WITH_DES_CBC_SHA = 26

SSL_DH_ANON_WITH_RC4_128_MD5 = 24

SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = 11

SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA = 13

SSL_DH_DSS_WITH_DES_CBC_SHA = 12

SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = 14

SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA = 16

SSL_DH_RSA_WITH_DES_CBC_SHA = 15

SSL_ENABLE_FDX = 11

SSL_ENABLE_SSL2 = 7

SSL_ENABLE_SSL3 = 8

SSL_ENABLE_TLS = 13

SSL_EN_DES_192_EDE3_CBC_WITH_MD5 = 65287

SSL_EN_DES_64_CBC_WITH_MD5 = 65286

SSL_EN_IDEA_128_CBC_WITH_MD5 = 65285

SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5 = 65284

SSL_EN_RC2_128_CBC_WITH_MD5 = 65283

SSL_EN_RC4_128_EXPORT40_WITH_MD5 = 65282

SSL_EN_RC4_128_WITH_MD5 = 65281

SSL_HANDSHAKE_AS_CLIENT = 5

SSL_HANDSHAKE_AS_SERVER = 6

SSL_NOT_ALLOWED = 0

SSL_NO_CACHE = 9

SSL_NO_LOCKS = 17

SSL_NO_STEP_DOWN = 15

SSL_NULL_WITH_NULL_NULL = 0

SSL_REQUEST_CERTIFICATE = 3

SSL_REQUIRE_ALWAYS = 1

SSL_REQUIRE_CERTIFICATE = 10

SSL_REQUIRE_FIRST_HANDSHAKE = 2

SSL_REQUIRE_NEVER = 0

SSL_REQUIRE_NO_ERROR = 3

SSL_RESTRICTED = 2

SSL_ROLLBACK_DETECTION = 14

SSL_RSA_EXPORT_WITH_DES40_CBC_SHA = 8

SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = 6

SSL_RSA_EXPORT_WITH_RC4_40_MD5 = 3

SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA = 65279

SSL_RSA_FIPS_WITH_DES_CBC_SHA = 65278

SSL_RSA_WITH_3DES_EDE_CBC_SHA = 10

SSL_RSA_WITH_DES_CBC_SHA = 9

SSL_RSA_WITH_IDEA_CBC_SHA = 7

SSL_RSA_WITH_NULL_MD5 = 1

SSL_RSA_WITH_NULL_SHA = 2

SSL_RSA_WITH_RC4_128_MD5 = 4

SSL_RSA_WITH_RC4_128_SHA = 5

SSL_SECURITY = 1

SSL_SECURITY_STATUS_NOOPT = -1

SSL_SECURITY_STATUS_OFF = 0

SSL_SECURITY_STATUS_ON_HIGH = 1

SSL_SECURITY_STATUS_ON_LOW = 2

SSL_SOCKS = 2

SSL_V2_COMPATIBLE_HELLO = 12

TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA = 99

TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA = 101

TLS_DHE_DSS_WITH_AES_128_CBC_SHA = 50

TLS_DHE_DSS_WITH_AES_256_CBC_SHA = 56

TLS_DHE_DSS_WITH_RC4_128_SHA = 102

TLS_DHE_RSA_WITH_AES_128_CBC_SHA = 51

TLS_DHE_RSA_WITH_AES_256_CBC_SHA = 57

TLS_DH_ANON_WITH_AES_128_CBC_SHA = 52

TLS_DH_ANON_WITH_AES_256_CBC_SHA = 58

TLS_DH_DSS_WITH_AES_128_CBC_SHA = 48

TLS_DH_DSS_WITH_AES_256_CBC_SHA = 54

TLS_DH_RSA_WITH_AES_128_CBC_SHA = 49

TLS_DH_RSA_WITH_AES_256_CBC_SHA = 55

TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA = 49160

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA = 49161

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA = 49162

TLS_ECDHE_ECDSA_WITH_NULL_SHA = 49158

TLS_ECDHE_ECDSA_WITH_RC4_128_SHA = 49159

TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA = 49170

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA = 49171

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA = 49172

TLS_ECDHE_RSA_WITH_NULL_SHA = 49168

TLS_ECDHE_RSA_WITH_RC4_128_SHA = 49169

TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA = 49155

TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA = 49156

TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA = 49157

TLS_ECDH_ECDSA_WITH_NULL_SHA = 49153

TLS_ECDH_ECDSA_WITH_RC4_128_SHA = 49154

TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA = 49165

TLS_ECDH_RSA_WITH_AES_128_CBC_SHA = 49166

TLS_ECDH_RSA_WITH_AES_256_CBC_SHA = 49167

TLS_ECDH_RSA_WITH_NULL_SHA = 49163

TLS_ECDH_RSA_WITH_RC4_128_SHA = 49164

TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA = 49175

TLS_ECDH_anon_WITH_AES_128_CBC_SHA = 49176

TLS_ECDH_anon_WITH_AES_256_CBC_SHA = 49177

TLS_ECDH_anon_WITH_NULL_SHA = 49173

TLS_ECDH_anon_WITH_RC4_128_SHA = 49174

TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA = 98

TLS_RSA_EXPORT1024_WITH_RC4_56_SHA = 100

TLS_RSA_WITH_AES_128_CBC_SHA = 47

TLS_RSA_WITH_AES_256_CBC_SHA = 53

_C_API = <PyCObject object at 0x9ec2e00>

__package__ = None

ssl_implemented_ciphers = (49162, 49172, 136, 135, 57, 56, 491...

Function Details

[hide private]

clear_session_cache()

You must call ssl.clear_session_cache() after you use one of the SSL Export Policy Functions to change cipher suite policy settings or use ssl.set_default_cipher_pref() to enable or disable any cipher suite. Otherwise, the old settings remain in the session cache and will be used instead of the new settings. This function clears only the client cache. The client cache is not configurable. It is located in RAM (not on disk).

config_mp_server_sid_cache(max_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None)

This function sets up a Server Session ID (SID) cache that is safe for access by multiple processes on the same system.

Like ssl.config_server_session_id_cache(), with one important difference. If the application will run multiple processes (as opposed to, or in addition to multiple threads), then it must call this function, instead of calling ssl.config_server_session_id_cache(). This has nothing to do with the number of processors, only processes.

Parameters:

max_cache_entries (integer) - The maximum number of entries in the cache. If ZERO the server default value is used (10,000).
ssl2_timeout (integer) - The lifetime in seconds of an SSL2 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (100 seconds).
ssl3_timeout (integer) - The lifetime in seconds of an SSL3 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (24 hours).
directory (string) - A string specifying the pathname of the directory that will contain the session cache. If None the server default value is used (/tmp (Unix) or temp (NT)).

config_server_session_id_cache(max_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None)

If you are writing an application which will use SSL sockets to handshake as a server, you must call config_server_session_id_cache() to configure the session caches for server sessions.

If your server application uses multiple processes (instead of or in addition to multiple threads), use ssl.config_mp_server_sid_cache() instead. You must use one of these functions to create a server cache.

This function creates two caches: the server session ID cache (also called the server session cache, or server cache), and the client-auth certificate cache (also called the client cert cache, or client auth cache). Both caches are used only for sessions where the program will handshakes as a server. The client-auth certificate cache is used to remember the certificates previously presented by clients for client certificate authentication.

A zero value or a value that is out of range for any of the parameters causes the server default value to be used in the server cache. Note, this function only affects the server cache, not the client cache.

Parameters:

max_cache_entries (integer) - The maximum number of entries in the cache. If ZERO the server default value is used (10,000).
ssl2_timeout (integer) - The lifetime in seconds of an SSL2 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (100 seconds).
ssl3_timeout (integer) - The lifetime in seconds of an SSL3 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (24 hours).
directory (string) - A string specifying the pathname of the directory that will contain the session cache. If None the server default value is used (/tmp (Unix) or temp (NT)).

config_server_session_id_cache_with_opt(max_cache_entries=0, max_cert_cache_entries=0, max_server_name_cache_entries=0, ssl2_timeout=0, ssl3_timeout=0, directory=None, enable_mp_cache=False)

Configure a secure server's session-id cache. Depends on value of enable_mp_cache, configures multi-proc or single proc cache.

Parameters:

max_cache_entries (integer) - The maximum number of entries in the cache. If ZERO the server default value is used (10,000).
max_cert_cache_entries (integer) - The maximum number of entries in the cert cache. If ZERO the server default value is used (10,000).
max_server_name_cache_entries (integer) - The maximum number of entries in the server name cache. If ZERO the server default value is used (10,000).
ssl2_timeout (integer) - The lifetime in seconds of an SSL2 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (100 seconds).
ssl3_timeout (integer) - The lifetime in seconds of an SSL3 session. The minimum timeout value is 5 seconds and the maximum is 24 hours. Values outside this range are replaced by the server default value (24 hours).
directory (string) - A string specifying the pathname of the directory that will contain the session cache. If None the server default value is used (/tmp (Unix) or temp (NT)).
enable_mp_cache (bool) - If True enable the multi-process cache.

get_cipher_policy(cipher)

Returns the cipher policy.

Parameters:

cipher (integer) - The cipher suite enumeration (e.g. SSL_RSA_WITH_NULL_MD5, etc.)

Returns: policy

get_default_cipher_pref(cipher)

Returns the application default preference for the specified SSL2, SSL3, or TLS cipher.

Parameters:

cipher (integer) - The cipher suite enumeration (e.g. SSL_RSA_WITH_NULL_MD5, etc.)

Returns: enabled

get_max_server_cache_locks()

Get the configured maximum number of mutexes used for the server's store of SSL sessions. This value is used by the server session ID cache initialization functions.

Returns: int

get_ssl_default_option(value)

Gets the default value of a specified SSL option for all subsequently opened sockets as long as the current application program is running. Refer to the documentation for SSLSocket.set_ssl_option() for an explanation of the possible values.

nss_init(cert_dir)

WARNING: nss_init() has been moved to the nss module, use nss.nss_init() instead of ssl.nss_init()

Sets up configuration files and performs other tasks required to run Network Security Services.

Parameters:

cert_dir (string) - Pathname of the directory where the certificate, key, and security module databases reside.

nss_shutdown()

WARNING: nss_shutdown() has been moved to the nss module, use nss.nss_shutdown() instead of ssl.nss_shutdown()

Closes the key and certificate databases that were opened by nss_init().

Note that if any reference to an NSS object is leaked (for example, if an SSL client application doesn't call clear_session_cache() first) then nss_shutdown fails with the error code SEC_ERROR_BUSY.

nssinit(cert_dir)

WARNING: nssinit() has been moved to the nss module, use nss.nss_init() instead of ssl.nssinit()

Sets up configuration files and performs other tasks required to run Network Security Services.

Parameters:

cert_dir (string) - Pathname of the directory where the certificate, key, and security module databases reside.

set_cipher_policy(cipher, enabled)

Tells the SSL library that the specified cipher suite is allowed by the application's export license, or is not allowed by the application's export license, or is allowed to be used only with a Step-Up certificate. It overrides the factory default policy for that cipher suite. The default policy for all cipher suites is SSL_NOT_ALLOWED, meaning that the application's export license does not approve the use of this cipher suite. A U.S.domestic version of a product typically sets all cipher suites to SSL_ALLOWED. This setting is used to separate export and domestic versions of a product, and is not intended to express user cipher preferences.

Parameters:

cipher (integer) - The cipher suite enumeration (e.g. SSL_RSA_WITH_NULL_MD5, etc.)
enabled (bool) - Boolean value

set_default_cipher_pref(cipher, enabled)

Sets the application default preference for the specified SSL2, SSL3, or TLS cipher. A cipher suite is used only if the policy allows it and the preference for it is set to True.

This function must be called once for each cipher you want to enable or disable by default.

Note, which cipher suites are permitted or disallowed are modified by previous calls to one or more of the SSL Export Policy Functions.

Parameters:

cipher (integer) - The cipher suite enumeration (e.g. SSL_RSA_WITH_NULL_MD5, etc.)
enabled (bool) - Boolean value

set_domestic_policy()

Configures cipher suites to conform with current U.S. export regulations related to domestic software products with encryption features.

set_export_policy()

Configures the SSL cipher suites to conform with current U.S. export regulations related to international software products with encryption features.

set_max_server_cache_locks(max_locks)

Set the configured maximum number of mutexes used for the server's store of SSL sessions. This value is used by the server session ID cache initialization functions. Note that on some platforms, these mutexes are actually implemented with POSIX semaphores, or with unnamed pipes. The default value varies by platform. An attempt to set a too-low maximum will return an error and the configured value will not be changed.

Parameters:

max_locks (int) - Maximum number of locks

set_ssl_default_option(option, value)

Changes the default value of a specified SSL option for all subsequently opened sockets as long as the current application program is running. Refer to the documentation for SSLSocket.set_ssl_option() for an explanation of the possible values.

Variables Details

[hide private]

ssl_implemented_ciphers

Value:

(49162,
 49172,
 136,
 135,
 57,
 56,
 49167,
 49157,
...