Next | Previous

ssl

Provides OpenSSL bindings for Blade.

Fields

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.socket(socket, context, ssl) ➝ Exported

Returns a new instance of a TLSSocket.

Classes

class SSL

SSL interface class

.SSL(context) ➝ Constructor

ssl.SSL 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.

  • @returns: number
.set_fd(fd)

Sets the socket file descriptor for this SSL.

  • @params:
    • int fd
  • @returns: bool
.accept()

Begins accepting data on SSL and returns true if successful or false otherwise.

  • @returns: bool
.connect()

Connects to an SSL server instance.

@throws

  • @returns: bool
.write(data)

Writes data to the current I/O stream and return an integer representing the total bytes written.

  • @params:
    • string|bytes data
  • @returns: int
.read(length, is_blocking)

Reads data off the I/O and returns it. Set length to -1 to read till no data is available in the stream.

  • @params:

    • int? length Default value is -1

    • bool? is_blocking Default value is false

  • @returns: string
.error(code)

Returns the last SSL error number

  • @params:
    • int? code
  • @returns: int
.shutdown()

Shutdown the SSL object.

.set_tlsext_host_name(name)

Sets the Server Name Indication (SNI) for use by Secure Sockets Layer (SSL). This function should be called on a client SSL session before the TLS handshake for the SNI extension to be set properly.

  • @params:
    • string name
  • @returns: bool
.get_peer_certificate()

Returns informations about the peer certificate in a dictionary.

The returned information includes:

  • subject_name

  • issuer_name

  • serial_number

  • not_before

  • not_after

  • public_key

  • extensions

  • algorithm

  • @returns: dict

.free()

Frees this SSL and all associated resources.

.get_pointer()

Returns the raw OpenSSl SSL pointer.

  • @returns: ptr
class TLSSocket

TLS enabled Socket version powered by OpenSSL.

@printable

.host ➝ string

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.

.port ➝ number

The port currently bound or connected to by the socket.

.family ➝ number

The socket family (which must be one of the AF_ variables). The default family for the socket is AF_INET.

.type ➝ number

The type of socket stream used by the socket. The default socket type is SOCK_STREAM.

.protocol ➝ number

The current operating protocol of the socket that controls the underlying behavior of the socket. The default is IPPROTO_TCP.

.id ➝ number

The file descriptor id of the current socket on the host machine.

.is_client ➝ bool

true when the socket is a client to a server socket, false otherwise.

.is_bound ➝ bool

true when the socket is bound to a given port on the device, false otherwise.

.is_connected ➝ bool

true when the socket is connected to a server socket, false otherwise.

.is_listening ➝ bool

true when the socket is currently listening on a host device port as a server, false otherwise.

.is_closed ➝ bool

true when the socket is closed, false otherwise.

.is_shutdown ➝ bool

true when the socket is shutdown, false otherwise.

.is_blocking ➝ bool

true when the socket is running in a blocking mode, false otherwise.

.shutdown_reason ➝ number

The property holds the reason for which the last shutdown operation was called or -1 if shutdown was never requested.

.send_timeout ➝ number

The amount of time in milliseconds that the socket waits before it terminates a send operation. This is equal to the SO_SNDTIMEO.

.receive_timeout ➝ number

The amount of time in milliseconds that the socket waits before it terminates a receive operation. This is equal to the SO_RCVTIMEO.

.TLSSocket(socket, context, ssl) ➝ Constructor

ssl.TLSSocket constructor

.connect(host, port, timeout)

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.

  • @params:
    • string host
    • int port
    • int? timeout Default is 300,000ms (i.e. 300 seconds)
  • @returns: bool
.bind(port, host)

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.

  • @params:
    • int port
    • string? host
  • @returns: bool
.send(message, flags)

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.

@notes:

  • the flags parameter is currently redundant and is kept only to remain compatible with future plans for this method.
  • @params:
    • string|bytes|file message
    • int? flags
  • @returns: number greater than -1 if successful indicating the total number of bytes sent or -1 if it fails.
