Module: LibTLS::Raw

Extended by:
FFI::Library
Defined in:
lib/libtls/raw.rb

Overview

ISC license.

Constant Summary collapse

TLS_API =

The version of the libtls API.

20141031
TLS_PROTOCOL_TLSv1_0 =

Select the TLS 1.0 protocol

(1 << 1)
TLS_PROTOCOL_TLSv1_1 =

Select the TLS 1.1 protocol

(1 << 2)
TLS_PROTOCOL_TLSv1_2 =

Select the TLS 1.2 protocol

(1 << 3)
TLS_PROTOCOL_TLSv1 =

Select any TLS 1.x protocol

TLS_PROTOCOL_TLSv1_0 | TLS_PROTOCOL_TLSv1_1 | TLS_PROTOCOL_TLSv1_2
TLS_PROTOCOLS_ALL =

Select any TLS protocol of any version

TLS_PROTOCOL_TLSv1
TLS_PROTOCOLS_DEFAULT =

Select the default, suggested TLS protocol

Do not use any protocol except this one unless you understand why you are doing so.

TLS_PROTOCOL_TLSv1_2
TLS_READ_AGAIN =

A read operation is necessary to continue

-2
##
# A write operation is necessary to continue
TLS_WRITE_AGAIN =

A write operation is necessary to continue

-3

Create and free configuration objects collapse

Client configuration collapse

Client and server configuration collapse

Server configuration collapse

Create, prepare, and free a connection context collapse

Initiate a connection and perform I/O collapse

Instance Method Summary collapse

Instance Method Details

#tls_accept_fds(ctx, cctx, fd_read, fd_write) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Perform the TLS handshake on an established pair of file descriptors

tls_accept_fds creates a new context suitable for reading and writing on an existing pair of file descriptors and returns it in *cctx. A configured server context should be passed in ctx and *cctx should be initialized to NULL.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • cctx (FFI::Pointer) —

    a reference to a TLS context

  • fd_read (Fixnum) —

    the read file descriptor

  • fd_write (Fixnum) —

    the write file descriptor

Returns:

See Also:



653
 
# File 'lib/libtls/raw.rb', line 653

attach_function :tls_accept_fds, [:pointer, :pointer, :int, :int], :int

#tls_accept_socket(ctx, cctx, socket) ⇒ Fixnum

Perform the TLS handshake on an established socket

A server can accept a new client connection by calling tls_accept_socket on an already established socket connection.

tls_accept_socket creates a new context suitable for reading and writing on an already established socket connection and returns it in *cctx. A configured server context should be passed in ctx and *cctx should be initialized to NULL.

The pattern looks like this:

cctx_ptr = FFI::MemoryPointer.new(:pointer)
LibTLS::Raw.tls_accept_socket(ctx, cctx_ptr, client_sock.fileno)
cctx = cctx_ptr.read_pointer

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • cctx (FFI::Pointer) —

    a reference to a TLS context

  • socket (Int) —

    the file descriptor of an established socket that is connected to a client. Use Socket#fileno to get the file descriptor of a Socket instance.

Returns:



683
 
# File 'lib/libtls/raw.rb', line 683

attach_function :tls_accept_socket, [:pointer, :pointer, :int], :int

#tls_client ⇒ FFI::Pointer

Create a client context

A tls connection is represented as a context. A new context is created by either the #tls_client or #tls_server functions. The context can then be configured with the function #tls_configure. The same tls_config object can be used to configure multiple contexts.

tls_client creates a new tls context for client connections.

Returns:

  • (FFI::Pointer) —

    a tls context or FFI::Pointer::NULL on failure. Check using #null?.



460
 
# File 'lib/libtls/raw.rb', line 460

attach_function :tls_client, [], :pointer

#tls_close(ctx) ⇒ Fixnum

Close the TLS connection

After use, a tls context should be closed with tls_close, and then freed by calling #tls_free. When no more contexts are to be created, the tls_config object should be freed by calling #tls_config_free.

tls_close closes a connection after use. If the connection was established using #tls_connect_fds, only the TLS layer will be closed and it is the caller’s responsibility to close the file descriptors.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

Returns:



522
 
# File 'lib/libtls/raw.rb', line 522

attach_function :tls_close, [:pointer], :int

