| Home | Trees | Indices | Help |
|---|
|
|
object --+
|
io.Socket --+
|
SSLSocket
SSLSocket(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)
Create a new NSPR SSL socket:
|
|||
|
|||
| a new object with type S, a subtype of T |
|
||
| (Socket, NetworkAddress) |
|
||
|
|||
| string) |
|
||
| [(level, string),...] |
|
||
| str |
|
||
|
|||
|
|||
|
|||
| Certficate |
|
||
| enabled |
|
||
|
|||
| string |
|
||
| Certficate |
|
||
|
|||
| on, cipher, key_size, secret_key_size, issuer, subject |
|
||
| id |
|
||
| SSLChannelInfo |
|
||
| value |
|
||
| (min_version, max_version) |
|
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
Inherited from |
|||
|
|||
| Socket |
|
||
|
Inherited from |
|||
|
|||
|
|||
|
|
The socket is a rendezvous socket that has been bound to an address with Socket.bind() and is listening for connections after a call to Socket.listen(). Socket.accept() accepts the first connection from the queue of pending connections and creates a new socket for the newly accepted connection. The rendezvous socket can still be used to accept more connections. Socket.accept() blocks the calling thread until either a new connection is successfully accepted or an error occurs. If the timeout parameter is not PR_INTERVAL_NO_TIMEOUT and no pending connection can be accepted before the time limit, Socket.accept() raises a nss.error.NSPRError exception with the error code PR_IO_TIMEOUT_ERROR. Socket.accept() returns a tuple containing a new Socket object and Networkaddress object for the peer.
|
|
|
Formats the object into a sequence of lines with indent level information. The return value is a list where each list item is a tuple. The first item in the tuple is an integer representing the indentation level for that line. Any remaining items in the tuple are strings to be output on that line. The output of this function can be formatted into a single string by calling nss.nss.indented\_format(), e.g.: print indented_format(obj.format_lines()) The reason this function returns a tuple as opposed to an single indented string is to support other text formatting systems such as GUI's with indentation controls. See nss.nss.indented\_format() for a complete explanation.
|
Returns the number of bytes waiting in internal SSL buffers to be read by the local application from the SSL socket. If SSL_SECURITY has not been enabled with a call to ssl.set\_ssl\_default\_option() or SSLSocket.set\_ssl\_option(), the function returns zero. |
Drives a handshake for a specified SSLSocket to completion on a socket that has already been prepared to do a handshake or is in the middle of doing a handshake. When you are forcing the initial handshake on a blocking socket, this function returns when the handshake is complete. For subsequent handshakes, the function can return either because the handshake is complete, or because application data has been received on the connection that must be processed (that is, the application must read it) before the handshake can continue. You can use SSLSocket.force\_handshake() when a handshake is desired but neither end has anything to say immediately. This occurs, for example, when an HTTPS server has received a request and determines that before it can answer the request, it needs to request an authentication certificate from the client. At the HTTP protocol level, nothing more is being said (that is, no HTTP request or response is being sent), so the server uses SSLSocket.force\_handshake() to make the handshake occur. SSLSocket.force\_handshake() does not prepare a socket to do a handshake by itself. The following functions prepare a socket to do a handshake:
A call to SSLSocket.force\_handshake() will almost always be preceded by one of those functions. In versions prior to NSS 1.2, you cannot force a subsequent handshake. If you use this function after the initial handshake, it returns immediately without forcing a handshake. |
|
|
|
Gets information about the security parameters of the current connection. Returns the tuple (on, cipher, key_size, secret_key_size, issuer, subject)
|
|
|
|
Causes SSL to begin a new SSL 3.0 handshake on a connection that has already completed one handshake. If flush_cache is True, the SSLSocket.rehandshake() function invalidates the current SSL session associated with the specified SSLSocket from the session cache and starts another full SSL 3.0 handshake. It is for use with SSL 3.0 only. You can call this function to redo the handshake if you have changed one of the socket's configuration parameters (for example, if you are going to request client authentication). Setting flush_cache to False can be useful, for example, if you are using export ciphers and want to keep changing the symmetric keys to foil potential attackers. SSLSocket.rehandshake() only initiates the new handshake by sending the first message of that handshake. To drive the new handshake to completion, you must either call SSLSocket.force\_handshake() or do another I/O operation (read or write) on the socket. A call to SSLSocket.rehandshake() is typically followed by a call to SSLSocket.force\_handshake().
|
|
|
set_auth_certificate_callback(callback, [user_data1, ...]) The callback has the following signature: callback(socket, check_sig, is_server, [user_data1, ...]) -> bool
The callback function should return True if authentication is successful, False otherwise. If authentication is not successful the callback should indicate the reason for the failure (if possible) by calling nss.set_error() with the appropriate error code. The callback function obtains the certificate to be authenticated by calling ssl.get_peer_certificate(). If is_server is false, the callback should also check that the domain name in the remote server's certificate matches the desired domain name specified in a previous call to ssl.set_hostname(). To obtain that domain name, the callback calls ssl.get_hostname(). The callback may need to call one or more PK11 functions to obtain the services of a PKCS 11 module. Some of the PK11 functions require a PIN argument (see ssl.set_pkcs11_pin_arg() for details). To obtain the value that was set with ssl.set_pkcs11_pin_arg(), the callback calls ssl.get_pkcs11_pin_arg(). If the callback returns False, the SSL connection is terminated immediately unless the application has supplied a bad-certificate callback function by having previously called ssl.set_bad_cert_callback(). A bad-certificate callback function gives the application the opportunity to choose to accept the certificate as authentic and authorized even though it failed the check performed by the certificate authentication callback function. Example:
def auth_certificate_callback(sock, check_sig, is_server, certdb):
cert_is_valid = False
cert = sock.get_peer_certificate()
pin_args = sock.get_pkcs11_pin_arg()
if pin_args is None:
pin_args = ()
# Define how the cert is being used based upon the is_server flag. This may
# seem backwards, but isn't. If we're a server we're trying to validate a
# client cert. If we're a client we're trying to validate a server cert.
if is_server:
intended_usage = nss.certificateUsageSSLClient
else:
intended_usage = nss.certificateUsageSSLServer
try:
# If the cert fails validation it will raise an exception, the errno attribute
# will be set to the error code matching the reason why the validation failed
# and the strerror attribute will contain a string describing the reason.
approved_usage = cert.verify_now(certdb, check_sig, intended_usage, *pin_args)
except Exception, e:
cert_is_valid = False
return cert_is_valid
# Is the intended usage a proper subset of the approved usage
if approved_usage & intended_usage:
cert_is_valid = True
else:
cert_is_valid = False
# If this is a server, we're finished
if is_server or not cert_is_valid:
return cert_is_valid
# Certificate is OK. Since this is the client side of an SSL
# connection, we need to verify that the name field in the cert
# matches the desired hostname. This is our defense against
# man-in-the-middle attacks.
hostname = sock.get_hostname()
try:
# If the cert fails validation it will raise an exception
cert_is_valid = cert.verify_hostname(hostname)
except Exception, e:
cert_is_valid = False
return cert_is_valid
return cert_is_valid
|
|
Sets preference for the specified SSL2, SSL3, or TLS cipher on the socket. 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.
|
set_client_auth_data_callback(callback, [user_data1, ...]) The callback has the following signature: callback(ca_names, [user_data1, ...]) -> (Certificate, PrivateKey)
The callback returns Certificate and PrivateKey if successful, or None if the callback failed. Defines a callback function for SSL to use in a client application when a server asks for client authentication information. This callback function is required if your client application is going to support client authentication. The callback function set with SSLSocket.set\_client\_auth\_data\_callback() is used to get information from a client application when authentication is requested by the server. The callback function retrieves the client's private key and certificate. SSL provides an implementation of this callback function; see NSS_GetClientAuthData for details. Unlike SSL_AuthCertificate, NSS_GetClientAuthData is not a default callback function. You must set it explicitly with SSLSocket.set\_client\_auth\_data\_callback() if you want to use it. Example:
def client_auth_data_callback(ca_names, chosen_nickname, password, certdb):
cert = None
if chosen_nickname:
try:
cert = nss.find_cert_from_nickname(chosen_nickname, password)
priv_key = nss.find_key_by_any_cert(cert, password)
return cert, priv_key
except NSPRError, e:
return False
else:
nicknames = nss.get_cert_nicknames(certdb, nss.SEC_CERT_NICKNAMES_USER)
for nickname in nicknames:
try:
cert = nss.find_cert_from_nickname(nickname, password)
if cert.check_valid_times():
if cert.has_signer_in_ca_names(ca_names):
priv_key = nss.find_key_by_any_cert(cert, password)
return cert, priv_key
except NSPRError, e:
pass
return False
sock = ssl.SSLSocket(net_addr.family)
sock.set_client_auth_data_callback(client_auth_data_callback, nickname, password, nss.get_default_certdb())
|
set_handshake_callback(callback, [user_data1, ...]) The callback has the following signature: callback(socket, [user_data1, ...])
Sets up a callback function used by SSL to inform either a client application or a server application when the handshake is completed. Example:
def handshake_callback(sock):
print 'handshake complete, peer = %s' % (sock.get_peer_name())
sock = ssl.SSLSocket(net_addr.family)
sock.set_handshake_callback(handshake_callback)
|
|
|
Associates a peer ID with a socket to facilitate looking up the SSL session when it is tunneling through a proxy. SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a session cache, which retains information about each connection for some predetermined length of time. For example, a client session cache includes the hostname and port number of each server the client connects with, plus additional information such as the master secret generated during the SSL handshake. For a direct connection with a server, the hostname and port number are sufficient for the client to identify the server as one for which it has an entry in its session cache. However, the situation is more complicated if the client is on an intranet and is connecting to a server on the Internet through a proxy. In this case, the client first connects to the proxy, and the client and proxy exchange messages specified by the proxy protocol that allow the proxy, in turn, to connect to the requested server on behalf of the client. This arrangement is known as SSL tunneling. Client session cache entries for SSL connections that tunnel through a particular proxy all have the same hostname and port number--that is, the hostname and port number of the proxy. To determine whether a particular server with which the client is attempting to connect has an entry in the session cache, the session cache needs some additional information that identifies that server. This additional identifying information is known as a peer ID. The peer ID is associated with a socket, and must be set before the SSL handshake occurs--that is, before the SSL handshake is initiated by a call to a function such as SSLSocket.read() or SSLSocket.force\_handshake(). To set the peer ID, you use SSLSocket.set\_sock\_peer\_id(). In summary, SSL uses three pieces of information to identify a server's entry in the client session cache: the hostname, port number, and peer ID. In the case of a client that is tunneling through a proxy, the hostname and port number identify the proxy, and the peer ID identifies the desired server. It is recommended that the client set the peer ID to a string that consists of the server's hostname and port number, like this:'www.hostname.com:387'. This convention guarantees that each server has a unique entry in the client session cache.
|
Sets a single configuration parameter on this socket. Call once for each parameter you want to change. The configuration parameters are listed below.
Keep the following in mind when deciding on the operating parameters you want to use with a particular socket. Turning on SSL_REQUIRE_CERTIFICATE will have no effect unless SSL_REQUEST_CERTIFICATE is also turned on. If you enable SSL_REQUEST_CERTIFICATE, then you should explicitly enable or disable SSL_REQUIRE_CERTIFICATE rather than allowing it to default. Enabling the SSL_REQUIRE_CERTIFICATE option is not recommended. If the client has no certificate and this option is enabled, the client's connection terminates with an error. The user is likely to think something is wrong with either the client or the server, and is unlikely to realize that the problem is the lack of a certificate. It is better to allow the SSL handshake to complete and then return an error message to the client that informs the user of the need for a certificate. The SSL protocol is defined to be able to handle simultaneous two-way communication between applications at each end of an SSL connection. Two-way simultaneous communication is also known as'Full Duplex', abbreviated FDX. However, most application protocols that use SSL are not two-way simultaneous, but two-way alternate, also known as 'Half Dupled'; that is, each end takes turns sending, and each end is either sending, or receiving, but not both at the same time. For an application to do full duplex, it would have two threads sharing the socket; one doing all the reading and the other doing all the writing. The SSL_ENABLE_FDX option tells the SSL library whether the application will have two threads, one reading and one writing, or just one thread doing reads and writes alternately. If an SSL3 client hello message is sent to a server that only understands SSL2 and not SSL3, then the server will interpret the SSL3 client hello as a very large message, and the connection will usually seem to 'hang' while the SSL2 server expects more data that will never arrive. For this reason, the SSL3 spec allows SSL3 client hellos to be sent in SSL2 format, and it recommends that SSL3 servers all accept SSL3 client hellos in SSL2 format. When an SSL2-only server receives an SSL3 client hello in SSL2 format, it can (and probably will) negotiate the protocol version correctly, not causing a 'hang'. Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does not understand SSL2-compatible client hello messages. SSL_V2_COMPATIBLE_HELLO tells the SSL library whether or not to send SSL3 client hello messages in SSL2-compatible format. Note that calling SSLSocket.set\_ssl\_option() to set SSL_V2_COMPATIBLE_HELLO to False implicitly also sets the SSL_ENABLE_SSL2 option to False for that SSL socket. Calling SSL_EnableDefault to change the application default setting for SSL_V2_COMPATIBLE_HELLO to False implicitly also sets the default value for SSL_ENABLE_SSL2 option to False for that application. The options SSL_ENABLE_SSL2, SSL_ENABLE_SSL3, and SSL_ENABLE_TLS can each be set to True or False independently of each other. NSS 2.8 and later versions will negotiate the highest protocol version with the peer application from among the set of protocols that are commonly enabled in both applications. [1] Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled, all SSL3/TLS cipher suites that are enabled are enabled for both SSL3 and TLS. When an application imports a socket into SSL after the TCP connection on that socket has already been established, it must call SSLSocket.reset\_handshake() to indicate whether the socket is for a client or server. At first glance this may seem unnecessary, since SSLSocket.set\_ssl\_option() can set SSL_HANDSHAKE_AS_CLIENT or SSL_HANDSHAKE_AS_SERVER. However, these settings control the behavior of SSLSocket.connect() and SSLSocket.accept() only; if you don't call one of those functions after importing a non-SSL socket with SSL_Import (as in the case of an already established TCP connection), SSL still needs to know whether the application is functioning as a client or server. If a socket file descriptor is imported as an SSL socket before it is connected, it is implicitly configured to handshake as a client or handshake as a server when the connection is made. If the application calls SSLSocket.connect() (connecting as a TCP client), then the SSL socket is (by default) configured to handshake as an SSL client. If the application calls SSLSocket.accept() (connecting the socket as a TCP server) then the SSL socket is (by default) configured to handshake as an SSL server. SSL_HANDSHAKE_AS_CLIENT and SSL_HANDSHAKE_AS_SERVER control this implicit configuration. Both SSL_HANDSHAKE_AS_CLIENT and SSL_HANDSHAKE_AS_SERVER are initially set to off--that is, the process default for both values is False when the process begins. The process default can be changed from the initial values by using SSL_EnableDefault, and the value for a particular socket can be changed by using SSLSocket.set\_ssl\_option(). If a socket that is already connected gets imported into SSL after it has been connected (that is, after SSLSocket.accept() or SSLSocket.connect() has returned), then no implicit SSL handshake configuration as a client or server will have been done by SSLSocket.connect() or SSLSocket.accept() on that socket. In this case, a call to SSLSocket.reset\_handshake() is required to explicitly configure the socket to handshake as a client or as a server. If SSLSocket.reset\_handshake() is not called to explicitly configure the socket handshake, a crash is likely to occur when the first I/O operation is done on the socket after it is imported into SSL.
|
|
| Home | Trees | Indices | Help |
|---|
| Generated by Epydoc 3.0.1 | http://epydoc.sourceforge.net |