ssl
Provides OpenSSL bindings for Blade
Properties
- ssl.SSL_FILETYPE_PEM
- SSL_FILETYPE_PEM
- ssl.SSL_FILETYPE_ASN1
- SSL_FILETYPE_ASN1
- ssl.SSL_VERIFY_NONE
-
-
Server mode
: the server will not send a client certificate request to the client, so the client will not send a certificate. -
Client mode
: if not using an anonymous cipher (by default disabled), the server will send a certificate which will be checked. The handshake will be continued regardless of the verification result.
-
- ssl.SSL_VERIFY_PEER
-
-
Server mode
: the server sends a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. The behaviour can be controlled by the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT, SSL_VERIFY_CLIENT_ONCE and SSL_VERIFY_POST_HANDSHAKE flags. -
Client mode
: the server certificate is verified. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. If no server certificate is sent, because an anonymous cipher is used, SSL_VERIFY_PEER is ignored.
-
- ssl.SSL_VERIFY_FAIL_IF_NO_PEER_CERT
-
-
Server mode
: if the client did not return a certificate, the TLS/SSL handshake is immediately terminated with a “handshake failure” alert. This flag must be used together with SSL_VERIFY_PEER. -
Client mode
: ignored
-
- ssl.SSL_VERIFY_CLIENT_ONCE
-
-
Server mode
: only request a client certificate once during the connection. Do not ask for a client certificate again during renegotiation or post-authentication if a certificate was requested during the initial handshake. This flag must be used together with SSL_VERIFY_PEER. -
Client mode
: ignored
-
- ssl.SSL_VERIFY_POST_HANDSHAKE
-
-
Server mode
: the server will not send a client certificate request during the initial handshake, but will send the request via SSL_verify_client_post_handshake(). This allows the SSL_CTX or SSL to be configured for post-handshake peer verification before the handshake occurs. This flag must be used together with SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre-TLSv1.3 connections. -
Client mode
: ignored
-
- ssl.TLS_method
- TLS method
- ssl.TLS_client_method
- TLS client method
- ssl.TLS_server_method
- TLS server method
- ssl.SSLv23_method
- SSLv23 method
- ssl.SSLv23_client_method
- SSLv23 client method
- ssl.SSLv23_server_method
- SSLv23 server method
- ssl.BIO_CLOSE
- BIO_CLOSE
- ssl.BIO_NOCLOSE
- BIO_NOCLOSE
- ssl.BIO_f_ssl
- SSL BIO method f_ssl
I/O performed on an SSL BIO communicates using the SSL protocol with the SSLs read and write BIOs. If an SSL connection is not established then an attempt is made to establish one on the first I/O call.
- ssl.BIO_s_connect
- SSL BIO method connect
Using connect BIOs, TCP/IP connections can be made and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.
- ssl.BIO_s_accept
- SSL BIO method accept
Using accept BIOs, TCP/IP connections can be accepted and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.
Functions
- ssl.server(port: int, address: string)
- Creates an new TLSServer instance. returns TLSServerthrows Exception, SocketExcepion, HttpException
Classes
class SSL
SSL interface class
class SSL methods
- SSL(context: SSLContext)
- constructor
- set_connect_state()
- puts this SSL instance in the connected mode.
- set_accept_state()
- puts this SSL instance in the accept mode.
- get_fd()
- returns the current socket file descriptor. It returns
-1
on failure or a positive integer on success.return number - set_fd(fd: int)
- sets the socket file descriptor for this SSL
- accept()
- begins accepting data on SSL
- connect()
- connects to an SSL server instance
- write(data: string | bytes)
- writes data to the current I/O stream. return int representing the total bytes written
- read([length: int])
- reads data off the I/O and returns it default length = -1return string
- error([code: int])
- returns the last SSL error number return int
- shutdown()
- shutdown the SSL object
- free()
- frees this SSL and all associated resources
- get_pointer()
- returns the raw OpenSSl SSL pointer return ptr
class TLSSocket
TLS enabled Socket version powered by OpenSSL. @printable
class TLSSocket properties
- TLSSocket.host
- This property holds the host bound, to be bound to or connected to by the current socket. Whenever a host is not given, the host will default to localhost.
- TLSSocket.port
- The port currently bound or connected to by the socket
- TLSSocket.family
- The socket family (which must be one of the
AF_
variables). The default family for the socket is AF_INET - TLSSocket.type
- The type of socket stream used by the socket. The default socket type is
SOCK_STREAM
- TLSSocket.protocol
- The current operating protocol of the socket that controls the underlying behavior of the socket. The default is
IPPROTO_TCP
. - TLSSocket.id
- The file descriptor id of the current socket on the host machine.
- TLSSocket.is_client
true
when the socket is a client to a server socket,false
otherwise.- TLSSocket.is_bound
true
when the socket is bound to a given port on the device,false
otherwise.- TLSSocket.is_connected
true
when the socket is connected to a server socket,false
otherwise.- TLSSocket.is_listening
true
when the socket is currently listening on a host device port as a server,false
otherwise.- TLSSocket.is_closed
true
when the socket is closed,false
otherwise.- TLSSocket.is_shutdown
true
when the socket is shutdown,false
otherwise.- TLSSocket.is_blocking
true
when the socket is running in a blocking mode,false
otherwise.- TLSSocket.shutdown_reason
- The property holds the reason for which the last
shutdown
operation was called or-1
ifshutdown
was never requested. - TLSSocket.send_timeout
- The amount of time in milliseconds that the socket waits before it terminates a
send
operation. This is equal to theSO_SNDTIMEO
. - TLSSocket.receive_timeout
- The amount of time in milliseconds that the socket waits before it terminates a
receive
operation. This is equal to theSO_RCVTIMEO
.
class TLSSocket methods
- TLSSocket([socket: Socket [, context: SSLContext [, ssl: SSL]]])
- constructor
- connect(host: string, port: int [, timeout: int])
- Initiates a connection to the given host on the specified port. If host is
nil
, it will connect on to the current hostn specified on the socket.default timeout = 300,000ms (i.e. 300 seconds)return bool - bind(port: int [, host: string])
- Binds this socket to the given port on the given host. If host is
nil
or not specified, it will connect on to the current hostn specified on the socket.return bool - send(message: string | file | bytes, flags: int)
- Sends the specified message to the socket. When this methods accepts a file as a message, the file is read and the resultant bytes of the file content is streamed to the socket.
- the flags parameter is currently redundant and is kept only to remanin compatible with future plans for this method.
return number greater than -1 if successful indicating the total number of bytes sent or -1 if it fails. - receive([length: int [, flags: int]])
- Receives bytes of the given length from the socket. If the length is not given, it default length of -1 indicating that the total available data on the socket stream will be read. If no data is available for read on the socket, the socket will wait to receive data or until the
receive_timeout
which is also equal to theSO_RCVTIMEO
setting of the socket has elapsed before or until it has received the total number of bytes required (whichever comes first).- the flags parameter is currently redundant and is kept only to remanin compatible with future plans for this method.
return string - read([length: int])
- Reads bytes of the given length from the socket. If the length is not given, it default length of -1 indicating that the total available data on the socket stream will be read.
This method differs from
receive()
in that it does not check for a socket having data to read or not and will block until data of length have been read or no more data is available for reading.- Only use this function after a call to
receive()
has succeeded.
default Length = 1024return string - Only use this function after a call to
- listen([queue_length: int])
- Listen for connections on a socket
This method puts the socket in a state where it is willing to accept incoming connections and creates a queue limit of
queue_length
for incoming connections. If a connection request arrives with the queue full, the client may receive an error with an indication ofECONNREFUSED
. Alternatively, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed.When the
queue_length
is ommited or set to -1, the method will use the default queue limit of the current platform which is usually equal toSOMAXCONN
.- listen() call applies only to sockets of type
SOCK_STREAM
(which is the default)
return bool - listen() call applies only to sockets of type
- accept()
- Accepts a connection on a socket
This method extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of the current socket, and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below.
The accepted socket may not be used to accept more connections. The original socket remains open.
return TLSSocket - close()
- Closes the socket return bool
- shutdown()
- The shutdown() call causes all or part of a full-duplex connection on the socket associated with socket to be shut down. return bool
- set_option(option: int, value: any)
- Sets the options of the current socket.
- Only
SO_
variables are valid option types
return bool - Only
- get_option(option: int)
- Gets the options set on the current socket return any
- set_blocking(mode: bool)
- Sets if the socket should operate in blocking or non-blocking mode.
true
for blocking (default) andfalse
for non-blocking. - info()
- Returns a dictionary containing the address, port and family of the current socket or an empty dictionary if the socket information could not be retrieved. return dictionary
- get_socket()
- returns the underlying Socket instance return Socket
- get_context()
- returns the underlying SSLContext instance return SSLContext
class TLSServer
TLS server @printable
class TLSServer properties
- TLSServer.host
- The host address to which this server will be bound default socket.IP_LOCAL (127.0.0.1)
- TLSServer.port
- The port to which this server will be bound to on the host.
- TLSServer.socket
- The working TLSSocket instance for the TLSServer.
- TLSServer.resuse_address
- A boolean value indicating whether to reuse socket addresses or not. default true
- TLSServer.read_timeout
- The timeout in milliseconds after which an attempt to read clients request data will be terminated. default 2000 (2 seconds)
- TLSServer.write_timeout
- The timeout in milliseconds after which an attempt to write response data to clients will be terminated.
If we cannot send response to a client after the stipulated time, it will be assumed such clients have disconnected and existing connections for that client will be closed and their respective sockets will be discarded.
default 2000 (2 seconds) - TLSServer.cert_file
- The SSL/TLS ceritificate file that will be used be used by a secured server for serving requests.
- do not set a value to it directly. Use
load_certs()
instead.
- do not set a value to it directly. Use
- TLSServer.private_key_file
- The SSL/TLS private key file that will be used be used by a secured server for serving requests.
- do not set a value to it directly. Use
load_certs()
instead.
- do not set a value to it directly. Use
- TLSServer.verify_certs
- This value controls whether the client certificate should be verified or not. boolean
class TLSServer methods
- TLSServer(port: int [, host: string])
- constructor
- load_certs(cert_file: string | file [, private_key_file: string | file])
- loads the given SSL/TLS certificate pairs for the given SSL/TLS context. return bool
- close()
- stops the server
- on_connect(fn: function)
- Adds a function to be called when a new client connects.
- Function fn MUST accept at one parameter which will be passed the client TLSSocket object.
- multiple
on_connect()
may be set on a single instance.
- on_disconnect(fn: function)
- Adds a function to be called when a new client disconnects.
- Function fn MUST accept at one parameter which will be passed the client information.
- multiple
on_disconnect()
may be set on a single instance.
- on_receive(fn: function)
- Adds a function to be called when the server receives a message from a client.
Function fn MUST accept TWO parameters. First parameter will accept the HttpRequest object and the second will accept the HttpResponse object.
- multiple
on_receive()
may be set on a single instance.
- multiple
- on_reply(fn: function)
- Adds a function to be called when the server sends a reply to a client.
Function fn MUST accept one parameter which will be passed the HttpResponse object.
- multiple
on_sent()
may be set on a single instance.
- multiple
- on_error(fn: function)
- Adds a function to be called when the server encounters an error with a client.
Function fn MUST accept two parameters. The first argument will be passed the
Exception
object and the second will be passed the clientTLSSocket
object.- multiple
on_error()
may be set on a single instance.
- multiple
- listen()
- Binds to the instance port and host and starts listening for incoming connection from HTTPS clients.
class BIO
SSL Binary Input/Output
class BIO methods
- BIO(method: ptr)
- constructor
- method must be a valid SSL BIO_* method
- set_ssl(ssl: SSL [, option: int])
- sets the working SSL instance for this BIO
- option must be one of the BIO constants if given.
- default option = BIO_NOCLOSE
- set_conn_hostname(name: string)
- sets the hostname for the current connected BIO socket
- set_accept_name(name: string)
- sets the address name for the current accepted BIO socket
- set_conn_address(address: string)
- sets the address for the current connected BIO socket
- set_conn_port(port: int | string)
- sets the port for the current connected BIO socket
- set_accept_port(port: int | string)
- sets the port for the current accepted BIO socket
- set_conn_family(family: int)
- sets the socket family for the current connected BIO socket
- set_accept_family(family: int)
- sets the socket family for the current accepted BIO socket
- get_conn_hostname()
- returns the hostname for the current connected BIO socket return string
- get_accept_name()
- returns the hostname for the current accepted BIO socket return string
- get_conn_address()
- returns the address for the current connected BIO socket return string
- get_conn_port()
- returns the port for the current connected BIO socket return string
- get_accept_port()
- returns the port for the current accepted BIO socket return string
- get_conn_family()
- returns the family for the current connected BIO socket return int
- get_accept_family()
- returns the family for the current accepted BIO socket return int
- get_fd()
- returns the current socket file descriptor. It returns
-1
on failure or a positive integer on success.return number - set_fd(fd: int [, opt: int])
- sets the socket file descriptor for this BIO default opt = BIO_NOCLOSE
- set_non_blocking([b: bool])
- converts the BIO into a non-blocking I/O stream if b is
true
, otherwise converts it into a blocking stream.default true - push(b: BIO)
- it appends b, which may be a single BIO or a chain of BIOs, to the current BIO stack (unless the current pinter is
nil
). It then makes a control call on BIO b and returns it. - false
- write(data: string | bytes)
- writes data to the current I/O stream. return int representing the total bytes written
- read([length: int])
- reads data off the I/O and returns it default length = 1024return string
- should_retry()
- returns
true
if this BIO needs to retry its last operation.false
otherwise. - do_connect()
- attempts to establish a connection to the host.
- do_accept()
- attempts to accept the connected socket.
- error([code: int])
- returns the last SSL error number return int
- error_string([code: int])
- returns the last SSL error as string return string
- free()
- frees this BIO and all associated resources
- get_pointer()
- returns the raw OpenSSl BIO pointer return ptr
class SSLBIO < BIO
SSLBIO is a generic BIO for SSL I/O
class SSLBIO methods
- ConnectBIO()
- constructor
class ConnectBIO < BIO
ConnectBIO is a generic BIO for new secured connections
class ConnectBIO methods
- ConnectBIO()
- constructor
class AcceptedBIO < BIO
AcceptedBIO is a generic BIO for accepting new secured connections from a TLS server
class AcceptedBIO methods
- AcceptedBIO()
- constructor
class SSLContext
SSL context representation class
class SSLContext methods
- SSLContext(method: ptr)
- constructor
- method must be a valid SSL method pointer
- set_verify(mode: int)
- sets the verification flags for ctx to be the given mode.
- The verification of certificates can be controlled by a set of logically or’ed mode flags.
- If the mode is SSL_VERIFY_NONE none of the other flags may be set.
- set_verify_locations(locations: string)
- set default locations for trusted CA certificates
- load_certs(cert_file: string | file, private_key_file: string | file)
- loads the given SSL/TLS certificate pairs for the given SSL/TLS context. return bool
- set_ciphers(ciphers: string)
- sets the list of allowed ciphers. This list must be colon (:) separated. return bool
- free()
- frees this Context and all associated resources
- get_pointer()
- returns the raw OpenSSl SSL_CTX pointer return ptr
class TLSContext < SSLContext
TLSContext is a specialized Context providing generic TLS support for both client and server mode.
class TLSContext methods
- TLSContext()
- constructor
class TLSClientContext < SSLContext
TLSClientContext is a specialized Context for supporting TLS clients.
class TLSClientContext methods
- TLSClientContext()
- constructor
class TLSServerContext < SSLContext
TLSServerContext is a specialized Context for supporting TLS servers.
class TLSServerContext methods
- TLSServerContext()
- constructor
class SSLv23Context < SSLContext
SSLv23Context is a specialized Context providing generic SSLv23 support for both client and server mode.
class SSLv23Context methods
- SSLv23Context()
- constructor
class SSLv23ClientContext < SSLContext
SSLv23ClientContext is a specialized Context for supporting SSLv23 clients.
class SSLv23ClientContext methods
- TLSClientContext()
- constructor
class SSLv23ServerContext < SSLContext
SSLv23ServerContext is a specialized Context for supporting SSLv23 servers.
class SSLv23ServerContext methods
- SSLv23ServerContext()
- constructor