#tls_config_clear_keys(config) ⇒ nil

TODO:

This is untested. Please contribute a patch.

Clear secret keys from memory

tls_config_clear_keys clears any secret keys from memory.

This applies to servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (nil) —

    void



368
 
# File 'lib/libtls/raw.rb', line 368

attach_function :tls_config_clear_keys, [:pointer], :void

#tls_config_free(config) ⇒ nil

Free the tls_config object

When no more contexts are to be created, the tls_config object should be freed by calling tls_config_free.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (nil) —

    void



115
 
# File 'lib/libtls/raw.rb', line 115

attach_function :tls_config_free, [:pointer], :void

#tls_config_insecure_noverifycert(config) ⇒ nil

Note:

This method should not be used, and is therefore untested.

Insecurely disable certficate verification

tls_config_insecure_noverifycert disables certificate verification. Be extremely careful when using this option.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (nil) —

    void



386
 
# File 'lib/libtls/raw.rb', line 386

attach_function :tls_config_insecure_noverifycert, [:pointer], :void

#tls_config_insecure_noverifyname(config) ⇒ nil

Note:

This method should not be used, and is therefore untested.

Insecurely disable server name verification

tls_config_insecure_noverifyname disables server name verification. Be careful when using this option.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (nil) —

    void



402
 
# File 'lib/libtls/raw.rb', line 402

attach_function :tls_config_insecure_noverifyname, [:pointer], :void

#tls_config_new ⇒ FFI::Pointer

Produce a new tls_config context

Before a connection is created, a configuration must be created. The tls_config_new function returns a new default configuration that can be used for future connections. Several functions exist to change the options of the configuration; see below.

Returns:

  • (FFI::Pointer) —

    a tls_config context or FFI::Pointer::NULL on failure. Check using #null?.



101
 
# File 'lib/libtls/raw.rb', line 101

attach_function :tls_config_new, [], :pointer

#tls_config_parse_protocols(protocols, protostr) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Parse a protocol string into a bitmask

The tls_config_parse_protocols function parses a protocol string and returns the corresponding value via the protocols argument. This value can then be passed to the #tls_config_set_protocols function. The protocol string is a comma or colon separated list of keywords. Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols), default (an alias for secure), legacy (an alias for all) and secure (currently TLSv1.2 only). If a value has a negative prefix (in the form of a leading exclamation mark) then it is removed from the list of available protocols, rather than being added to it.

Parameters:

  • protocols (FFI::Pointer) —

    a uint32_t pointer to store the parse result

  • protostr (String) —

    the protocol string

Returns:

  • (Fixnum) —

    0 on success, -1 on error



139
 
# File 'lib/libtls/raw.rb', line 139

attach_function :tls_config_parse_protocols, [:uint32_t, :string], :int

#tls_config_set_ca_file(config, ca_file) ⇒ Fixnum

Use the given file as the certificate authority file

tls_config_set_ca_file sets the filename used to load a file containing the root certificates.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • ca_file (String) —

    absolute path to the file containing the root certificates

Returns:

  • (Fixnum) —

    0 on success, -1 on error



156
 
# File 'lib/libtls/raw.rb', line 156

attach_function :tls_config_set_ca_file, [:pointer, :string], :int

#tls_config_set_ca_mem(config, cert, len) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Use the root certicate from memory

tls_config_set_ca_mem sets the root certificates directly from memory.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • cert (FFI::Pointer) —

    uint8_t pointer to the cert

  • len (Fixnum) —

    number of bytes in the cert

Returns:

  • (Fixnum) —

    0 on success, -1 on error



191
 
# File 'lib/libtls/raw.rb', line 191

attach_function :tls_config_set_ca_mem, [:pointer, :pointer, :size_t], :int

#tls_config_set_ca_path(config, ca_path) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Use the directory specified to find the root certificate file

tls_config_set_ca_path sets the path (directory) which should be searched for root certificates.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • ca_path (String) —

    absolute path to the directory containing the root certificates

Returns:

  • (Fixnum) —

    0 on success, -1 on error



174
 
# File 'lib/libtls/raw.rb', line 174

attach_function :tls_config_set_ca_path, [:pointer, :string], :int

#tls_config_set_cert_file(config, cert_file) ⇒ Fixnum

