mirror of
https://github.com/nmap/nmap.git
synced 2026-01-15 02:49:02 +00:00
Add luadoc files for openssl and pcre. That finishes the modules in the section
"Lua Extensions", which is now just a stub.
This commit is contained in:
david
@@ -763,7 +763,7 @@ action refer to <xref linkend="nse-tutorial-action"/>.
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="nse-library">
|
||||
<indexterm class="startofrange" id="nse-library-indexterm"><primary>Nmap Scripting Engine (NSE)</primary><secondary>modules</secondary></indexterm>
|
||||
<indexterm><primary>Nmap Scripting Engine (NSE)</primary><secondary>modules</secondary></indexterm>
|
||||
<title>Lua Extensions</title>
|
||||
<para>In addition to the significant built-in capabilities of
|
||||
Lua, we have written or integrated several extensions to make
|
||||
@@ -774,458 +774,7 @@ action refer to <xref linkend="nse-tutorial-action"/>.
|
||||
<ulink url="http://www.lua.org/manual/5.1/manual.html#pdf-require">
|
||||
<literal>require</literal>
|
||||
</ulink> the default modules in order to use them.
|
||||
The default modules are described in the following sections.
|
||||
</para>
|
||||
|
||||
<sect2 id="nse-pcre">
|
||||
<indexterm class="startofrange" id="nse-pcre-indexterm"><primary><varname>pcre</varname> NSE module</primary></indexterm>
|
||||
<indexterm><primary>Perl Compatible Regular Expressions (PCRE)</primary><secondary>in NSE</secondary></indexterm>
|
||||
<indexterm><primary>regular expressions</primary><secondary>in NSE</secondary></indexterm>
|
||||
<title>Perl Compatible Regular Expressions</title>
|
||||
|
||||
<para>
|
||||
One of Lua's quirks is its string patterns. While they have
|
||||
great performance and are tightly integrated into the Lua
|
||||
interpreter, they are very different in syntax and not as
|
||||
powerful as standard regular expressions. So we have
|
||||
integrated Perl compatible regular expressions into Lua
|
||||
using PCRE and a modified version of the Lua PCRE library
|
||||
written by Reuben Thomas<indexterm><primary>Thomas, Reuben</primary></indexterm>
|
||||
and Shmuel Zeigerman.<indexterm><primary>Zeigerman, Shmuel</primary></indexterm>
|
||||
These are
|
||||
the same sort of regular expressions used by Nmap version
|
||||
detection. The main modification to their library is that
|
||||
the NSE version only supports PCRE expressions instead of both
|
||||
PCRE and POSIX patterns. In order to maintain a high script
|
||||
execution speed, the library interfacing with PCRE is
|
||||
kept very thin. It is not integrated as seamlessly as the
|
||||
Lua string pattern API. This allows script authors to decide
|
||||
when to use PCRE expressions versus Lua patterns. The use of PCRE
|
||||
involves a separate pattern compilation step, which saves
|
||||
execution time when patterns are reused. Compiled patterns
|
||||
can be cached in the NSE registry and reused by other
|
||||
scripts. The PCRE functions reside inside the <literal>pcre</literal>
|
||||
namespace.
|
||||
</para>
|
||||
|
||||
<indexterm><primary>Perl Compatible Regular Expressions (PCRE)</primary><secondary>security vulnerabilities in</secondary></indexterm>
|
||||
<warning><para>PCRE has a history of security vulnerabilities
|
||||
allowing attackers who are able to compile arbitrary regular
|
||||
expressions to execute arbitrary code. More such
|
||||
vulnerabilities may be discovered in the future. These have
|
||||
never affected Nmap because it doesn't give attackers any
|
||||
control over the regular expressions it uses. Similarly, NSE
|
||||
scripts should never build regular expressions with untrusted
|
||||
network input. Matching hardcoded regular expressions
|
||||
<emphasis>against</emphasis> the untrusted input is
|
||||
fine.</para></warning>
|
||||
|
||||
<para>The following documentation is derived from that supplied by
|
||||
the PCRE Lua lib.</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre.new(pattern, flags, locale)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns a compiled regular expression. The first
|
||||
argument is a string describing the pattern, such as
|
||||
<literal>^foo$</literal>. The second
|
||||
argument is a number describing which compilation
|
||||
flags are set. The compilation flags are set
|
||||
bitwise. If you want to set the 3rd (corresponding to
|
||||
the number 4) and the 1st (corresponding to 1) bit
|
||||
for example you would pass the number 5 as a second
|
||||
argument. The compilation flags accepted are those
|
||||
of the PCRE C library. These include flags for case
|
||||
insensitive matching (1), matching line beginnings (^)
|
||||
and endings ($) even in multiline strings (i.e. strings
|
||||
containing <quote>\n</quote>) (2) and a flag for matching across
|
||||
line boundaries (4). No compilation flags yield a default
|
||||
value of 0. The third (optional) argument is a string
|
||||
describing the locale which should be used to compile the
|
||||
regular expression. The variable is a string which is
|
||||
passed to the C standard library function
|
||||
<function>setlocale</function>. For more
|
||||
information on this argument refer to the
|
||||
documentation of <function>setlocale</function>. The
|
||||
resulting compiled regular expression is ready to be
|
||||
matched against strings. Compiled regular
|
||||
expressions are subject to Lua's garbage collection.
|
||||
Generally speaking, <literal>my_regex = pcre.new("<replaceable>pcre-pattern</replaceable>",0,"C")</literal>
|
||||
should do the job most of the time.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre.flags()</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns a table of the available PCRE option flags
|
||||
(numbers) keyed by their names (strings). Possible
|
||||
names of the available strings can be retrieved from
|
||||
the documentation of the PCRE library used to link
|
||||
against Nmap. The key is the option name in the
|
||||
manual minus the <literal>PCRE</literal>
|
||||
prefix. <literal>PCRE_CASELESS</literal> becomes
|
||||
<literal>CASELESS</literal> for example.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre.version()</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the version of the PCRE library in use as a
|
||||
string. For example <literal>6.4 05-Sep-2005</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre_obj:match(string, start, flags)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the start point and the end point of
|
||||
the first match of the compiled regular expression
|
||||
pcre_obj in the string. A third
|
||||
returned value is a table which contains
|
||||
<literal>false</literal> in the positions where the
|
||||
pattern did not match. If named sub-patterns were
|
||||
used, the table also contains substring matches keyed
|
||||
by their sub-pattern name. Should no match be found the
|
||||
function returns <literal>nil</literal>.
|
||||
The second and third arguments are optional. The second
|
||||
argument is a number specifying where the engine should
|
||||
start trying to apply the pattern. The third argument
|
||||
specifies execution flags for the pattern.
|
||||
If you want to see if a given string matches a certain expression
|
||||
you could use:</para>
|
||||
|
||||
<programlisting>
|
||||
s = pcre_obj:match("string to be searched", 0,0);
|
||||
if(s) code_to_be_done_on_match end
|
||||
</programlisting>
|
||||
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre_obj:exec(string, start, flags)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This function is like <literal>match()</literal> except that a table returned as
|
||||
a third result contains offsets of substring matches rather
|
||||
than substring matches themselves. That table will not
|
||||
contain string keys, even if named sub-patterns are used. For
|
||||
example, if the whole match is at offsets <literal>10, 20</literal> and substring
|
||||
matches are at offsets <literal>12, 14</literal> and <literal>16, 19</literal> then the function
|
||||
returns the following: <literal>10, 20, {12,14,16,19}</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>pcre_obj:gmatch(string, func, n, ef)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Tries to match the regular expression <replaceable>pcre_obj</replaceable> against <replaceable>string</replaceable>
|
||||
up to <replaceable>n</replaceable> times (or as many as possible if <replaceable>n</replaceable> is either
|
||||
not given or is not a positive number), subject to
|
||||
execution flags ef. Each time there is a match, <replaceable>func</replaceable>
|
||||
is called as <replaceable>func(m, t)</replaceable>, where <replaceable>m</replaceable> is the matched
|
||||
string and <replaceable>t</replaceable> is a table of substring matches. This
|
||||
table contains <literal>false</literal> in the
|
||||
positions where the corresponding sub-pattern did
|
||||
not match. If named sub-patterns are used then the
|
||||
table also contains substring matches keyed by their
|
||||
correspondent sub-pattern names (strings). If <replaceable>func</replaceable>
|
||||
returns a <literal>true</literal> value, then gmatch
|
||||
immediately returns; gmatch returns the number of
|
||||
matches made.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
<indexterm class="endofrange" startref="nse-pcre-indexterm"/>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="nse-openssl">
|
||||
<indexterm class="startofrange" id="nse-openssl-indexterm"><primary><varname>openssl</varname> NSE module</primary></indexterm>
|
||||
<indexterm><primary>OpenSSL</primary><seealso><varname>openssl</varname> NSE module</seealso></indexterm>
|
||||
<indexterm><primary>OpenSSL</primary><secondary>in NSE</secondary></indexterm>
|
||||
<title>OpenSSL NSE bindings</title>
|
||||
|
||||
<para>
|
||||
The <literal>openssl</literal> module is a wrapper for OpenSSL
|
||||
functions that provide encryption and decryption, hashing, and
|
||||
multiprecision integers.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_num_bits(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the size of <literal>bignum</literal> in bits.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_num_bytes(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the size of <literal>bignum</literal> in bytes.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_set_bit(bignum, position)</option></term>
|
||||
<listitem>
|
||||
<para>Sets the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_clear_bit(bignum, position)</option></term>
|
||||
<listitem>
|
||||
<para>Clears the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_is_bit_set(bignum, position)</option></term>
|
||||
<listitem>
|
||||
<para>Gets the state of the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_set_negative(bignum, negative)</option></term>
|
||||
<listitem>
|
||||
<para>Sets the sign of <literal>bignum</literal>. If
|
||||
<literal>negative</literal> is <literal>true</literal>
|
||||
the sign becomes negative, otherwise it becomes positive.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_is_negative(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Returns true if <literal>bignum</literal> is
|
||||
negative, false otherwise.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_bin2bn(string)</option></term>
|
||||
<listitem>
|
||||
<para>Converts the binary-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_dec2bn(string)</option></term>
|
||||
<listitem>
|
||||
<para>Converts the decimal-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_hex2bn(string)</option></term>
|
||||
<listitem>
|
||||
<para>Converts the hex-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_bn2bin(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Converts <literal>bignum</literal> into a binary-encoded string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_bn2dec(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Converts <literal>bignum</literal> into a decimal-encoded string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_bn2hex(bignum)</option></term>
|
||||
<listitem>
|
||||
<para>Converts <literal>bignum</literal> into a hex-encoded string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_rand(bits)</option></term>
|
||||
<listitem>
|
||||
<para>Returns a random <literal>bignum</literal> with a
|
||||
size of <literal>bits</literal> bits.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_pseudo_rand(bits)</option></term>
|
||||
<listitem>
|
||||
<para>Returns a pseudorandom <literal>bignum</literal>
|
||||
with a size of <literal>bits</literal> bits.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.bignum_mod_exp(a, p, m)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the bignum which is the result of <literal>a</literal>^<literal>p</literal> mod <literal>m</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.rand_bytes(bytes)</option></term>
|
||||
<listitem>
|
||||
<para>Returns a string of length
|
||||
<literal>bytes</literal> containing random data.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.rand_pseudo_bytes(bytes)</option></term>
|
||||
<listitem>
|
||||
<para>Returns a string of length
|
||||
<literal>bytes</literal> containing pseudorandom data.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<indexterm><primary>digests, cryptographic</primary></indexterm>
|
||||
<indexterm><primary>hashes, cryptographic</primary></indexterm>
|
||||
<option>openssl.md2(message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the MD2 digest of <literal>message</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.md4(message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the MD4 digest of <literal>message</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.md5(message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the MD5 digest of <literal>message</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.sha1(message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the SHA-1 digest of <literal>message</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.ripemd160(message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the RIPEMD-160 digest of <literal>message</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.digest(algorithm, message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the digest of <literal>message</literal>
|
||||
using the algorithm given by the string
|
||||
<literal>algorithm</literal>. The algorithm name may be
|
||||
anything returned by the
|
||||
<function>openssl.supported_digests</function>
|
||||
function.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.hmac(algorithm, key, message)</option></term>
|
||||
<listitem>
|
||||
<para>Returns the message authentication code of
|
||||
<literal>message</literal> using the given algorithm and
|
||||
key. <literal>algorithm</literal> may be anything
|
||||
returned by the
|
||||
<function>openssl.supported_digests</function>
|
||||
function.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<indexterm><primary>keys, cryptographic</primary></indexterm>
|
||||
<option>openssl.encrypt(algorithm, key, iv, data, padding = false)</option></term>
|
||||
<listitem>
|
||||
<para>Encrypt <literal>data</literal> with the given
|
||||
algorithm, key, and initialization vector.
|
||||
<literal>algorithm</literal> may be anything
|
||||
returned by the
|
||||
<function>openssl.supported_ciphers</function>
|
||||
function. If <literal>padding</literal> is true then a
|
||||
partial final block will be padded and encrypted.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.decrypt(algorithm, key, iv, data, padding = false)</option></term>
|
||||
<listitem>
|
||||
<para>Encrypt <literal>data</literal> with the given
|
||||
algorithm, key, and initialization vector.
|
||||
<literal>algorithm</literal> may be anything
|
||||
returned by the
|
||||
<function>openssl.supported_ciphers</function>
|
||||
function. If <literal>padding</literal> is true then the
|
||||
final block must be padded correctly.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.supported_ciphers()</option></term>
|
||||
<listitem>
|
||||
<para>Returns a table with the names of the supported cipher algorithms.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.supported_digests()</option></term>
|
||||
<listitem>
|
||||
<para>Returns a table with the names of the supported digest algorithms.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>openssl.DES_string_to_key(string data)</option></term>
|
||||
<listitem>
|
||||
<para>Converts <literal>data</literal>, which must be a
|
||||
7-byte string, into an 8-byte DES key and sets the
|
||||
parity.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
<indexterm class="endofrange" startref="nse-openssl-indexterm"/>
|
||||
</sect2>
|
||||
|
||||
<indexterm class="endofrange" startref="nse-library-indexterm"/>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="nse-api">
|
||||
|
||||
Reference in New Issue
Block a user