Creates a context that is used to wrap a TCP connection. In case of errors, the function returns nil, followed by an error message.
params is a table that contains parameters to create the context. These parameters can be:
| Key |
Value Type
|
Value |
Mandatory
|
|---|---|---|---|
| mode |
String
|
Use "client" or "server". |
Yes
|
| protocol |
String
|
|
Yes
|
| key |
String
|
Path to the file that contains the key (in PEM format). |
No
|
| password |
String /
Function |
Password of the encrypted key, or a callback function that returns it. If the callback does not return a string, a null password is used. |
No
|
| certificate |
String
|
Path to the file that contains the chain certificates. These must be in PEM format and must be sorted starting from the subject's certificate (client or server), followed by intermediate CA certificates if applicable, and ending at the highest level CA. |
No
|
| cafile |
String
|
Path to the file that contains a
set of trusting certificates (in PEM format). |
No
|
| capath |
String
|
Path to the directory that
constains a set of files with trusting certificates. |
No
|
| verify |
String /
Table
|
Options used to verify the
certificates. Use an array of strings for multiple options. |
No
|
| options |
String /
Table
|
Options to change the behaviour
of the OpenSSL library. Use an array of strings for multiple options. |
No
|
| ciphers |
String
|
The list of ciphers to be used in
the connection. |
No
|
| depth |
Number
|
Maximum depth in the certificate chain verification. |
No
|
Please, see OpenSSL documentation for more information.
The field verify supports:
The field options supports:
Note: you need to check if your version of OpenSSL provides these options
Wraps the TCP connection sock and returns a new object that is used to establish a secure session. In case of error, the function returns nil, followed by an error message.
ssl.wrap needs a context, which provides parameters such as protocol, certificate, key, etc., in order to create the new connection object. You can provide a already created context in params or a table with the parameters. In this case, ssl.wrap calls ssl.newcontext to obtain the context.
Note: ssl.wrap invalidates the socket passed as argument. This prevents the garbage collector to close the TCP connection when the socket object is disposed.
Closes the connection.
Performs theTLS/SSL handshake to establesh the secure connection. In case of success, the function returns true, otherwise, false followed by an error message.
If timeout is set, dohandshake returns the messages "wantread" and "wantwrite", instead of "timeout". wantread indicates that the operation is not finished because a timeout in the underline TCP connection prevents it of sending data. In the same way, wantwrite indicates a timeout while receiving information from network. In these cases, you can call socket.select to wait the connection to be ready for reading or writing and call dohandshake again to finish the operation. For example:
local succ, msg
conn:settimeout(0)
while not succ do
succ, msg = conn:dohandshake()
if msg == 'wantread' then
socket.select({conn}, nil)
elseif msg == 'wantwrite' then
socket.select(nil, {conn})
else
-- other errors
end
end
conn:receive([[pattern] [, prefix]])
Reads data from the connection conn, according to the specified read pattern:
'*a': reads from the connection until it is closed. No end-of-line translation is performed;
'*l': reads a line of text from the connection. The line is terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not included in the returned line. In fact, all CR characters are ignored by the pattern. This is thedefault pattern;
number: causes the method to read a specified number of bytes from the socket.
The parameter prefix is an optional string to be concatenated to the beginning of any received data before return.
If successful, the method returns the received pattern. In case of error, the method returns nil followed by an error message.
Among the error messages, "closed" indicates that the connection was closed before the transmission was completed; "wantread" and "wantwrite" indicates that a timeout occured during the operation. Also, after the error message, the function returns the partial result of the transmission.
In the case of wantread or wantwrite errors, you should wait the connection to be ready for reading or writing, respectively, and call receive again (see dohandshake).
Sends data through the connection.
data is the string to be sent. The optional arguments i and j work exactly like the standard string.sub Lua function to allow the selection of a substring to be sent.
If successful, the method returns the index of the last byte within [i, j] that has been sent. Notice that, if i is 1 or absent, this is effectively the total number of bytes sent. In case of error, the method returns nil, followed by an error message and the index of the last byte within [i, j] that has been sent. You might want to try again from the byte following that.
Among the error messages, "closed"indicates that the connection was closed before the transmission was completed; "wantread" and "wantwrite" indicates that a timeout occured during the operation.
In the case of wantread or wantwrite errors, you should wait the connection to be ready for reading or writing, respectively, and call send again (see dohandshake).
conn:settimeout(value [, mode])
Changes the timeout values for the connection. By default, the operations send, receive, and dohandshake will block indefinitely, until the operation completes. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code.
The amount of time to wait is specified as the value parameter, in seconds. There are two timeout modes and both can be used together for fine tuning:
The nil timeout value allows operations to block indefinitely. Negative timeout values have the same effect.
Informs the reason that triggers the timeout in the last call of send, receive, or dohandshake. The string "read" indicates the operation was not performed because the connection was not ready for reading. In the same way, "write" indicates the connection was not ready for writing. If the operations were successfully complited, the string "nothing" is returned.
This is a simple HTTPS client built on top of LuaSocket's HTTP module. This function creates a custom create function, that performs the secure connection with the server, and passes it to LuaSocket.
If url is a table, it should contain a union of LuaSocket's HTTP options and LuaSec configuration. However, the current implementation does not support proxy nor URL redirection, so the fields redirect and proxy are not supported in url. Also, setting http.PROXY is not permitted.
In the case url is a string, the module uses the following default configuration to establish the connection:
default = {
protocol = "tlsv1",
options = "all",
verify = "none",
}
The parameter body is an optional string sent as request body.
In case of failure, https.requet returns nil followed by an error message. In case of success, if url is a string, the function returns the response's body, status code, headers, and status line. If url is a table, the function returns the same results, except the response's body is replaced by the value 1.
Some examples:
local res, code, headers, status = https.request("https://www.site.com.br")
local one, code, headers, status = https.request {
url = "https://www.site.com.br",
sink = ltn12.sink.file(io.stdout),
protocol = "tlsv1",
options = "all",
verify = "none",
}
| Last update: 03-Mar-2011 17:58 |
|
SSL Lua SSL Lua OpenSSL Lua OpenSSL