Use the given file as the certficate file

tls_config_set_ca_file sets sets file from which the public certificate will be read.

This applies to clients and servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • cert_file (String) —

    absolute path to the file containing the public certificate

Returns:

  • (Fixnum) —

    0 on success, -1 on error



209
 
# File 'lib/libtls/raw.rb', line 209

attach_function :tls_config_set_cert_file, [:pointer, :string], :int

#tls_config_set_cert_mem(config, cert, len) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Use the given file as the public certificate

tls_config_set_cert_mem sets the public certificate directly from memory.

This applies to clients and servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • cert (FFI::Pointer) —

    uint8_t pointer to the cert

  • len (Fixnum) —

    number of bytes in the cert

Returns:

  • (Fixnum) —

    0 on success, -1 on error



227
 
# File 'lib/libtls/raw.rb', line 227

attach_function :tls_config_set_cert_mem, [:pointer, :pointer, :size_t], :int

#tls_config_set_ciphers(config, ciphers) ⇒ Fixnum

Use the given list of ciphers

tls_config_set_ciphers sets the list of ciphers that may be used.

This applies to clients and servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • ciphers (String) —

    a list of ciphers to use

Returns:

  • (Fixnum) —

    0 on success, -1 on error



243
 
# File 'lib/libtls/raw.rb', line 243

attach_function :tls_config_set_ciphers, [:pointer, :string], :int

#tls_config_set_dheparams(config, params) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Tune the dheparams

This applies to servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • params (String) —

    one of “none” (0), “auto” (-1), or “legacy” (1024). The default is “none”.

Returns:

  • (Fixnum) —

    0 on success, -1 on error



260
 
# File 'lib/libtls/raw.rb', line 260

attach_function :tls_config_set_dheparams, [:pointer, :string], :int

#tls_config_set_ecdhecurve(config, name) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Use the specified EC DHE curve

This applies to servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • name —

    one of “none” (NID_undef), “auto” (-1), or any NID value understood by OBJ_txt2nid (3).

Returns:

  • (Fixnum) —

    0 on success, -1 on error



275
 
# File 'lib/libtls/raw.rb', line 275

attach_function :tls_config_set_ecdhecurve, [:pointer, :string], :int

#tls_config_set_key_file(config, key_file) ⇒ Fixnum

Set the private key via an absolute file path

tls_config_set_key_file sets the file from which the private key will be read.

This applies to servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • key_file (String) —

    absolute path to a private key in a file

Returns:

  • (Fixnum) —

    0 on success, -1 on error



290
 
# File 'lib/libtls/raw.rb', line 290

attach_function :tls_config_set_key_file, [:pointer, :string], :int

#tls_config_set_key_mem(config, key, len) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Set the private key via a value in memory

tls_config_set_key_mem directly sets the private key from memory.

This applies to servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • key (FFI::Pointer) —

    a uint8_t pointer to the key

  • len (Fixnum) —

    number of bytes in the key

Returns:

  • (Fixnum) —

    0 on success, -1 on error



307
 
# File 'lib/libtls/raw.rb', line 307

attach_function :tls_config_set_key_mem, [:pointer, :pointer, :size_t], :int

#tls_config_set_protocols(config, protocols) ⇒ nil

Select which protocols are to be used

tls_config_set_protocols sets which versions of the protocol may be used. Possible values are the bitwise OR of:

Additionally, the values TLS_PROTOCOL_TLSv1 (TLSv1.0, TLSv1.1 and TLSv1.2), TLS_PROTOCOLS_ALL (all supported protocols) and TLS_PROTOCOLS_DEFAULT (TLSv1.2 only) may be used.

This applies to clients and servers.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • protocols (Fixnum) —

    bitmask of the protocols to select

Returns:

  • (nil) —

    void



332
 
# File 'lib/libtls/raw.rb', line 332

attach_function :tls_config_set_protocols, [:pointer, :uint], :void

#tls_config_set_verify_depth(config, verify_depth) ⇒ nil

TODO:

This is untested. Please contribute a patch.

Set the maximum depth for the certificate chain

See SSL_CTX_set_verify_depth(3) for details.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

  • verify_depth (Fixnum) —

    the maximum depth for certificate chain verification