.receive(length, flags)

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 the SO_RCVTIMEO setting of the socket has elapsed before or until it has received the total number of bytes required (whichever comes first).

@notes:

  • the flags parameter is currently redundant and is kept only to remain compatible with future plans for this method.
  • @params:
    • int? length
    • int? flags
  • @returns: string
.read(length)

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.

@notes:

  • Only use this function after a call to receive() has succeeded.
  • @params:
    • int? length Default value is 1024.
  • @returns: string
.listen(queue_length)

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 of ECONNREFUSED. Alternatively, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed.

When the queue_length is omitted or set to -1, the method will use the default queue limit of the current platform which is usually equal to SOMAXCONN.

@notes:

  • listen() call applies only to sockets of type SOCK_STREAM (which is the default).
  • @params:
    • int? queue_length Default value is SOMAXCONN.
  • @returns: bool
.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.

.close()

Closes the socket.

  • @returns: bool
.shutdown()

The shutdown() call causes all or part of a full-duplex connection on the socket associated with socket to be shut down.

  • @returns: bool
.set_option(option, value)

Sets the options of the current socket.

@notes:

  • Only SO_ variables are valid option types.
  • @params:
    • int option
    • any value
  • @returns: bool
.get_option(option)

Gets the options set on the current socket.

  • @params:
    • int option
  • @returns: any
.set_blocking(mode)

Sets if the socket should operate in blocking or non-blocking mode. true for blocking (default) and false for non-blocking.

  • @params:
    • bool mode
  • @returns: bool
.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.

  • @returns: dictionary
.get_socket()

Returns the underlying Socket instance.

.get_context()

Returns the underlying SSLContext instance.

.get_ssl()

Returns the underlying SSL instance

  • @returns: SSL
.set_context(context)

Sets the underlying SSL context to use.

class BIO

SSL Binary Input/Output implementation

.BIO(method) ➝ Constructor

@param ptr method

@notes:

  • Method must be a valid SSL BIO_ method
.set_ssl(ssl, option)

Sets the working SSL instance for this BIO.

@notes:

  • Option must be one of the BIO constants if given.
  • @params:
    • SSL ssl
    • int? option Default value is BIO_NOCLOSE
.set_conn_hostname(name)

Sets the hostname for the current connected BIO socket.

  • @params:
    • string name
.set_accept_tname(name)

Sets the address name for the current accepted BIO socket.

  • @params:
    • string name
.set_conn_address(address)

Sets the address for the current connected BIO socket.

  • @params:
    • string address
.set_conn_port(port)

Sets the port for the current connected BIO socket.

  • @params:
    • int|string port
.set_accept_port(port)

Sets the port for the current accepted BIO socket.

  • @params:
    • int|string port
.set_conn_family(family)

Sets the socket family for the current connected BIO socket.

  • @params:
    • int family
.set_accept_family(family)

Sets the socket family for the current accepted BIO socket.

  • @params:
    • int family
.get_conn_hostname()

Returns the hostname for the current connected BIO socket.

  • @returns: string
.get_accept_name()

Returns the hostname for the current accepted BIO socket.

  • @returns: string
.get_conn_address()

Returns the address for the current connected BIO socket.

  • @returns: string
.get_conn_port()

Returns the port for the current connected BIO socket.

  • @returns: string
.get_accept_port()

Returns the port for the current accepted BIO socket.

  • @returns: string
.get_conn_family()

Returns the family for the current connected BIO socket.

  • @returns: int
.get_accept_family()

Returns the family for the current accepted BIO socket.

  • @returns: int
.get_fd()

Returns the current socket file descriptor. It returns -1 on failure or a positive integer on success.

  • @returns: number
.set_fd(fd, opt)

Sets the socket file descriptor for this BIO

  • @params:
    • int fd
    • int? opt Default value is BIO_NOCLOSE
