diff --git a/docs/scripting.xml b/docs/scripting.xml index 0db85cd06..16c339a89 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -763,7 +763,7 @@ action refer to . - Nmap Scripting Engine (NSE)modules + Nmap Scripting Engine (NSE)modules Lua Extensions 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 . require the default modules in order to use them. - The default modules are described in the following sections. - - - pcre NSE module - Perl Compatible Regular Expressions (PCRE)in NSE - regular expressionsin NSE - Perl Compatible Regular Expressions - - - 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 ThomasThomas, Reuben - and Shmuel Zeigerman.Zeigerman, Shmuel - 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 pcre - namespace. - - - Perl Compatible Regular Expressions (PCRE)security vulnerabilities in - 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 - against the untrusted input is - fine. - - The following documentation is derived from that supplied by - the PCRE Lua lib. - - - - - - - - - Returns a compiled regular expression. The first - argument is a string describing the pattern, such as - ^foo$. 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 \n) (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 - setlocale. For more - information on this argument refer to the - documentation of setlocale. The - resulting compiled regular expression is ready to be - matched against strings. Compiled regular - expressions are subject to Lua's garbage collection. - Generally speaking, my_regex = pcre.new("pcre-pattern",0,"C") - should do the job most of the time. - - - - - - - - - - - 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 PCRE - prefix. PCRE_CASELESS becomes - CASELESS for example. - - - - - - - - - - Returns the version of the PCRE library in use as a - string. For example 6.4 05-Sep-2005. - - - - - - - - - - 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 - false 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 nil. - 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: - - -s = pcre_obj:match("string to be searched", 0,0); -if(s) code_to_be_done_on_match end - - - - - - - - - - - This function is like match() 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 10, 20 and substring - matches are at offsets 12, 14 and 16, 19 then the function - returns the following: 10, 20, {12,14,16,19} - - - - - - - - - - Tries to match the regular expression pcre_obj against string - up to n times (or as many as possible if n is either - not given or is not a positive number), subject to - execution flags ef. Each time there is a match, func - is called as func(m, t), where m is the matched - string and t is a table of substring matches. This - table contains false 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 func - returns a true value, then gmatch - immediately returns; gmatch returns the number of - matches made. - - - - - - - - - - openssl NSE module - OpenSSLopenssl NSE module - OpenSSLin NSE - OpenSSL NSE bindings - - - The openssl module is a wrapper for OpenSSL - functions that provide encryption and decryption, hashing, and - multiprecision integers. - - - - - - - - Returns the size of bignum in bits. - - - - - - - Returns the size of bignum in bytes. - - - - - - - Sets the bit at position in bignum. - - - - - - - Clears the bit at position in bignum. - - - - - - - Gets the state of the bit at position in bignum. - - - - - - - Sets the sign of bignum. If - negative is true - the sign becomes negative, otherwise it becomes positive. - - - - - - - Returns true if bignum is - negative, false otherwise. - - - - - - - Converts the binary-encoded string into a bignum. - - - - - - - Converts the decimal-encoded string into a bignum. - - - - - - - Converts the hex-encoded string into a bignum. - - - - - - - Converts bignum into a binary-encoded string. - - - - - - - Converts bignum into a decimal-encoded string. - - - - - - - Converts bignum into a hex-encoded string. - - - - - - - Returns a random bignum with a - size of bits bits. - - - - - - - Returns a pseudorandom bignum - with a size of bits bits. - - - - - - - Returns the bignum which is the result of a^p mod m. - - - - - - - Returns a string of length - bytes containing random data. - - - - - - - Returns a string of length - bytes containing pseudorandom data. - - - - - - digests, cryptographic - hashes, cryptographic - - - Returns the MD2 digest of message. - - - - - - - Returns the MD4 digest of message. - - - - - - - Returns the MD5 digest of message. - - - - - - - Returns the SHA-1 digest of message. - - - - - - - Returns the RIPEMD-160 digest of message. - - - - - - - Returns the digest of message - using the algorithm given by the string - algorithm. The algorithm name may be - anything returned by the - openssl.supported_digests - function. - - - - - - - Returns the message authentication code of - message using the given algorithm and - key. algorithm may be anything - returned by the - openssl.supported_digests - function. - - - - - - keys, cryptographic - - - Encrypt data with the given - algorithm, key, and initialization vector. - algorithm may be anything - returned by the - openssl.supported_ciphers - function. If padding is true then a - partial final block will be padded and encrypted. - - - - - - - Encrypt data with the given - algorithm, key, and initialization vector. - algorithm may be anything - returned by the - openssl.supported_ciphers - function. If padding is true then the - final block must be padded correctly. - - - - - - - Returns a table with the names of the supported cipher algorithms. - - - - - - - Returns a table with the names of the supported digest algorithms. - - - - - - - Converts data, which must be a - 7-byte string, into an 8-byte DES key and sets the - parity. - - - - - - - - diff --git a/nselib/openssl.luadoc b/nselib/openssl.luadoc new file mode 100644 index 000000000..cf1b3eaef --- /dev/null +++ b/nselib/openssl.luadoc @@ -0,0 +1,108 @@ +--- OpenSSL bindings. +-- \n\n +-- This module is a wrapper for OpenSSL functions that provide encryption and +-- decryption, hashing, and multiprecision integers. +-- @author Sven Klemm +-- @copyright See nmaps COPYING for licence + +module "openssl" + +--- Returns the size of bignum in bits. +function openssl.bignum_num_bits(bignum) + +--- Returns the size of bignum in bytes. +function openssl.bignum_num_bytes(bignum) + +--- Sets the bit at position in bignum. +function openssl.bignum_set_bit(bignum, position) + +--- Clears the bit at position in bignum. +function openssl.bignum_clear_bit(bignum, position) + +--- Gets the state of the bit at position in bignum. +function openssl.bignum_is_bit_set(bignum, position) + +--- Sets the sign of bignum. If negative is true the sign becomes negative, +-- otherwise it becomes positive. +function openssl.bignum_set_negative(bignum, negative) + +--- Returns true if bignum is negative, false otherwise. +function openssl.bignum_is_negative(bignum) + +--- Converts the binary-encoded string into a bignum. +function openssl.bignum_bin2bn(string) + +--- Converts the decimal-encoded string into a bignum. +function openssl.bignum_dec2bn(string) + +--- Converts the hex-encoded string into a bignum. +function openssl.bignum_hex2bn(string) + +--- Converts bignum into a binary-encoded string. +function openssl.bignum_bn2bin(bignum) + +--- Converts bignum into a decimal-encoded string. +function openssl.bignum_bn2dec(bignum) + +--- Converts bignum into a hex-encoded string. +function openssl.bignum_bn2hex(bignum) + +--- Returns a random bignum with a +function openssl.bignum_rand(bits) + +--- Returns a pseudorandom bignum with a the given size in bits. +function openssl.bignum_pseudo_rand(bits) + +--- Returns the bignum which is the result of a^p mod m. +function openssl.bignum_mod_exp(a, p, m) + +--- Returns a string of length bytes containing random data. +function openssl.rand_bytes(bytes) + +--- Returns a string of length bytes containing pseudorandom data. +function openssl.rand_pseudo_bytes(bytes) + +--- Returns the MD2 digest of message. +function openssl.md2(message) + +--- Returns the MD4 digest of message. +function openssl.md4(message) + +--- Returns the MD5 digest of message. +function openssl.md5(message) + +--- Returns the SHA-1 digest of message. +function openssl.sha1(message) + +--- Returns the RIPEMD-160 digest of message. +function openssl.ripemd160(message) + +--- Returns the digest of message using the algorithm given by the string +-- algorithm. The algorithm name may be anything returned by the +-- openssl.supported_digests function. +function openssl.digest(algorithm, message) + +--- Returns the message authentication code of message using the given algorithm +-- and key. algorithm may be anything returned by the openssl.supported_digests +-- function. +function openssl.hmac(algorithm, key, message) + +--- Encrypt data with the given algorithm, key, and initialization vector. +-- algorithm may be anything returned by the openssl.supported_ciphers function. +-- If padding is true then a partial final block will be padded and encrypted. +function openssl.encrypt(algorithm, key, iv, data, padding = false) + +--- Encrypt data with the given algorithm, key, and initialization vector. +-- algorithm may be anything returned by the openssl.supported_ciphers function. +-- If padding is true then the final block must be padded correctly. +function openssl.decrypt(algorithm, key, iv, data, padding = false) + +--- Returns a table with the names of the supported cipher algorithms. +function openssl.supported_ciphers() + +--- Returns a table with the names of the supported digest algorithms. +function openssl.supported_digests() + +--- Converts data, which must be a 7-byte string, into an 8-byte DES key and +-- sets the parity. +function openssl.DES_string_to_key(string data) diff --git a/nselib/pcre.luadoc b/nselib/pcre.luadoc new file mode 100644 index 000000000..726ed424e --- /dev/null +++ b/nselib/pcre.luadoc @@ -0,0 +1,119 @@ +--- Perl Compatible Regular Expressions +-- \n\n +-- 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 and Shmuel +-- Zeigerman. 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. +-- \n\n +-- The documentation for this module is derived from that supplied by the PCRE +-- Lua lib. +-- \n\n +-- Warning: 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 against the untrusted input is fine. +-- @author Reuben Thomas +-- @author Shmuel Zeigerman + +module "pcre" + +--- Returns a compiled regular expression. +-- \n\n +-- The resulting compiled regular expression is ready to be matched against +-- strings. Compiled regular expressions are subject to Lua's garbage +-- collection. +-- \n\n +-- 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 newlines) (2) and a flag for +-- matching across line boundaries (4). No compilation flags yield a default +-- value of 0. +-- @param pattern a string describing the pattern, such as "^foo$". +-- @param flags a number describing which compilation flags are set. +-- @param locale a string describing the locale which should be used to compile +-- the regular expression (optional). The value is a string which is passed to +-- the C standard library function setlocale. For more information on this +-- argument refer to the documentation of setlocale. +-- @usage my_regex = pcre.new("pcre-pattern",0,"C") +function pcre.new(pattern, flags, locale) + +--- Returns a table of the available PCRE option flags (numbers) keyed by their +-- names (strings). +-- \n\n +-- 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 PCRE prefix. PCRE_CASELESS becomes +-- CASELESS for example. +function pcre.flags() + +--- Returns the version of the PCRE library in use as a string. +-- \n\n +-- For example "6.4 05-Sep-2005". +function pcre.version() + +--- Matches a string against a compiled regular expression. +-- \n\n +-- Returns the start point and the end point of the first match of the compiled +-- regular expression pcre_obj in the string. +-- @param string the string to match against. +-- @param start where to start the match in the string (optional). +-- @param flags execution flags (optional). +-- @return nil if no match, otherwise the start point of the first match. +-- @return the end point of the first match. +-- @return a table which contains false 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. +-- @usage +-- s = pcre_obj:match("string to be searched", 0,0);\n +-- if(s) code_to_be_done_on_match end +function pcre_obj:match(string, start, flags) + +--- Matches a string against a compiled regular expression, returning positions +-- of substring matches. +-- \n\n +-- This function is like match() 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 10, 20 +-- and substring matches are at offsets 12, 14 and 16, 19 then the function +-- returns the following: 10, 20, {12,14,16,19} +-- @param string the string to match against. +-- @param start where to start the match in the string (optional). +-- @param flags execution flags (optional). +-- @return a table which contains a list of substring match start and end +-- positions. +function pcre_obj:exec(string, start, flags) + +--- Matches a string against a regular expression multiple times. +-- \n\n +-- Tries to match the regular expression pcre_obj against string up to n times +-- (or as many as possible if n is either not given or is not a positive +-- number), subject to the execution flags ef. Each time there is a match, func +-- is called as func(m, t), where m is the matched string and t is a table of +-- substring matches. This table contains false 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 func returns a true value, then gmatch +-- immediately returns; gmatch returns the number of matches made. +-- @param string the string to match against. +-- @param n the maximum number of matches to do (optional). +-- @param ef execution flags (optional). +-- @return the number of matches made. +function pcre_obj:gmatch(string, func, n, ef)