Returns:

  • (nil) —

    void



351
 
# File 'lib/libtls/raw.rb', line 351

attach_function :tls_config_set_verify_depth, [:pointer, :int], :void

#tls_config_verify(config) ⇒ nil

Note:

While this method is fine, getting to this state is not. This method is therefore untested.

Restore default verification

tls_config_verify reenables server name and certificate verification.

This applies to clients.

Parameters:

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (nil) —

    void



418
 
# File 'lib/libtls/raw.rb', line 418

attach_function :tls_config_verify, [:pointer], :void

#tls_configure(ctx, config) ⇒ Fixnum

Apply the configuration to the context

tls_configure readies a tls context for use by applying the configuration options.

The same tls_config object can be used to configure multiple contexts.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • config (FFI::Pointer) —

    the TLS config

Returns:

  • (Fixnum) —

    0 on success, -1 on error



491
 
# File 'lib/libtls/raw.rb', line 491

attach_function :tls_configure, [:pointer, :pointer], :int

#tls_connect(ctx, host, port) ⇒ Fixnum

Open a TLS connection to the host and port

A client connection is initiated after configuration by calling tls_connect. This function will create a new socket, connect to the specified host and port, and then establish a secure connection.

tls_connect connects a client context to the server named by host. The port may be numeric or a service name. If it is FFI::Pointer::NULL then a host of the format “hostname:port” is permitted.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • host (String) —

    the server to connect to, as an IPv4 address, an IPv6 address, anything that can be resolved by getaddrinfo.

  • port (String) —

    the port as a number, service name, or NULL pointer. If it is a NULL pointer, the host is parsed for the port number.

Returns:



562
 
# File 'lib/libtls/raw.rb', line 562

attach_function :tls_connect, [:pointer, :string, :string], :int

#tls_connect_fds(ctx, fd_read, fd_write, servername) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Upgrade an existing connection to secure

tls_connect_fds connects a client context to a pair of existing file descriptors.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • fd_read (Fixnum) —

    the read file descriptor

  • fd_write (Fixnum) —

    the write file descriptor

  • servername (String) —

    the name of the server, as matched in the certificate

Returns:



583
 
# File 'lib/libtls/raw.rb', line 583

attach_function :tls_connect_fds, [:pointer, :int, :int, :string], :int

#tls_connect_servername(ctx, host, port, servername) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Open a TLS connection to the host and port, verifying against servername

The tls_connect_servername function has the same behaviour as #tls_connect, however the name to use for verification is explicitly provided, rather than being inferred from the host value.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • host (String) —

    the server to connect to, as an IPv4 address, an IPv6 address, anything that can be resolved by getaddrinfo.

  • port (String) —

    the port as a number, service name, or NULL pointer. If it is a NULL pointer, the host is parsed for the port number.

  • servername (String) —

    the server name to verify the certificate against

Returns:



608
609
 
# File 'lib/libtls/raw.rb', line 608

attach_function :tls_connect_servername,
[:pointer, :string, :string, :string], :int

#tls_connect_socket(ctx, s, servername) ⇒ Fixnum

TODO:

This is untested. Please contribute a patch.

Upgrade an existing socket

tls_connect_socket connects a client context to an already established socket connection.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • s (Fixnum) —

    the file descriptor for a socket

  • servername (String) —

    the server name to verify the certificate against

Returns:



629
 
# File 'lib/libtls/raw.rb', line 629

attach_function :tls_connect_socket, [:pointer, :int, :string], :int

#tls_error(ctx) ⇒ String

Produce the error message on the context

The tls_error function may be used to retrieve a string containing more information about the most recent error.

Parameters:

  • ctx (FFI::Pointer) —

    the TLS context

Returns:

  • (String) —

    the error message for the most recent error



86
 
# File 'lib/libtls/raw.rb', line 86

attach_function :tls_error, [:pointer], :string

#tls_free(ctx) ⇒ Object

Free memory for the TLS context

After use, a tls context should be closed with tls_close, and then freed by calling #tls_free. When no more contexts are to be created, the tls_config object should be freed by calling #tls_config_free.

tls_free frees a tls context after use.

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context



536
 
# File 'lib/libtls/raw.rb', line 536

attach_function :tls_free, [:pointer], :void