.set_non_blocking(is_blocking)

Converts the BIO into a non-blocking I/O stream if b is true, otherwise converts it into a blocking stream.

  • @params:
    • bool? is_blocking Default value is true.
.push(bio)

It appends bio, 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 bio and returns it.

  • @params:
  • @returns: self
.pop()

Removes this BIO from any chain is is part of

.write(data)

Writes data to the current I/O stream and returns the total bytes written.

  • @params:
    • string|bytes data
  • @returns: int
.read(length)

Reads data off the I/O and returns it.

  • @params:
    • int? length Default value is 1024
  • @returns: string
.should_retry()

Returns true if this BIO needs to retry its last operation. false otherwise.

  • @returns: bool
.do_connect()

Attempts to establish a connection to the host.

  • @returns: int
.do_accept()

Attempts to accept the connected socket.

  • @returns: int
.error(code)

Returns the last SSL error number.

  • @params:
    • int? code
  • @returns: int
.error_string()

Returns the last SSL error as string.

  • @returns: string
.free()

Frees this BIO and all associated resources.

.get_pointer()

Returns the raw OpenSSl BIO pointer.

  • @returns: ptr
class SSLBIO < BIO

SSLBIO is a generic BIO for SSL I/O

.SSLBIO() ➝ Constructor
ssl.SSLBIO constructor
class ConnectBIO < BIO

ConnectBIO is a generic BIO for new secured connections

.ConnectBIO() ➝ Constructor
ssl.ConnectBIO constructor
class AcceptedBIO < BIO

AcceptedBIO is a generic BIO for accepting new secured connections from a TLS server

.AcceptedBIO() ➝ Constructor
ssl.AcceptedBIO constructor
class SSLContext

SSL context representation class

.SSLContext(method) ➝ Constructor

ssl.SSLContext constructor

@notes:

  • Method must be a valid SSL method pointer.
  • @params:
    • ptr method
.set_verify(mode, disable)

Enables or disables the verification flags for the given mode on the context.

@notes:

  • 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.
  • @params:
    • int mode
    • bool? disable Default: false
.set_verify_locations(locations)

Sets the default locations for trusted CA certificates.

  • @params:
    • string locations
.load_certs(cert_file, private_key_file)

Loads the given SSL/TLS certificate pairs for the given SSL/TLS context.

  • @params:
    • string|file cert_file
    • string|file private_key_file
  • @returns: bool
.set_ciphers(ciphers)

Sets the list of allowed ciphers. This list must be colon (😃 separated.

  • @params:
    • string ciphers
  • @returns: bool
.free()

Frees this Context and all associated resources

.get_pointer()

Returns the raw OpenSSl SSL_CTX pointer.

  • @returns: ptr
class TLSContext < SSLContext

TLSContext is a specialized Context providing generic TLS support for both client and server mode.

.TLSContext() ➝ Constructor
ssl.TLSContext constructor
class TLSClientContext < SSLContext

TLSClientContext is a specialized Context for supporting TLS clients.

.TLSClientContext() ➝ Constructor
ssl.TLSClientContext constructor
class TLSServerContext < SSLContext

TLSServerContext is a specialized Context for supporting TLS servers.

.TLSServerContext() ➝ Constructor
ssl.TLSServerContext constructor
class SSLv23Context < SSLContext

SSLv23Context is a specialized Context providing generic SSLv23 support for both client and server mode.

.SSLv23Context() ➝ Constructor
ssl.SSLv23Context constructor
class SSLv23ClientContext < SSLContext

SSLv23ClientContext is a specialized Context for supporting SSLv23 clients.

.SSLv23ClientContext() ➝ Constructor
ssl.SSLv23ClientContext constructor
class SSLv23ServerContext < SSLContext

SSLv23ServerContext is a specialized Context for supporting SSLv23 servers.

.SSLv23ServerContext() ➝ Constructor
ssl.SSLv23ServerContext constructor