tls NSE Library — Nmap Scripting Engine documentation (original) (raw)

Script Arguments Functions

A library providing functions for doing TLS/SSL communications

These functions will build strings and process buffers. Socket communication is left to the script to implement.

Author:

Source: https://svn.nmap.org/nmap/nselib/tls.lua

Script Arguments

tls.servername

Hostname to use in the Server Name Indication (SNI) extension. Overrides the target name given on the command line and affects all targets.

Functions

cipher_info (c)

Get info about a cipher suite

client_hello (t)

Build a client_hello message

parse_messages (mbuffer, mi, h)

Parse a series of TLS messages from a buffer

record_buffer (sock, buffer, i)

Get an entire record into a buffer

record_read (buffer, i, fragment)

Read a SSL/TLS record

record_write (type, protocol, b)

Build a SSL/TLS record

rsa_equiv (ktype, bits)

Get the strength-equivalent RSA key size

Functions

cipher_info (c)

Get info about a cipher suite

Returned table has "kex", "cipher", "mode", "size", and "hash" keys, as well as boolean flag "draft". The "draft" flag is only supported for some suites that have different enumeration values in draft versus final RFC.

Parameters

c

The cipher suite name, e.g. TLS_RSA_WITH_AES_128_GCM_SHA256

Return value:

A table of info as described above.

client_hello (t)

Build a client_hello message

The options table has the following keys:

• "protocol" - The TLS protocol version string for the client_hello. This indicates the highest protocol version supported.
• "record_protocol" - The TLS protocol version string for the TLS record. This indicates the lowest protocol version supported.
• "ciphers" - a table containing the cipher suite names. Defaults to the NULL cipher
• "compressors" - a table containing the compressor names. Default: NULL
• "extensions" - a table containing the extension names. Default: no extensions

Parameters

t

Table of options

Return value:

The client_hello record as a string

parse_messages (mbuffer, mi, h)

Parse a series of TLS messages from a buffer

Parameters

mbuffer

The buffer to parse

mi

The index into that buffer to begin parsing

h

The TLS/DTLS header. Must contain "type" and "protocol" fields

Return values:

1. A table of parsed messages
2. The position where parsing stopped

record_buffer (sock, buffer, i)

Get an entire record into a buffer

Caller is responsible for closing the socket if necessary.

Parameters

sock

The socket to read additional data from

buffer

The string buffer holding any previously-read data (default: "")

i

The position in the buffer where the record should start (default: 1)

Return values:

1. status Socket status
2. Buffer containing at least 1 record if status is true
3. Error text if there was an error

record_read (buffer, i, fragment)

Read a SSL/TLS record

Parameters

buffer

The read buffer

i

The position in the buffer to start reading (default: 1)

fragment

Message fragment left over from previous record (nil if none)

Return values:

1. The current position in the buffer
2. The record that was read, as a table
3. Whether parsing can continue if more data becomes available.

record_write (type, protocol, b)

Build a SSL/TLS record

Parameters

type

The type of record ("handshake", "change_cipher_spec", etc.)

protocol

The protocol and version ("SSLv3", "TLSv1.0", etc.)

b

The record body

Return value:

The SSL/TLS record as a string

rsa_equiv (ktype, bits)

Get the strength-equivalent RSA key size

Based on NIST SP800-57 part 1 rev 3

Parameters

ktype

Key type ("dh", "ec", "rsa", "dsa")

bits

Size of key in bits

Return value:

Size in bits of RSA key with equivalent strength