#tls_init ⇒ Fixnum

Initialize the libtls library

The tls_init function should be called once before any function is used. It may be called more than once, but not concurrently.

Returns:

  • (Fixnum) —

    0 on success, -1 on error



74
 
# File 'lib/libtls/raw.rb', line 74

attach_function :tls_init, [], :int

#tls_load_file(file, len, password) ⇒ FFI::Pointer

TODO:

This is untested. Please contribute a patch.

Load a certificate or key

tls_load_file loads a certificate or key from disk into memory to be loaded with #tls_config_set_ca_mem, #tls_config_set_cert_mem or #tls_config_set_key_mem. A private key will be decrypted if the optional password argument is specified.

This applies to clients and servers.

Parameters:

  • file (String) —

    the absolute filename

  • len (FFI::Pointer) —

    pointer to a size_t storing the number of bytes loaded

  • password (String) —

    either FFI::Pointer::NULL or the password for the private key

Returns:

  • (FFI::Pointer) —

    pointer to uint8_t, the key



442
 
# File 'lib/libtls/raw.rb', line 442

attach_function :tls_load_file, [:string, :pointer, :string], :pointer

#tls_read(ctx, buf, buflen, outlen) ⇒ Fixnum

Read from the socket

tls_read reads buflen bytes of data from the socket into buf. The amount of data read is returned in outlen.

The pattern is as follows:

READ_LEN = 1024
FFI::MemoryPointer.new(:size_t) do |outlen|
  FFI::MemoryPointer.new(:uchar, READ_LEN, true) do |buf|
    loop do
      if LibTLS::Raw.tls_read(ctx, buf, READ_LEN, outlen) < 0
        raise LibTLS::CError, "tls_read: #{LibTLS::Raw.tls_error(ctx)}"
      end

      do_something_with( buf.get_string(0, outlen.get_int(0)) )

      if READ_LEN > outlen.get_int(0)
        break
      end
    end
  end
end

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • buf (FFI::Pointer) —

    allocated memory for a buflen number of uchars

  • buflen (Fixnum) —

    the number of bytes to read

  • outlen (FFI::Pointer) —

    the number of bytes read

Returns:



723
 
# File 'lib/libtls/raw.rb', line 723

attach_function :tls_read, [:pointer, :pointer, :size_t, :pointer], :int

#tls_reset(ctx) ⇒ nil

TODO:

This is untested. Please contribute a patch.

Reset a context to a newly-initialized state

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

Returns:

  • (nil) —

    void



502
 
# File 'lib/libtls/raw.rb', line 502

attach_function :tls_reset, [:pointer], :void

#tls_server ⇒ FFI::Pointer

Create a server context

A tls connection is represented as a context. A new context is created by either the #tls_client or #tls_server functions. The context can then be configured with the function #tls_configure. The same tls_config object can be used to configure multiple contexts.

tls_server creates a new tls context for server connections.

Returns:

  • (FFI::Pointer) —

    a tls context or FFI::Pointer::NULL on failure. Check using #null?.



476
 
# File 'lib/libtls/raw.rb', line 476

attach_function :tls_server, [], :pointer

#tls_write(ctx, buf, buflen, outlen) ⇒ Fixnum

Write data to the socket

tls_write writes buflen bytes of data from buf to the socket. The amount of data written is returned in outlen.

The pattern is as follows:

STR = "HELLO\r\n"

FFI::MemoryPointer.new(:size_t) do |outlen|
  FFI::MemoryPointer.new(:uchar, STR.length + 1) do |str_ptr|
    str_ptr.put_string(0, STR)

    if LibTLS::Raw.tls_write(ctx, str_ptr, STR.length, outlen) < 0
      raise LibTLS::CError, "tls_write: #{LibTLS::Raw.tls_error(ctx)}"
    end
  end
end

Parameters:

  • ctx (FFI::Pointer) —

    a TLS context

  • buf (FFI::Pointer) —

    a pointer to the string of uchars

  • buflen (Fixnum) —

    the number of bytes to write

  • outlen (FFI::Pointer) —

    the number of bytes written

Returns:



756
 
# File 'lib/libtls/raw.rb', line 756

attach_function :tls_write, [:pointer, :pointer, :size_t, :pointer], :int