API Documentation¶

This package provides a high-level interface to manage, generate certificates and run a SOCKS service in Twisted framework. The following modules are defined:

CertStore¶

class sockssl.certstore.CertStore(root_cert=None, root_key=None)¶

Manage Root Certificate Authority, and generate Dummy Certificate

__init__(root_cert=None, root_key=None)¶

Create a CertStore instance

Parameters

root_cert (OpenSSL.crypto.X509, optional) – rootCA certificate - x509 instance. Defaults to None.
root_key (OpenSSL.crypto.PKey, optional) – rootCA private key - PKey instance. Defaults to None.

dummy_ctx(sni)¶

Get SSL context of dummy ceritficate from SNI list. Use for passing to twisted StartTLS

Parameters: sni (List[str]) – List of domain name, ips
Returns: twisted.internet._sslverify.OpenSSLCertificateOptions

dump_root_cert(filename, format='PEM')¶

Dump rootCA certificate to file

Parameters

filename (str) – path to certificate file
format (str, optional) – format of certificate, support PEM/DER. Defaults to “PEM”.

dump_root_key(filename, format='PEM')¶

Dump rootCA private key to file

Parameters

filename (str) – path to private key file
format (str, optional) – format of private key, support PEM/DER. Defaults to “PEM”.

gen_root_ca(org, cn, exp=94608000, key_size=2048)¶

Generate rootCA certificate + privatekey and store in root_key, root_cert

Parameters

org (str) – Organization name
cn (str) – Common Name
exp (int, optional) – Expiration time in second. Defaults to 94608000 == 3 years
key_size (int, optional) – RSA key size (1024/2048/…). Defaults to 2048.

load_root_cert(filename, format='PEM')¶

Load rootCA certificate from file

Parameters

filename (str) – path to certificate file
format (str, optional) – format of certificate, support PEM/DER. Defaults to “PEM”.

load_root_key(filename, format='PEM')¶

Load rootCA private key from file

Parameters

filename (str) – path to private key file
format (str, optional) – format of private key, support PEM/DER. Defaults to “PEM”.

root_cert = None¶: OpenSSL.crypto.x509 (certificate) instance of rootCA

root_ctx()¶

Get SSL context of rootCA ceritficate. Use for passing to twisted StartTLS

Returns: twisted.internet._sslverify.OpenSSLCertificateOptions

root_key = None¶: OpenSSL.crypto.PKey (private key) instance of rootCA

sockssl.certstore.find_client_hello(packet)¶

Parse ClientHello Packet of TLS 1.2

Parameters: packet (bytes) – stream of packet
Returns: TlsClientHello

sockssl.certstore.is_sni(obj)¶

Check if an object is SNI instance

Parameters: obj (object) –
Returns: bool

Service¶

class sockssl.service.SockService(host=None, port=None, cert_store=None, protocol=None, users=None, data=None)¶

Service class to manage certstore and serve your socks protocol

__init__(host=None, port=None, cert_store=None, protocol=None, users=None, data=None)¶

Create a SockService instance

Parameters

host (Optional[str], optional) – Interface as ip or hostname. Defaults to None.
port (Optional[int], optional) – Port in integer. Defaults to None.
cert_store (Optional[CertStore], optional) – Instance of CertStore Class. Defaults to None.
protocol (Any, optional) – Class of protocol you want to serve. Defaults to None.
users (Any, optional) – Auth users data of protocol. List[str] for SOCKSv4, List[Tuple[str, str]] for SOCKSv5. Defaults to None.
data (Any, optional) – Global data for that protocol (like auth data), will pass to SockFactory. Defaults to None.

serve_forever()¶: Listen TCP and run reactor forever

set_cert_store(cert_store=None)¶

Set CertStore instance to intercept TLS traffic.: Set to None if you don’t want to do TLS mitm.

Parameters: cert_store (Optional[CertStore], optional) – Instance of CertStore Class. Defaults to None.

set_data(data=None)¶

Set global data share between connection

Parameters: data (Any, optional) – Global data for that protocol (like auth data), will pass to SockFactory. Defaults to None.

set_host_port(host, port)¶

Set listen interface and port for service

Parameters

host (str) – Interface as ip or hostname
port (int) – Port in integer

set_protocol(protocol, users=None)¶

Set protocol and users data for service to serve, usually SOCKv4 or SOCKSv5.

Parameters

protocol (Any) – Class of protocol you want to serve
users (Any, optional) – Auth users data of protocol. List[str] for SOCKSv4, List[Tuple[str, str]] for SOCKSv5. Defaults to None.

Factory¶

class sockssl.factory.SockFactory(protocol, users=None, cert_store=None, data=None)¶

Twisted framework Protocol Factory: store global context and produce protocol handler for each connection

__init__(protocol, users=None, cert_store=None, data=None)¶

Create a SockFactory instance

Parameters

protocol (Any) – Class of protocol. SOCKSv4, SOCKSv5, … or your class
users (Any, optional) – Auth users data of protocol. Defaults to None.
cert_store (Optional[CertStore], optional) – Instance of CertStore to do TLS mitm. Defaults to None.
data (Any, optional) – Global data variable share between connection. Defaults to None.

Protocols¶

class sockssl.protocol.SOCKSv4(logging=None, reactor=<twisted.internet.epollreactor.EPollReactor object>)¶: Implementation of SOCKSv4 protocol compatiables with ISOCKS interface

class sockssl.protocol.SOCKSv5(reactor=<twisted.internet.epollreactor.EPollReactor object>)¶: Implementation of SOCKSv5 protocol compatiables with ISOCKS interface

Interface¶

class sockssl.protocol.isocks.ISOCKS¶

Interface to interact with SOCKS protocol

addr_client: <InterfaceClass twisted.internet.interfaces.IAddress> = None¶: Client information

addr_server: <InterfaceClass twisted.internet.interfaces.IAddress> = None¶: Server information

factory: <InterfaceClass twisted.internet.interfaces.IProtocolFactory> = None¶: Factory instance of current protocol connection

on_connect()¶: Trigger when a client connected

on_disconnect()¶: Trigger when client disconnected

on_recv_client(data)¶

Process data sent from client to server

Parameters: data (bytes) – Data from client
Returns: bytes – Data will be sent to server

on_recv_server(data)¶

Process data sent back from server to client

Parameters: data (bytes) – Data got from server
Returns: bytes – Data will be sent back to client

on_socks_established()¶: Trigger when a SOCKS tunnel established

on_socks_failed()¶: Trigger when a SOCKS connection failed to establish