security.SecureSocket

security.SecureSocket

The agutil.security module includes the SecureSocket class, which wraps over an agutil.io.Socket instance. A SecureSocket class allows for encrypted communications using RSA or AES encryption. This class extends agutil.io.MPlexSocket, so in addition to the methods listed below, it supports all methods of the MPlexSocket class.

The previous agutil.security.SecureSocket class has been completely overhauled to provide lower-level functionality. For a class similar to the old SecureSocket see: SecureConnection.

API

• SecureSocket(address, port, password=None, rsabits=4096, timeout=3, logmethod=agutil.DummyLog) (Constructor)

  address and port are used to establish a connection to a remote socket. If password is set and not None, it is used to generate a new AES ECB cipher which provides the lowest level of encryption for the socket (used for basic communications between the sockets). Both sockets must use the same password. rsabits sets the size of the RSA keypair used for exchanging RSA messages with the remote socket. timeout sets the default timeout for receiving incoming messages (must be None, or a non-negative integer). logmethod specifies a logging object to use (it defaults to agutil.DummyLog), but may also be an agutil.Logger instance or a bound method returned by agutil.Logger.bindToSender().

• SecureSocket.send(msg, channel='\_\_rsa\_\_', sign='SHA-256')

• SecureScoket.sendRSA(msg, channel='\_\_rsa\_\_', sign='SHA-256') Encrypts msg using the remote socket's public key and sends over the channel channel. If msg is longer than the remote public key can encrypt, it is broken into chunks and each chunk is encrypted before transmission. sign can be False, or one of 'MD5', 'SHA-1', 'SHA-224', 'SHA-256', 'SHA-384', or 'SHA-512'. If sign is not False, the rsa signature of msg is computed using the specified hashing algorithm and sent to the remote socket.

• SecureSocket.recv(channel='\_\_rsa\_\_', decode=False, timeout=-1)

• SecureSocket.recvRSA(channel='\_\_rsa\_\_', decode=False, timeout=-1) Waits to receive a message on the channel channel, then decrypts using this socket's private key. If decode is true, the decrypted bytes object is decoded into a str object. timeout sets the maximum time allowed for any single operation with the remote socket (thus the .recvRSA method may take longer to complete as a whole). If timeout is -1, it defaults to the SecureSocket's default timeout parameter. If the remote socket elects to send a message signature (the default), the message will be verified against the signature. This will raise rsa.pkcs1.VerificationError if signature verification fails

• SecureSocket.sendAES(msg, channel='__aes__', key=False, iv=False) Encrypts msg using an AES cipher and sends to the remote socket over the channel channel. If msg is a BytesIO object, bytes will be read from the file and transmitted, instead of transmitting msg itself. If both key and iv are False, the cipher used for encryption is the same as the SecureSocket's base cipher (an ECB cipher if password was set in the constructor, or no cipher at all otherwise). If key is True or a bytes object, the cipher used for encryption is an AES ECB cipher using key as the key (if key is true, a random 32-byte key is generated). If both key and iv are True or bytes objects, the cipher used for encryption is an AES CBC cipher using key as the key and iv as the initialization vector (if key is true, a random 32-byte key is generated; if iv is true, a random 16-byte vector is generated). If an AES cipher is used that isn't the socket's base cipher, the key is transmitted using the .sendRSA method

• SecureScoket.recvAES(channel='__aes__', decode=False, timeout=-1, output_file=None) Waits to receive a message on channel then decrypts using an AES cipher. The type of cipher used is determined by the sending socket. timeout behaves identical to how it does in .recvRSA. If output_file is a BytesIO object, the decrypted data is written to that file. If it is a str object, that is used as a filename to output the decrypted data. Otherwise, the decrypted data is returned. If decode is True and output_file is None, then the decrypted bytes object is encoded to a str object before returning

• SecureSocket.sendRAW msg, channel='__raw__') Sends msg over the channel channel with no encryption

• SecureSocket.recvRAW(channel='__raw__', decode=False, timeout=-1) Waits to receive a message on channel then returns. Waits at most timeout seconds (or the default timeout of the SecureSocket if timeout is -1). If decode is True, then the received bytes object is decoded into a str object before returning

• SecureSocket.settimeout(timeout) Sets the default timeout to timeout

• SecureSocket.gettimeout() Returns the current default timeout

• SecureSocket.close() Closes the underlying Socket and terminates the connection