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
-
#tls_config_free(config) ⇒ nil
Free the
tls_config
object. -
#tls_config_new ⇒ FFI::Pointer
Produce a new
tls_config
context.
Client configuration collapse
-
#tls_config_insecure_noverifycert(config) ⇒ nil
Insecurely disable certficate verification.
-
#tls_config_insecure_noverifyname(config) ⇒ nil
Insecurely disable server name verification.
-
#tls_config_set_ca_file(config, ca_file) ⇒ Fixnum
Use the given file as the certificate authority file.
-
#tls_config_set_ca_mem(config, cert, len) ⇒ Fixnum
Use the root certicate from memory.
-
#tls_config_set_ca_path(config, ca_path) ⇒ Fixnum
Use the directory specified to find the root certificate file.
-
#tls_config_set_verify_depth(config, verify_depth) ⇒ nil
Set the maximum depth for the certificate chain.
-
#tls_config_verify(config) ⇒ nil
Restore default verification.
Client and server configuration collapse
-
#tls_config_set_cert_file(config, cert_file) ⇒ Fixnum
Use the given file as the certficate file.
-
#tls_config_set_cert_mem(config, cert, len) ⇒ Fixnum
Use the given file as the public certificate.
-
#tls_config_set_ciphers(config, ciphers) ⇒ Fixnum
Use the given list of ciphers.
-
#tls_config_set_protocols(config, protocols) ⇒ nil
Select which protocols are to be used.
-
#tls_load_file(file, len, password) ⇒ FFI::Pointer
Load a certificate or key.
Server configuration collapse
-
#tls_config_clear_keys(config) ⇒ nil
Clear secret keys from memory.
-
#tls_config_set_dheparams(config, params) ⇒ Fixnum
Tune the dheparams.
-
#tls_config_set_ecdhecurve(config, name) ⇒ Fixnum
Use the specified EC DHE curve.
-
#tls_config_set_key_file(config, key_file) ⇒ Fixnum
Set the private key via an absolute file path.
-
#tls_config_set_key_mem(config, key, len) ⇒ Fixnum
Set the private key via a value in memory.
Create, prepare, and free a connection context collapse
-
#tls_client ⇒ FFI::Pointer
Create a client context.
-
#tls_close(ctx) ⇒ Fixnum
Close the TLS connection.
-
#tls_configure(ctx, config) ⇒ Fixnum
Apply the configuration to the context.
-
#tls_free(ctx) ⇒ Object
Free memory for the TLS context.
-
#tls_reset(ctx) ⇒ nil
Reset a context to a newly-initialized state.
-
#tls_server ⇒ FFI::Pointer
Create a server context.
Initiate a connection and perform I/O collapse
-
#tls_accept_fds(ctx, cctx, fd_read, fd_write) ⇒ Fixnum
Perform the TLS handshake on an established pair of file descriptors.
-
#tls_accept_socket(ctx, cctx, socket) ⇒ Fixnum
Perform the TLS handshake on an established socket.
-
#tls_connect(ctx, host, port) ⇒ Fixnum
Open a TLS connection to the
host
andport
. -
#tls_connect_fds(ctx, fd_read, fd_write, servername) ⇒ Fixnum
Upgrade an existing connection to secure.
-
#tls_connect_servername(ctx, host, port, servername) ⇒ Fixnum
Open a TLS connection to the
host
andport
, verifying againstservername
. -
#tls_connect_socket(ctx, s, servername) ⇒ Fixnum
Upgrade an existing socket.
-
#tls_read(ctx, buf, buflen, outlen) ⇒ Fixnum
Read from the socket.
-
#tls_write(ctx, buf, buflen, outlen) ⇒ Fixnum
Write data to the socket.
Instance Method Summary collapse
-
#tls_config_parse_protocols(protocols, protostr) ⇒ Fixnum
Parse a protocol string into a bitmask.
-
#tls_error(ctx) ⇒ String
Produce the error message on the context.
-
#tls_init ⇒ Fixnum
Initialize the libtls library.
Instance Method Details
#tls_accept_fds(ctx, cctx, fd_read, fd_write) ⇒ Fixnum
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.
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
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.
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.
522 |
# File 'lib/libtls/raw.rb', line 522 attach_function :tls_close, [:pointer], :int |
#tls_config_clear_keys(config) ⇒ nil
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.
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
.
115 |
# File 'lib/libtls/raw.rb', line 115 attach_function :tls_config_free, [:pointer], :void |
#tls_config_insecure_noverifycert(config) ⇒ nil
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.
386 |
# File 'lib/libtls/raw.rb', line 386 attach_function :tls_config_insecure_noverifycert, [:pointer], :void |
#tls_config_insecure_noverifyname(config) ⇒ nil
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.
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.
101 |
# File 'lib/libtls/raw.rb', line 101 attach_function :tls_config_new, [], :pointer |
#tls_config_parse_protocols(protocols, protostr) ⇒ Fixnum
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.
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.
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
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.
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
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.
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.
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
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.
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.
243 |
# File 'lib/libtls/raw.rb', line 243 attach_function :tls_config_set_ciphers, [:pointer, :string], :int |
#tls_config_set_dheparams(config, params) ⇒ Fixnum
260 |
# File 'lib/libtls/raw.rb', line 260 attach_function :tls_config_set_dheparams, [:pointer, :string], :int |
#tls_config_set_ecdhecurve(config, name) ⇒ Fixnum
This is untested. Please contribute a patch.
Use the specified EC DHE curve
This applies to servers.
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.
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
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.
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.
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
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.
351 |
# File 'lib/libtls/raw.rb', line 351 attach_function :tls_config_set_verify_depth, [:pointer, :int], :void |
#tls_config_verify(config) ⇒ nil
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.
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.
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.
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
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.
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
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.
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
This is untested. Please contribute a patch.
Upgrade an existing socket
tls_connect_socket
connects a client context to an already established socket connection.
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.
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.
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.
74 |
# File 'lib/libtls/raw.rb', line 74 attach_function :tls_init, [], :int |
#tls_load_file(file, len, password) ⇒ FFI::Pointer
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.
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
723 |
# File 'lib/libtls/raw.rb', line 723 attach_function :tls_read, [:pointer, :pointer, :size_t, :pointer], :int |
#tls_reset(ctx) ⇒ nil
This is untested. Please contribute a patch.
Reset a context to a newly-initialized state
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.
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
756 |
# File 'lib/libtls/raw.rb', line 756 attach_function :tls_write, [:pointer, :pointer, :size_t, :pointer], :int |