constant
Protocols.HTTP.response_codes
Mapping from StatusCode
to descriptive string.
StatusCode
.Query
delete_url(string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Sends a HTTP DELETE request to the server in the URL and returns
the created and initialized Query
object. 0
is returned
upon failure. If a query object having
request_headers->Connection=="Keep-Alive"
from a previous
request is provided and the already established server connection
can be used for the next request, you may gain some performance.
void
do_async_method(string
method
, string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, Protocols.HTTP.Query
con
, void
|string
data
)
Low level asynchronous HTTP call method.
method
The HTTP method to use, e.g. "GET"
.
url
The URL to perform method
on. Should be a complete URL,
including protocol, e.g. "https://pike.lysator.liu.se/"
.
query_variables
Calls http_encode_query
and appends the result to the URL.
request_headers
The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.
con
Previously initialized connection object.
In particular the callbacks must have been set
(Query.set_callbacks()
).
data
Data payload to be transmitted in the request.
do_method()
, Query.set_callbacks()
void
do_async_proxied_method(string
|Standards.URI
proxy
, string
user
, string
password
, string
method
, string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, Protocols.HTTP.Query
con
, void
|string
data
)
Low level asynchronous proxied HTTP call method.
Makes an HTTP request through a proxy.
proxy
URL for the proxy.
user
password
Proxy authentication credentials.
method
The HTTP method to use, e.g. "GET"
.
url
The URL to perform method
on. Should be a complete URL,
including protocol, e.g. "https://pike.lysator.liu.se/"
.
query_variables
Calls http_encode_query
and appends the result to the URL.
request_headers
The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.
con
Previously initialized connection object.
In particular the callbacks must have been set
(Query.set_callbacks()
).
data
Data payload to be transmitted in the request.
do_async_method()
, do_proxied_method()
, Query.set_callbacks()
.Query
|zero
do_method(string
method
, string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
, void
|string
data
)
Low level HTTP call method.
method
The HTTP method to use, e.g. "GET"
.
url
The URL to perform method
on. Should be a complete URL,
including protocol, e.g. "https://pike.lysator.liu.se/"
.
query_variables
Calls http_encode_query
and appends the result to the URL.
request_headers
The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.
con
Old connection object.
data
Data payload to be transmitted in the request.
do_sync_method()
.Query
do_proxied_method(string
|Standards.URI
proxy
, string
user
, string
password
, string
method
, string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
, void
|string
data
)
Makes an HTTP request through a proxy.
proxy
URL for the proxy.
user
password
Proxy authentication credentials.
method
url
query_variables
request_headers
con
data
The remaining arguments are identical to do_method()
.
do_method()
, do_async_proxied_method()
.Query
get_url(string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Sends a HTTP GET request to the server in the URL and returns the
created and initialized Query
object. 0
is returned
upon failure. If a query object having
request_headers->Connection=="Keep-Alive"
from a previous
request is provided and the already established server connection
can be used for the next request, you may gain some performance.
string
get_url_data(string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Returns the returned data after calling the requested server for
information through HTTP GET. 0
is returned upon failure.
Redirects (HTTP 302) are automatically followed.
array
(string
)|zero
get_url_nice(string
|Standards.URI
url
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Returns an array of ({content_type, data})
after calling
the requested server for the information. 0
is returned
upon failure. Redirects (HTTP 302) are automatically followed.
string
http_encode_query(mapping
(string
:int
|string
|array
(string
)) variables
)
Encodes a query mapping to a string; this protects odd - in http perspective - characters like '&' and '#' and control characters, and packs the result together in a HTTP query string.
Example:
> Protocols.HTTP.http_encode_query( (["anna":"eva","lilith":"blue"]) ); Result: "lilith=blue&anna=eva" > Protocols.HTTP.http_encode_query( (["&":"&","'=\"":"\0\0\0\u0434"]) ); Result: "%27%3D%22=%00%00%00%D0%B4&%26amp%3B=%26"
string
iri_encode(string
s
)
Encodes the given string using %XX encoding to be used as a
component part in an IRI (Internationalized Resource Identifier,
see RFC 3987). This means that all chars outside the IRI
iunreserved set are encoded, i.e. this function encodes
equivalently to uri_encode
except that all 8-bit and wider
characters are left as-is.
This function currently does not encode chars in the Unicode private ranges, although that is strictly speaking required in some but not all IRI components. That could change if it turns out to be a problem.
percent_decode
, uri_encode
string
percent_decode(string
s
)
Decodes URI-style %XX encoded chars in the given string.
percent_encode
, uri_decode
This function currently does not accept wide string input, which
is necessary to work as the reverse of iri_encode
.
string
percent_encode(string
s
)
Encodes the given string using %XX encoding, except that URI unreserved chars are not encoded. The unreserved chars are A-Z, a-z, 0-9, -, ., _, and ~ (see RFC 2396 section 2.3).
8-bit chars are encoded straight, and wider chars are not allowed.
That means this encoding is applicable if s
is a binary octet
string. If it is a character string then uri_encode
should be
used instead.
It is also slightly faster than uri_encode
if s
is known to
contain only US-ASCII.
.Query
post_url(string
|Standards.URI
url
, mapping
(string
:int
|string
|array
(string
))|string
query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Similar to get_url
, except that query variables is sent as a
POST request instead of a GET request. If query_variables is a
simple string, it is assumed to contain the verbatim
body of the POST request; Content-Type must be properly specified
manually, in this case.
string
post_url_data(string
|Standards.URI
url
, mapping
(string
:int
|string
|array
(string
))|string
query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Similar to get_url_data
, except that query variables is sent as
a POST request instead of a GET request.
array
(string
) post_url_nice(string
|Standards.URI
url
, mapping
(string
:int
|string
|array
(string
))|string
query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Similar to get_url_nice
, except that query variables is sent as
a POST request instead of a GET request.
.Query
put_url(string
|Standards.URI
url
, void
|string
file
, void
|mapping
(string
:int
|string
|array
(string
)) query_variables
, void
|mapping
(string
:string
|array
(string
)|int
) request_headers
, void
|Protocols.HTTP.Query
con
)
Sends a HTTP PUT request to the server in the URL and returns the
created and initialized Query
object. 0
is returned upon
failure. If a query object having
request_headers->Connection=="Keep-Alive"
from a previous
request is provided and the already established server connection
can be used for the next request, you may gain some performance.
string
quoted_string_decode(string
s
)
Decodes the given string which has been encoded as a
quoted-string according to RFC 2616 section 2.2. s
is assumed
to not include the surrounding " chars.
quoted_string_encode
string
quoted_string_encode(string
s
)
Encodes the given string quoted to be used as content inside a quoted-string according to RFC 2616 section 2.2. The returned string does not include the surrounding " chars.
The quoted-string quoting rules in RFC 2616 have several problems:
Quoting is inconsistent since " is quoted as \", but \ does not need to be quoted. This is resolved in the HTTP bis update to mandate quoting of \ too, which this function performs.
Many characters are not quoted sufficiently to make the result
safe to use in an HTTP header, so this quoting is not enough if
s
contains NUL, CR, LF, or any 8-bit or wider character.
quoted_string_decode
string
uri_decode(string
s
)
Decodes URI-style %XX encoded chars in the given string, and
then UTF-8 decodes the result. This is the reverse of
uri_encode
and uri_encode_invalids
.
uri_encode
, uri_encode_invalids
string
uri_encode(string
s
)
Encodes the given string using %XX encoding to be used as a component part in a URI. This means that all URI reserved and excluded characters are encoded, i.e. everything except A-Z, a-z, 0-9, -, ., _, and ~ (see RFC 2396 section 2.3).
8-bit chars and wider are encoded using UTF-8 followed by percent-encoding. This follows RFC 3986 section 2.5, the IRI-to-URI conversion method in the IRI standard (RFC 3987) and appendix B.2 in the HTML 4.01 standard. It should work regardless of the charset used in the XML document the URI might be inserted into.
uri_decode
, uri_encode_invalids
, iri_encode
string
uri_encode_invalids(string
s
)
Encodes all "dangerous" chars in the given string using %XX encoding, so that it can be included as a URI in an HTTP message or header field. This includes control chars, space and various delimiter chars except those in the URI reserved set (RFC 2396 section 2.2).
Since this function doesn't touch the URI reserved chars nor the escape char %, it can be used on a complete formatted URI or IRI.
8-bit chars and wider are encoded using UTF-8 followed by percent-encoding. This follows RFC 3986 section 2.5, the IRI standard (RFC 3987) and appendix B.2 in the HTML 4.01 standard.
The characters in the URI reserved set are: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =. In addition, this function doesn't touch the escape char %.
uri_decode
, uri_encode
HTTP Status codes.
response_codes
,
https://www.iana.org/assignments/http-status-codes/http-status-codes.txt
constant
Protocols.HTTP.DAV_ALREADY_REPORTED
RFC 5842 section 7.1: 208 Already Reported
constant
Protocols.HTTP.DAV_FAILED_DEP
RFC 2518 section 10.5: 424 Failed Dependency
constant
Protocols.HTTP.DAV_LOCKED
RFC 2518 section 10.4: 423 Locked
constant
Protocols.HTTP.DAV_LOOP_DETECTED
RFC 5842 section 7.2: 508 Loop Detected
constant
Protocols.HTTP.DAV_MULTISTATUS
RFC 2518 section 10.2: 207 Multi-Status
constant
Protocols.HTTP.DAV_PROCESSING
RFC 2518 section 10.1: 102 Processing
constant
Protocols.HTTP.DAV_STORAGE_FULL
RFC 2518 section 10.6: 507 Insufficient Storage
constant
Protocols.HTTP.DAV_UNPROCESSABLE
RFC 2518 section 10.3: 422 Unprocessable Entry
constant
Protocols.HTTP.DELTA_HTTP_IM_USED
RFC 3229 section 10.4.1: 226 IM Used
constant
Protocols.HTTP.HTCPCP_TEAPOT
RFC 2324 section 2.3.2: 418 I'm a teapot
constant
Protocols.HTTP.HTTP_ACCEPTED
RFC 2616 section 10.2.3: 202 Accepted
constant
Protocols.HTTP.HTTP_BAD
RFC 2616 section 10.4.1: 400 Bad Request
constant
Protocols.HTTP.HTTP_BAD_GW
RFC 2616 section 10.5.3: 502 Bad Gateway
constant
Protocols.HTTP.HTTP_BAD_RANGE
RFC 2616 section 10.4.17: 416 Requested Range Not Satisfiable
constant
Protocols.HTTP.HTTP_CONFLICT
RFC 2616 section 10.4.10: 409 Conflict
constant
Protocols.HTTP.HTTP_CONTINUE
RFC 2616 section 10.1.1: 100 Continue
constant
Protocols.HTTP.HTTP_CREATED
RFC 2616 section 10.2.2: 201 Created
constant
Protocols.HTTP.HTTP_EARLY_HINTS
RFC 8297 section 2: 103 Early Hints
constant
Protocols.HTTP.HTTP_EXPECT_FAILED
RFC 2616 section 10.4.18: 417 Expectation Failed
constant
Protocols.HTTP.HTTP_FORBIDDEN
RFC 2616 section 10.4.4: 403 Forbidden
constant
Protocols.HTTP.HTTP_FOUND
RFC 2616 section 10.3.3: 302 Found
constant
Protocols.HTTP.HTTP_GONE
RFC 2616 section 10.4.11: 410 Gone
constant
Protocols.HTTP.HTTP_GW_TIMEOUT
RFC 2616 section 10.5.5: 504 Gateway Timeout
constant
Protocols.HTTP.HTTP_HEADERS_TOO_LARGE
RFC 6585 section 5: 431 Request Header Fields Too Large
constant
Protocols.HTTP.HTTP_INTERNAL_ERR
RFC 2616 section 10.5.1: 500 Internal Server Error
constant
Protocols.HTTP.HTTP_LEGALLY_RESTRICTED
RFC 7725 section 3: 451 Unavailable For Legal Reasons
constant
Protocols.HTTP.HTTP_LENGTH_REQ
RFC 2616 section 10.4.12: 411 Length Required
constant
Protocols.HTTP.HTTP_METHOD_INVALID
RFC 2616 section 10.4.6: 405 Method Not Allowed
constant
Protocols.HTTP.HTTP_MISDIRECTED_REQ
RFC 7540 section 9.1.2: 421 Misdirected Request
constant
Protocols.HTTP.HTTP_MOVED_PERM
RFC 2616 section 10.3.2: 301 Moved Permanently
constant
Protocols.HTTP.HTTP_MULTIPLE
RFC 2616 section 10.3.1: 300 Multiple Choices
constant
Protocols.HTTP.HTTP_NET_AUTH_REQUIRED
RFC 6585 section 6: 511 Network Authentication Required
constant
Protocols.HTTP.HTTP_NONAUTHORATIVE
RFC 2616 section 10.2.4: 203 Non-Authorative Information
constant
Protocols.HTTP.HTTP_NOT_ACCEPTABLE
RFC 2616 section 10.4.7: 406 Not Acceptable
constant
Protocols.HTTP.HTTP_NOT_EXTENDED
RFC 2774 section 7: 510 Not Extended (obsolete)
constant
Protocols.HTTP.HTTP_NOT_FOUND
RFC 2616 section 10.4.5: 404 Not Found
constant
Protocols.HTTP.HTTP_NOT_IMPL
RFC 2616 section 10.5.2: 501 Not Implemented
constant
Protocols.HTTP.HTTP_NOT_MODIFIED
RFC 2616 section 10.3.5: 304 Not Modified
constant
Protocols.HTTP.HTTP_NO_CONTENT
RFC 2616 section 10.2.5: 204 No Content
constant
Protocols.HTTP.HTTP_OK
RFC 2616 section 10.2.1: 200 OK
constant
Protocols.HTTP.HTTP_PARTIAL_CONTENT
RFC 2616 section 10.2.7: 206 Partial Content
constant
Protocols.HTTP.HTTP_PAY
RFC 2616 section 10.4.3: 402 Payment Required
constant
Protocols.HTTP.HTTP_PERM_REDIRECT
RFC 7538 section 3: 308 Permanent Redirect
constant
Protocols.HTTP.HTTP_PRECOND_FAILED
RFC 2616 section 10.4.13: 412 Precondition Failed
constant
Protocols.HTTP.HTTP_PRECOND_REQUIRED
RFC 6585 section 3: 428 Precondition required
constant
Protocols.HTTP.HTTP_PROXY_AUTH_REQ
RFC 2616 section 10.4.8: 407 Proxy Authentication Required
constant
Protocols.HTTP.HTTP_REQ_TOO_LARGE
RFC 2616 section 10.4.14: 413 Request Entity Too Large
constant
Protocols.HTTP.HTTP_RESET_CONTENT
RFC 2616 section 10.2.6: 205 Reset Content
constant
Protocols.HTTP.HTTP_SEE_OTHER
RFC 2616 section 10.3.4: 303 See Other
constant
Protocols.HTTP.HTTP_SWITCH_PROT
RFC 2616 section 10.1.2: 101 Switching protocols
constant
Protocols.HTTP.HTTP_TEMP_REDIRECT
RFC 2616 section 10.3.8: 307 Temporary Redirect
constant
Protocols.HTTP.HTTP_TIMEOUT
RFC 2616 section 10.4.9: 408 Request Timeout
constant
Protocols.HTTP.HTTP_TOO_MANY_REQUESTS
RFC 6585 section 4: 429 Too Many Requests
constant
Protocols.HTTP.HTTP_UNAUTH
RFC 2616 section 10.4.2: 401 Unauthorized
constant
Protocols.HTTP.HTTP_UNAVAIL
RFC 2616 section 10.5.4: 503 Service Unavailable
constant
Protocols.HTTP.HTTP_UNSUPP_MEDIA
RFC 2616 section 10.4.16: 415 Unsupported Media Type
constant
Protocols.HTTP.HTTP_UNSUPP_VERSION
RFC 2616 section 10.5.6: 505 HTTP Version Not Supported
constant
Protocols.HTTP.HTTP_URI_TOO_LONG
RFC 2616 section 10.4.15: 414 Request-URI Too Long
constant
Protocols.HTTP.HTTP_USE_PROXY
RFC 2616 section 10.3.6: 305 Use Proxy
constant
Protocols.HTTP.TCN_VARIANT_NEGOTIATES
RFC 2295 section 8.1: 506 Variant Also Negotiates
constant
Protocols.HTTP.TLS_TOO_EARLY
RFC 8470 section 5.2: 425 Too Early
constant
Protocols.HTTP.TLS_UPGRADE_REQUIRED
RFC 2817 section 4.2: 426 Upgrade Required
Open and execute an HTTP query.
HTTP.Query o=HTTP.Query();
void ok() { write("ok...\n"); write("%O\n", o->headers); exit(0); }
void fail() { write("fail\n"); exit(0); }
int main() { o->set_callbacks(ok, fail); o->async_request("pike.lysator.liu.se", 80, "HEAD / HTTP/1.0"); return -1; }
int
Protocols.HTTP.Query.errno
Errno copied from the connection or simulated for async operations.
In Pike 7.8 and earlier hardcoded Linux values were used in
async operations, 110 instead of System.ETIMEDOUT
and
113 instead of System.EHOSTUNREACH
.
mapping
Protocols.HTTP.Query.headers
Headers as a mapping. All header names are in lower case, for convinience.
string
Protocols.HTTP.Query.host
string
Protocols.HTTP.Query.real_host
int
Protocols.HTTP.Query.port
Connected host and port.
Used to detect whether keep-alive can be used.
mapping
(string
:array
(string
)) Protocols.HTTP.Query.hostname_cache
Set this to a global mapping if you want to use a cache, prior of calling *request().
int
Protocols.HTTP.Query.timeout
int
Protocols.HTTP.Query.maxtime
timeout
is the time to wait in seconds on connection and/or data.
If data is fetched asynchronously the watchdog will be reset every time
data is received. Defaults to 120 seconds.
maxtime
is the time the entire operation is allowed to take, no matter
if the connection and data fetching is successful. This is by default
indefinitely.
These values only have effect in asynchroneous calls
int
Protocols.HTTP.Query.ok
Tells if the connection is successfull.
string
Protocols.HTTP.Query.protocol
Protocol string, ie "HTTP/1.0"
.
int
Protocols.HTTP.Query.status
string
Protocols.HTTP.Query.status_desc
Status number and description (eg 200
and "ok"
).
int
res = Protocols.HTTP.Query()
()
Wait for connection to complete.
Returns 1
on successfull connection, 0
on failure.
void
async_fetch(function
(:void
) callback
, mixed
... extra
)
Fetch all data in background.
timed_async_fetch()
, async_request()
, set_callbacks()
Protocols.HTTP.Query
set_callbacks(function
(:void
)|zero
request_ok
, function
(:void
)|zero
request_fail
, mixed
... extra
)
Protocols.HTTP.Query
async_request(string
server
, int
port
, string
query
)
Protocols.HTTP.Query
async_request(string
server
, int
port
, string
query
, mapping
headers
, string
|void
data
)
Setup and run an asynchronous request,
otherwise similar to thread_request()
.
request_ok
(Protocols.HTTP.Query httpquery,...extra args)
will be called when connection is complete,
and headers are parsed.
request_fail
(Protocols.HTTP.Query httpquery,...extra args)
is called if the connection fails.
Returns the called object
(
array
)Protocols.HTTP.Query()
Array | |
| Headers |
| Data |
| Protocol |
| Status |
| Status description |
(
mapping
)Protocols.HTTP.Query()
The header mapping ORed with the following mapping.
| The protocol. |
| The status code. |
| The status description. |
| The returned data. |
(
string
)Protocols.HTTP.Query()
Gives back the answer as a string.
void
close()
Close all associated file descriptors.
string
data(int
|void
max_length
)
Gives back the data as a string.
Protocols.HTTP.Query.PseudoFile
datafile()
Gives back a pseudo-file object,
with the methods read()
and close()
.
This could be used to copy the file to disc at
a proper tempo.
datafile()
doesn't give the complete request,
just the data.
file()
int
downloaded_bytes()
Gives back the number of downloaded bytes.
Protocols.HTTP.Query.PseudoFile
file()
Protocols.HTTP.Query.PseudoFile
file(mapping
newheaders
, void
|mapping
removeheaders
)
Gives back a pseudo-file object,
with the methods read()
and close()
.
This could be used to copy the file to disc at
a proper tempo.
newheaders
, removeheaders
is applied as:
(oldheaders|newheaders))-removeheaders
Make sure all new and remove-header indices are lower case.
datafile()
Protocols.HTTP.Query
thread_request(string
server
, int
port
, string
query
)
Protocols.HTTP.Query
thread_request(string
server
, int
port
, string
query
, mapping
headers
, void
|string
data
)
Create a new query object and begin the query.
The query is executed in a background thread;
call `()
in the object to wait for the request
to complete.
query
is the first line sent to the HTTP server;
for instance "GET /index.html HTTP/1.1"
.
headers
will be encoded and sent after the first line,
and data
will be sent after the headers.
Returns the called object.
void
timed_async_fetch(function
(this_program
, __unknown__
... :void
) ok_callback
, function
(this_program
, __unknown__
... :void
) fail_callback
, mixed
... extra
)
Like async_fetch()
, except with a timeout and a corresponding fail
callback function.
async_fetch()
, async_request()
, set_callbacks()
int
total_bytes()
Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.
string
unicode_data()
Gives back data, but decoded according to the content-type character set.
data
Minimal simulation of a Stdio.File
object.
Objects of this class are returned by file()
and datafile()
.
Do not attempt further queries using this Query
object
before having read all data.
void
close()
string
read(int
n
, bool
|void
not_all
)
typedef
string
|Standards.URI
|SessionURL
Protocols.HTTP.Session.URL
A URL which is either a string a Standards.URI
or a SessionURL
.
mapping
Protocols.HTTP.Session.default_headers
Default HTTP headers.
int
Protocols.HTTP.Session.follow_redirects
The number of redirects to follow, if any. This is the default to the created Request objects.
A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.
Default is 20 redirects. A negative number will mean infinity.
Loops will currently not be detected, only the limit works to stop loops.
Request.follow_redirects
mapping
Protocols.HTTP.Session.hostname_cache
Cache of hostname to IP lookups. Given to and used by the
Query
objects.
int
Protocols.HTTP.Session.maximum_connection_reuse
Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.
int
Protocols.HTTP.Session.maximum_connections_per_server
Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.
int
Protocols.HTTP.Session.maximum_total_connections
Maximum total number of connections. Limits only async requests, and the number of kept-alive connections (live connections + kept-alive connections <= this number) Defaults to 50 connections.
int
|float
Protocols.HTTP.Session.time_to_keep_unused_connections
The time to keep unused connections in seconds. Set to zero to never save any kept-alive connections. (Might be good in a for instance totaly synchroneous script that keeps the backend thread busy and never will get call_outs.) Defaults to 10 seconds.
Request
async_get_url(URL
url
, void
|mapping
query_variables
, function
(:void
)|zero
callback_headers_ok
, function
(:void
)|zero
callback_data_ok
, function
(:void
)|zero
callback_fail
, mixed
... callback_arguments
)
Request
async_put_url(URL
url
, void
|string
file
, void
|mapping
query_variables
, function
(:void
)|zero
callback_headers_ok
, function
(:void
)|zero
callback_data_ok
, function
(:void
)|zero
callback_fail
, mixed
... callback_arguments
)
Request
async_delete_url(URL
url
, void
|mapping
query_variables
, function
(:void
)|zero
callback_headers_ok
, function
(:void
)|zero
callback_data_ok
, function
(:void
)|zero
callback_fail
, mixed
... callback_arguments
)
Request
async_post_url(URL
url
, mapping
query_variables
, function
(:void
)|zero
callback_headers_ok
, function
(:void
)|zero
callback_data_ok
, function
(:void
)|zero
callback_fail
, mixed
... callback_arguments
)
Sends a HTTP GET, POST, PUT or DELETE request to the server in
the URL asynchroneously, and call the corresponding callbacks
when result arrives (or not). The callbacks will receive
the created Request object as first argument, then
the given callback_arguments
, if any.
callback_headers_ok
is called when the HTTP request has received
headers.
callback_data_ok
is called when the HTTP request has been
received completely, data and all.
callback_fail
is called when the HTTP request has failed,
on a TCP/IP or DNS level, or has received a forced timeout.
The created Request object is returned.
string
encode_cookies()
void
decode_cookies(string
data
, void
no_clear
)
Dump all cookies to a string and read them back. This is useful to
store cookies in between sessions (on disk, for instance).
decode_cookies
will throw an error upon parse failures.
Also note, decode_cookies
will clear out any previously
learned cookies from the Session
object, unless no_clear
is given and true.
Request
get_url(URL
url
, void
|mapping
query_variables
)
Request
post_url(URL
url
, mapping
|string
query_variables
)
Request
put_url(URL
url
, string
file
, void
|mapping
query_variables
)
Request
delete_url(URL
url
, void
|mapping
query_variables
)
Sends a HTTP GET, POST, PUT or DELETE request to the server in the URL
and returns the created and initialized Request
object.
0 is returned upon failure.
array
(string
) get_cookies(Standards.URI
|SessionURL
for_url
, void
|bool
no_delete
)
Get the cookies that we should send to this server,
for this url. They are presented in the form suitable
for HTTP headers (as an array).
This will also take in count expiration of cookies,
and delete expired cookies from the Session
unless
no_delete
is true.
array
(string
) get_url_nice(URL
url
, mapping
query_variables
)
string
get_url_data(URL
url
, mapping
query_variables
)
array
(string
) post_url_nice(URL
url
, mapping
|string
query_variables
)
string
post_url_data(URL
url
, mapping
|string
query_variables
)
Returns an array of ({content_type,data})
and
just the data string respective,
after calling the requested server for the information.
0
is returned upon failure.
post* is similar to the get_url()
class of functions,
except that the query variables is sent as a POST request instead
of as a GET.
Query
give_me_connection(Standards.URI
url
)
Request a Query
object suitable to use for the
given URL. This may be a reused object from a keep-alive
connection.
void
return_connection(Standards.URI
url
, Query
query
)
Return a previously used Query object to the keep-alive storage. This function will determine if the given object is suitable to keep or not by checking status and headers.
void
set_cookie(Cookie
cookie
, Standards.URI
|zero
who
)
Set a cookie.
The cookie will be checked against current security levels et al,
using the parameter who
.
If who
is zero, no security checks will be performed.
void
set_http_cookie(string
cookie
, Standards.URI
at
)
Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.
Request
Query
Protocols.HTTP.Session.Request.con
Raw connection object
function
(string
, Standards.URI
:mixed
|void
) Protocols.HTTP.Session.Request.cookie_encountered
Cookie callback. When a request is performed,
the result is checked for cookie changes and
additions. If a cookie is encountered, this
function is called. Default is to call
set_http_cookie
in the Session
object.
int
Protocols.HTTP.Session.Request.follow_redirects
Number of redirects to follow;
the request will perform another request if the
HTTP answer is a 3xx redirect.
Default from the parent Session.follow_redirects
.
A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.
Loops will currently not be detected, only the limit works to stop loops.
Standards.URI
Protocols.HTTP.Session.Request.url_requested
URL requested (set by prepare_method). This will update according to followed redirects.
protected
void
_destruct()
_destruct
is called when an object is destructed.
void
destroy()
But since this clears the HTTP connection from the Request object,
it can also be used to reuse a Request
object.
Request
do_async(array
(string
|int
|mapping
) args
)
Start a request asyncroneously. It will perform in
the background using callbacks (make sure the backend
thread is free).
Call set_callbacks
to setup the callbacks.
Get arguments from prepare_method
.
The called object.
set_callbacks
, prepare_method
, do_sync
, do_thread
Request
|zero
do_sync(array
(string
|int
|mapping
) args
)
Perform a request synchronously.
Get arguments from prepare_method
.
0 upon failure, this object upon success
prepare_method
, do_async
, do_thread
Request
do_thread(array
(string
|int
|mapping
) args
)
Start a request in the background, using a thread.
Call wait
to wait for the thread to finish.
Get arguments from prepare_method
.
The called object.
prepare_method
, do_sync
, do_async
, wait
do_thread
does not rerun redirections automatically
array
(string
|int
|mapping
) prepare_method(string
method
, URL
url
, void
|mapping
query_variables
, void
|mapping
extra_headers
, void
|string
data
)
Prepares the HTTP Query object for the connection,
and returns the parameters to use with do_sync
,
do_async
or do_thread
.
This method will also use cookie information from the
parent Session
, and may reuse connections (keep-alive).
void
set_callbacks(function
(mixed
... :mixed
)|zero
headers
, function
(mixed
... :mixed
)|zero
data
, function
(mixed
... :mixed
)|zero
fail
, mixed
... callback_arguments
)
Setup callbacks for async mode,
headers
will be called when the request got connected,
and got data headers; data
will be called when the request
got the amount of data it's supposed to get and fail
is
called whenever the request failed.
Note here that an error message from the server isn't considered a failure, only a failed TCP connection.
Request
|zero
wait()
Wait for the request thread to finish.
0 upon failure, or the called object upon success.
do_thread
Class to store URL+referer
inherit Standards.URI : URI
URL
Protocols.HTTP.Session.SessionURL.referer
the referer to this URL
Protocols.HTTP.Session.SessionURL Protocols.HTTP.Session.SessionURL(
URL
uri
, URL
base_uri
, URL
_referer
)
instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables
This module contains various HTTP Authentication implementations for
both server and client use. A Client implementation would
typically call the make_authenticator
method with the incoming
WWW-Authenticate header to get a Client
object. For each HTTP
request the auth() method of the object can be called to get an
appropriate Authorization header.
Server code should create an authentication class and inherit the
concrete authentication scheme implementation. To add an actual
user lookup, overload get_password
or
get_hashed_password
. Hashed passwords must be hashed with the
scheme appropriate digest.
class Auth { inherit Protocols.HTTP.Authentication.DigestMD5Server; Concurrent.Future get_password(string user) { Promise p = Concurrent.Promise(); if( user == "bob" ) return p->success("builder"); return p->failure(sprintf("No user %O", user)); } }
Auth auth = Auth("apps@pike.org"); Concurrent.Future authenticate(Protocols.HTTP.Server.Request req) { Concurrent.Future authenticated = Concurrent.Promise(); auth->auth(req->request_headers->authorization, req->request_method, request->not_query) ->then(lambda(string user) { authenticated->success(user); }, lambda(string reason) { authenticated->failure(reason); string c = auth->challenge(); request->response_and_finish( ([ "error":401, "extra_heads" : ([ "WWW-Authenticate":c, ]) ]) ); }); return authenticated; }
Client
make_authenticator(string
|array
(string
) hdrs
, string
user
, string
password
, void
|string
realm
)
Create an authenticator for a server responding with the given HTTP authentication header. Currently only works for one realm.
hdrs
The WWW-Authenticate HTTP header or headers.
user
The username to use.
password
The plaintext password.
realm
Optionally the realm the user and password is valid in. If omitted, the authentication will happen in whatever realm the server is presenting.
mapping
(string
:string
) split_header(string
hdr
)
Split client generated Authorization header into its parts.
HTTP Basic authentication client.
Abstract Client class.
Abstract HTTP Digest authentication client.
inherit Digest : Digest
HTTP Digest authentication client using MD5.
inherit DigestClient : DigestClient
inherit DigestMD5 : DigestMD5
HTTP Digest server implementation using MD5.
inherit DigestMD5 : DigestMD5
inherit DigestServer : DigestServer
Implements the session version "MD5-sess" of the MD5 HTTP Digest
authentication. Used identically to DigestMD5Server
.
inherit DigestMD5Server : DigestMD5Server
HTTP Digest authentication client using SHA256.
inherit DigestClient : DigestClient
inherit DigestSHA256 : DigestSHA256
HTTP Digest server implementation using SHA256.
inherit DigestSHA256 : DigestSHA256
inherit DigestServer : DigestServer
Implements the session version "SHA256-sess" of the SHA256 HTTP
Digest authentication. Used identically to DigestSHA256Server
.
inherit DigestSHA256Server : DigestSHA256Server
HTTP Digest authentication client using SHA512/256.
inherit DigestClient : DigestClient
inherit DigestSHA512256 : DigestSHA512256
HTTP Digest server implementation using SHA512/256.
inherit DigestSHA512256 : DigestSHA512256
inherit DigestServer : DigestServer
Implements the session version "SHA-512-256-sess" of the SHA512/256 HTTP
Digest authentication. Used identically to DigestSHA512256Server
.
inherit DigestSHA512256Server : DigestSHA512256Server
Abstract HTTP Digest implementation.
inherit Digest : Digest
string
Protocols.HTTP.Authentication.DigestServer.realm
The current realm of the authentication.
Concurrent.Future
auth(string
hdr
, string
method
, string
path
)
Authenticate a request.
hdr
The value of the Authorization header. Zero is acceptable, but will produce an unconditional rejection.
method
This is the HTTP method used, typically "GET" or "POST".
path
This is the path of the request.
string(7bit)
challenge()
Creates a challenge header value for the WWW-Authenticate header in 401 responses.
Protocols.HTTP.Authentication.DigestServer Protocols.HTTP.Authentication.DigestServer(
void
|string(8bit)
realm
, void
|string(8bit)
key
)
realm
The realm to be authenticated.
key
If this key is set all challanges are verified against signature using this key. The key can be any 8-bit string, but should be the same across multiple instances on the same domain, and over time.
Concurrent.Future
get_hashed_password(string
user
)
Function intended to be overloaded that returns a future that
will resolved to the given users hashed password. Overloading
this function will prevent get_password
from being called.
Concurrent.Future
get_password(string
user
)
Function intended to be overloaded that returns a future that will resolve to the given users password.
get_hashed_password
This HTTP client module utilises the Concurrent.Promise
and
Concurrent.Future
classes and only does asynchronous calls.
Protocols.HTTP.Promise.Arguments a1, a2; a1 = Protocols.HTTP.Promise.Arguments(([ "extra_args" : ({ "Extra arg for Roxen request" }), "headers" : ([ "User-Agent" : "My Special HTTP Client" ]) ])); a2 = Protocols.HTTP.Promise.Arguments(([ "variables" : ([ "q" : "Pike programming language" ]), "maxtime" : 10 ])); Concurrent.Future q1 = Protocols.HTTP.Promise.get_url("http://www.roxen.com", a1); Concurrent.Future q2 = Protocols.HTTP.Promise.get_url("http://www.google.com", a2); array(Concurrent.Future) all = ({ q1, q2 }); /* To get a callback for each of the requests */ all->on_success(lambda (Protocols.HTTP.Promise.Result ok_resp) { werror("Got successful response for %O\n", ok_resp->host); }); all->on_failure(lambda (Protocols.HTTP.Promise.Result failed_resp) { werror("Request for %O failed!\n", failed_resp->host); }); /* To get a callback when all of the requests are done. In this case on_failure will be called if any of the request fails. */ Concurrent.Future all2 = Concurrent.results(all); all2->on_success(lambda (array(Protocols.HTTP.Promise.Result) ok_resp) { werror("All request were successful: %O\n", ok_resp); }); all->on_failure(lambda (Protocols.HTTP.Promise.Result failed_resp) { werror("The request to %O failed.\n", failed_resp->host); });
Concurrent.Future
get_url(Protocols.HTTP.Session.URL
url
, void
|Arguments
args
)
Concurrent.Future
post_url(Protocols.HTTP.Session.URL
url
, void
|Arguments
args
)
Concurrent.Future
put_url(Protocols.HTTP.Session.URL
url
, void
|Arguments
args
)
Concurrent.Future
delete_url(Protocols.HTTP.Session.URL
url
, void
|Arguments
args
)
Sends a GET, POST, PUT or DELETE request to url
asynchronously. A Concurrent.Future
object is returned on which you
can register callbacks via Concurrent.Future->on_success()
and
Concurrent.Future.on_failure()
which will get a Result
object as argument.
For an example of usage see Protocols.HTTP.Promise
Concurrent.Future
do_method(string
http_method
, Protocols.HTTP.Session.URL
url
, void
|Arguments
args
)
Fetch an URL with the http_method
method.
void
set_timeout(int
t
)
void
set_maxtime(int
t
)
set_timeout()
sets the default timeout for connecting and data fetching.
The watchdog will be reset each time data is fetched.
set_maxtime()
sets the timeout for the entire operation. If this is set
to 30 seconds for instance, the request will be aborted after
30 seconds event if data is still being received. By default this is
indefinitely.
t
is the timeout in seconds.
Arguments
Class representing the arguments to give to get_url()
, post_url()
put_url()
, delete_url()
and do_method()
.
void
|string
|mapping
Protocols.HTTP.Promise.Arguments.data
POST data
array
(mixed
) Protocols.HTTP.Promise.Arguments.extra_args
Extra arguments that will end up in the Result
object
bool
Protocols.HTTP.Promise.Arguments.follow_redirects
Should redirects be followed. Default is true.
mapping
(string
:string
) Protocols.HTTP.Promise.Arguments.headers
Additional request headers
int
Protocols.HTTP.Promise.Arguments.maxtime
Request timeout
int
Protocols.HTTP.Promise.Arguments.timeout
Data fetch timeout
mapping
(string
:mixed
) Protocols.HTTP.Promise.Arguments.variables
Query variables
Protocols.HTTP.Promise.Arguments Protocols.HTTP.Promise.Arguments(
void
|mapping
(string
:mixed
) args
)
If args
is given the indices that match any of this object's
members will set those object members to the value of the
corresponding mapping member.
HTTP result class.
A class representing a request and its response. An instance of
this class will be given as argument to the
Concurrent.Future()->on_success()
and
Concurrent.Future()->on_failure()
callbacks registered on the returned
Concurrent.Future
object from get_url()
, post_url()
,
delete_url()
, put_url()
or do_method()
.
string
|zero
Protocols.HTTP.Promise.Result.charset
Returns the charset of the requested document, if given by the response headers.
Read only
string
Protocols.HTTP.Promise.Result.content_encoding
Returns the content encoding of the response if set by the remote server.
Read only
string
Protocols.HTTP.Promise.Result.content_type
Returns the content type of the requested document
Read only
string
Protocols.HTTP.Promise.Result.data
Raw data body of the request
get()
array
(mixed
) Protocols.HTTP.Promise.Result.extra_args
Extra arguments set in the Arguments
object.
mapping
Protocols.HTTP.Promise.Result.headers
The HTTP response headers
string
Protocols.HTTP.Promise.Result.host
The host that was called in the request
int
Protocols.HTTP.Promise.Result.length
Returns the value of the content-length header.
Read only
int
Protocols.HTTP.Promise.Result.status
The HTTP status of the response, e.g 200, 201, 404 and so on.
string
Protocols.HTTP.Promise.Result.status_description
The textual representation of status
.
Standards.URI
Protocols.HTTP.Promise.Result.url
Returns the requested URL
string
get()
The response body, i.e the content of the requested URL
Internal class for the actual HTTP requests
inherit Protocols.HTTP.Session : parent
constant
Protocols.HTTP.Server.HeaderParser
Fast HTTP header parser.
constant
Protocols.HTTP.Server.http_decode_string
string
extension_to_type(string
extension
)
Looks up the file extension in a table to return a suitable MIME type.
string
filename_to_extension(string
filename
)
Determine the extension for a given filename.
string
filename_to_type(string
filename
)
Looks up the file extension in a table to return a suitable MIME type.
string
http_date(int
time
)
Makes a time notification suitable for the HTTP protocol.
time
The time in seconds since the 00:00:00 UTC, January 1, 1970
The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT
int
http_decode_date(string
data
)
Decode a HTTP date to seconds since 1970 (UTC)
zero (UNDEFINED) if the given string isn't a HTTP date
mapping
(string
:string
|array
(string
)) http_decode_urlencoded_query(string
query
, void
|mapping
dest
)
Decodes an URL-encoded query into a mapping.
The simplest server possible. Binds a port and calls
a callback with request_program
objects.
object
|function
(:void
)|program
Protocols.HTTP.Server.Port.request_program
void
close()
Closes the HTTP port.
Protocols.HTTP.Server.Port Protocols.HTTP.Server.Port(
function
(.Request
:void
) callback
, void
|int
portno
, void
|string
interface
, void
|int
reuse_port
)
This class represents a connection from a client to the server.
There are three different read callbacks that can be active, which
have the following call graphs. read_cb
is the default read
callback, installed by attach_fd
.
| (Incoming data)
v
read_cb
| If complete headers are read
v
parse_request
v
parse_variables
| If callback isn't changed to read_cb_chunked or read_cb_post
v
finalize
| (Incoming data)
v
read_cb_post
| If enough data has been received
v
finalize
| (Incoming data)
v
read_cb_chunked
| If all data chunked transfer-encoding needs
v
finalize
string
Protocols.HTTP.Server.Request.body_raw
raw unparsed body of the request (raw
minus request line and headers)
int
Protocols.HTTP.Server.Request.connection_timeout_delay
connection timeout, delay until connection is closed while waiting for the correct headers:
mapping
(string
:string
) Protocols.HTTP.Server.Request.cookies
cookies set by client
string
Protocols.HTTP.Server.Request.full_query
full resource requested, including attached GET query
mapping
Protocols.HTTP.Server.Request.misc
external use only
Stdio.NonblockingStream
Protocols.HTTP.Server.Request.my_fd
The socket that this request came in on.
string
Protocols.HTTP.Server.Request.not_query
resource requested minus any attached query
string
Protocols.HTTP.Server.Request.protocol
request protocol and version, eg. HTTP/1.0
string
Protocols.HTTP.Server.Request.query
query portion of requested resource, starting after the first "?"
string
Protocols.HTTP.Server.Request.raw
raw unparsed full request (headers and body)
mapping
(string
:string
|array
(string
)) Protocols.HTTP.Server.Request.request_headers
all headers included as part of the HTTP request, ie content-type.
string
Protocols.HTTP.Server.Request.request_raw
full request line (request_type
+ full_query
+ protocol
)
string
Protocols.HTTP.Server.Request.request_type
HTTP request method, eg. POST, GET, etc.
mapping
Protocols.HTTP.Server.Request.response
the response sent to the client (for use in the log_cb)
int
Protocols.HTTP.Server.Request.send_timeout_delay
send timeout (no activity for this period with data in send buffer) in seconds, default is 180
mapping
(string
:string
|array
(string
)) Protocols.HTTP.Server.Request.variables
all variables included as part of a GET or POST request.
void
finish(int
clean
)
Finishes this request, as in removing timeouts, calling the
logging callback etc. If clean
is given, then the processing of
this request went fine and all data was sent properly, in which
case the connection will be reused if keep-alive was
negotiated. Otherwise the connection will be closed and
destructed.
string
|zero
get_ip()
Return the IP address that originated the request, or 0 if
the IP address could not be determined. In the event of an
error, my_fd
->errno() will be set.
void
opportunistic_tls(string
s
)
Called when the client is attempting opportunistic TLS on this HTTP port. Overload to handle, i.e. send the data to a TLS port. By default the connection is simply closed.
void
response_and_finish(mapping
m
, function
(:void
)|void
_log_cb
)
return a properly formatted response to the HTTP client
m
Contains elements for generating a response to the client.
| Data to be returned to the client. Can be an array of objects which are concatenated and sent to the client. |
| File object, the contents of which will be returned to the client. |
| HTTP error code |
| length of content returned. If file is provided, size bytes will be returned to client. |
| contains optional modification date. |
| contains optional content-type |
| contains a mapping of additional headers to be returned to client. |
| contains the server identification header. |
int
sent_data()
Returns the amount of data sent.
void
set_mode(int
mode
)
mode
A number of integer flags bitwise ored together to determine
the mode of operation.
SHUFFLER
: Use the Shuffler to send out the data.
constant
Protocols.HTTP.Server.Request.READ_SIZE
constant
Protocols.HTTP.Server.Request.READ_CHUNK
constant
Protocols.HTTP.Server.Request.READ_POSTNL
constant
Protocols.HTTP.Server.Request.READ_TRAILER
constant
Protocols.HTTP.Server.Request.FINISHED
A very simple SSL server. Binds a port and calls a callback with
request_program
objects.
inherit SSL.Port : Port
object
|function
(:void
)|program
Protocols.HTTP.Server.SSLPort.request_program
Protocols.HTTP.Server.SSLPort Protocols.HTTP.Server.SSLPort(
function
(Request
:void
) callback
, int(1..)
|void
port
, void
|string
interface
, void
|string
|Crypto.Sign.State
key
, void
|string
|array
(string
) certificate
, void
|int
reuse_port
)
Create a HTTPS (HTTP over SSL) server.
callback
The function run when a request is received.
takes one argument of type Request
.
port
The port number to bind to, defaults to 443.
interface
The interface address to bind to.
key
An optional SSL secret key, provided in binary format, such
as that created by Standards.PKCS.RSA.private_key()
.
certificate
An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.
reuse_port
If true, enable SO_REUSEPORT if the OS supports it. See
Stdio.Port.bind
for more information
protected
void
new_connection()
The port accept callback
Secure Socket Layer (SSL) version 3.0 and Transport Layer Security (TLS) versions 1.0 - 1.2.
RFC 2246 (TLS 1.0): "The primary goal of the TLS Protocol is to provide privacy and data integrity between two communicating applications."
The classes that typical users need to use are
File
This is an object that attempts to behave as a Stdio.File
as much as possible.
Port
This is an object that attempts to behave as a Stdio.Port
as much as possible, with Port()->accept()
returning
File
objects.
Context
The configurated context for the File
.
Constants.CertificatePair
A class for keeping track of certificate chains and their private keys.
The Constants
module also contains lots of constants that are
used by the various APIs, as well as functions for formatting
the constants for output.
File
, Port
, Context
, Constants.CertificatePair
,
Constants
Alert packet.
inherit .Packet : Packet
Based on the base Packet
.
SSL.Alert SSL.Alert(
int(1..2)
level
, int(8bit)
description
, ProtocolVersion
version
, string
|void
message
)
String buffer with the possibility to read and write data as they would be formatted in structs.
inherit Stdio.Buffer : Buffer
this_program
add_int_array(array
(int
) data
, int(8bit)
item_size
, int(0..)
len
)
Appends an array of unsigned integers of width item_size
to the buffer, preceded with an unsigned integer len
declaring
the size of the array in bytes.
this_program
add_string_array(array
(string(8bit)
) data
, int(0..)
item_size
, int(0..)
len
)
Appends an array of variable length strings with item_size
bytes hollerith coding, prefixed by a len
bytes large integer
declaring the total size of the array in bytes.
SSL.Buffer SSL.Buffer(
void
|string(8bit)
|Stdio.Buffer
s
)
Create a new buffer, optionally initialized with the
value s
.
array
(int
) read_int_array(int(8bit)
item_size
, int(0..)
len
)
Reads an array of integers as written by add_int_array
from the buffer.
array
(string(8bit)
) read_string_array(int(0..)
item_size
, int(0..)
len
)
Reads an array of strings as written by add_string_array
from the buffer.
Client-side connection state.
inherit Connection : Connection
array
(int
)|zero
SSL.ClientConnection.client_cert_types
array
(string(8bit)
)|zero
SSL.ClientConnection.client_cert_distinguished_names
A few storage variables for client certificate handling on the client side.
SSL.ClientConnection SSL.ClientConnection(
Context
ctx
, string(8bit)
|void
server_name
, Session
|void
session
)
Initialize a new ClientConnection
.
ctx
Context
to use.
server_name
Optional host name of the server.
session
Optional Session
to resume.
int(-1..1)
handle_handshake(int
type
, Buffer
input
, Stdio.Buffer
raw
)
Do handshake processing.
type
One of HANDSHAKE_*.
input
The contents of the packet.
raw
The raw packet received (needed for supporting SSLv2 hello messages).
This function returns:
| If handshaking is in progress. |
| If handshaking has completed. |
| If a fatal error occurred. |
It uses the send_packet()
function to transmit packets.
void
send_renegotiate()
Renegotiate the connection (client initiated).
Sends a client_hello
to force a new round of handshaking.
SSL.Connection keeps the state relevant for a single SSL connection.
This includes the Context
object (which doesn't change), various
buffers, the Session
object (reused or created as appropriate),
and pending read and write states being negotiated.
Each connection will have two sets of read and write State
s: The
current read and write states used for encryption, and pending read
and write states to be taken into use when the current keyexchange
handshake is finished.
This object is also responsible for managing incoming and outgoing packets. Outgoing packets are stored in queue objects and sent in priority order.
This class should never be created directly, instead one of the
classes that inherits it should be used (ie either
ClientConnection
or ServerConnection
) depending on whether
this is to be a client-side or server-side connection. These in
turn are typically created by File()->create()
.
ClientConnection
, ServerConnection
, Context
,
Session
, File
, State
private
constantint
SSL.Connection.window_size
Number of passed sequence numbers to keep track of. RFC 4347 section 4.1.2.5: A minimum window size of 32 MUST be supported, but a window size of 64 is preferred and SHOULD be employed as the default. Another window size (larger than the minimum) MAY be chosen by the receiver.
string(8bit)
|zero
SSL.Connection.application_protocol
Selected ALPN (RFC 7301) protocol (if any).
Note that this is a connection property, and needs to be renegotiated on session resumption.
string(8bit)
|zero
SSL.Connection.client_random
string(8bit)
|zero
SSL.Connection.server_random
Random cookies, sent and received with the hello-messages.
.Cipher.KeyExchange
|zero
SSL.Connection.ke
The active Cipher.KeyExchange
(if any).
int
|zero
SSL.Connection.sent
Number of application data bytes sent by us.
private
int
SSL.Connection.sequence_mask
Bitmask representing sequence numbers for accepted
received packets in the interval
[next_seq_num-window_size
..next_seq_num-2
].
The packet with seqence number next_seq_num-1
is
implicitly known to have been received.
ConnectionState
SSL.Connection.state
Bitfield with the current connection state.
SSL.Connection SSL.Connection(
Context
ctx
)
Initialize the connection state.
ctx
The context for the connection.
void
derive_master_secret(string(8bit)
premaster_secret
)
Derive the master secret from the premaster_secret and the random seeds, and configure the keys.
string
describe_state()
Returns a string describing the current connection state.
string(8bit)
|int(-1..1)
got_data(string(8bit)
data
)
Main receive handler.
data
String of data received from the peer.
Returns one of:
| Returns an empty string if there's neither application data nor errors (eg during the initial handshake). |
| Returns a string of received application data. |
| Returns |
| Returns These are the main cases of errors:
|
This function is intended to be called from an i/o read callback.
int(-1..1)
handle_alert(int
level
, int
description
)
Handle an alert received from the peer.
level
Alert level; either ALERT_warning
or ALERT_fatal
.
description
Alert description code; one of
indices(SSL.Constants.ALERT_descriptions)
.
| A Fatal error occurred and processing should stop. |
| Processing can continue. |
| Connection should close. |
int(-1..1)
handle_handshake(int
type
, Buffer
input
, Stdio.Buffer
raw
)
Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).
This function returns 0 if handshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.
void
mark_seq_num(int
num
)
Mark seqence number num
as seen and accepted.
This will cause valid_seq_nump()
to return 0
for it
if it shows up again.
void
new_cipher_states()
Generate new pending cipher states.
int
query_write_queue_size()
Returns the number of packets queued for writing.
Returns the number of times to_write()
can be called before
it stops returning non-empty strings.
protected
Packet
|zero
recv_packet()
Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.
void
send_close()
Initiate close.
void
send_packet(Packet
packet
, int
|void
priority
)
Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.
void
send_renegotiate()
Renegotiate the connection.
int
send_streaming_data(string(8bit)
data
)
Send an application data packet. If the data block is too large then as much as possible of the beginning of it is sent. The size of the sent data is returned.
void
set_alert_callback(function
(object
, int
|object
, string
:void
) callback
)
Called with alert object, sequence number of bad packet, and raw data as arguments, if a bad packet is received.
Can be used to support a fallback redirect https->http.
void
shutdown()
Remove cyclic references as best we can.
int(-1..2)
to_write(Stdio.Buffer
output
)
Extracts data from the packet queues. Returns 2 if data has been written, 0 if there are no pending packets, 1 of the connection is being closed politely, and -1 if the connection died unexpectedly.
This function is intended to be called from an i/o write callback.
query_write_queue_size()
, send_streaming_data()
.
int
valid_seq_nump(int
num
)
Check whether num
is a valid seqence number for a new packet.
int
SSL.Connection.HandshakeFragment.mt
int
SSL.Connection.HandshakeFragment.len
int
SSL.Connection.HandshakeFragment.offset
string(8bit)
SSL.Connection.HandshakeFragment.data
protected
local
void
__create__(int
mt
, int
len
, int
offset
, string(8bit)
data
)
SSL.Connection.HandshakeFragment SSL.Connection.HandshakeFragment(
int
mt
, int
len
, int
offset
, string(8bit)
data
)
Keeps the state that is shared by all SSL-connections on a client, or for one port on a server. It includes policy configuration, the server or client certificate(s), the corresponding private key(s), etc. It also includes the session cache.
The defaults are usually suitable for a client, but for a server some configuration is necessary.
Typical use is to:
Call add_cert()
with the certificates belonging to the server
or client. Note that clients often don't have or need any
certificates, and also that certificate-less server operation is
possible, albeit discouraged and not enabled by default.
Suitable self-signed certificates can be created with
Standards.X509.make_selfsigned_certificate()
.
Optionally call get_suites()
to get a set of cipher_suites
to assign to preferred_suites
. This is only needed if the
default set of suites from get_suites(128, 1)
isn't
satisfactory.
The initialized Context
object is then passed to
File()->create()
or used as is embedded in Port
.
File
, Port
, Standards.X509
array
(string(8bit)
)|zero
SSL.Context.advertised_protocols
List of advertised protocols using using TLS application level protocol negotiation.
int
SSL.Context.auth_level
Policy for client authentication. One of
SSL.Constants.AUTHLEVEL_none
,
SSL.Constants.AUTHLEVEL_verify
, SSL.Constants.AUTHLEVEL_ask
and SSL.Constants.AUTHLEVEL_require
.
Defaults to SSL.Constants.AUTHLEVEL_none.
array
(int
) SSL.Context.client_auth_methods
The possible client authentication methods. Used only if
auth_level is AUTH_ask or AUTH_require. Generated by
set_authorities
.
array
(int
) SSL.Context.ecc_curves
Supported elliptical curve cipher curves in order of preference. Defaults to all supported curves, ordered with the largest curves first.
bool
SSL.Context.enable_renegotiation
If set enable SSL/TLS protocol renegotiation.
Defaults to 1
(enabled).
RFC 7540 section 9.2.1 requires this to be turned off after
Protocols.HTTP2
communication has started.
bool
SSL.Context.encrypt_then_mac
Attempt to enable encrypt-then-mac mode. Defaults to 1
.
Replaced by extensions
.
multiset
(int
) SSL.Context.extensions
A list of all extensions that will be considered in the handshake process. Extensions not listed will not be sent, and will be ignored if received.
The following values are included by default.
| Protection against renegotiation attack (RFC 5746). |
| Allows negotiation of the maximum fragment size (RFC 6066 section 4). |
| Attempts to address attacks against block ciphers (RFC 7366). |
| Required to support more than one protocol on the same TLS port (RFC 7639). |
| Required to select which out of several certificates to use (RFC 5246 section 7.4.1.4.1). |
| Required for elliptic curve key exchange (RFC 4492 section 5.1.2). |
| Required for elliptic curve key exchange (RFC 4492 section 5.1.1). |
| Allows the client to select which of several domains hosted on the same server it wants to connect to. Required by many websites (RFC 6066 section 3). |
| Support session resumption without server-side state (RFC 4507 and RFC 5077). |
| Not supported by Pike. The server side will just check that the client packets are correctly formatted. |
| Not supported by Pike. The server side will just check that the client packets are correctly formatted. |
| Needed for TLS 1.3 0-RTT handshake. EXPERIMENTAL. |
| This extension is required to avoid a bug in some f5 SSL terminators for certain sizes of client handshake messages. |
The following supported values are not included by default.
| This extension allows for the HMAC to be truncated for a small win in payload size. Not widely implemented and may be a security risk (RFC 6066 section 7). |
| This extension allows the client and server to send heartbeats
over the connection. Intended to keep TCP connections
alive. Required to be set to use |
| Binds the master secret to important session parameters to protect against man in the middle attacks (RFC 7627). |
array
(int
) SSL.Context.ffdhe_groups
Supported FFDHE groups for DHE key exchanges, in order of preference, most preferred first.
Defaults to the full set of supported FFDHE groups from the FFDHE draft, in order of size with the smallest group (2048 bits) first.
Server-side the first group in the list that satisfies the NIST guide lines for key strength (NIST SP800-57 5.6.1) (if any) for the selected cipher suite will be selected, and otherwise the largest group.
Client-side the list will be reversed (as a precaution if the server actually follows the clients preferences).
bool
SSL.Context.heartbleed_probe
If set, the other peer will be probed for the heartbleed bug
during handshake. If heartbleed is found the connection is closed
with insufficient security fatal error. Requires
Constants.EXTENSION_heartbeat
to be set in extensions
.
int
SSL.Context.max_sessions
Maximum number of sessions to keep in the cache.
int
SSL.Context.min_version
int
SSL.Context.max_version
The accepted range of versions for the client/server. List
specific versions in supported_versions
instead.
Replaced by supported_versions
.
int
SSL.Context.packet_max_size
The maximum amount of data that is sent in each SSL packet by
File
. A value between 1 and Constants.PACKET_MAX_SIZE
.
array
(int
) SSL.Context.preferred_compressors
Lists the supported compression algorithms in order of preference.
Defaults to ({ COMPRESSION_null })
due to SSL attacks that
target compression.
array
(int
)|zero
SSL.Context.preferred_suites
Cipher suites we want to support, in order of preference, best first. By default set to all suites with at least 128 bits cipher key length, excluding RC4, and ephemeral and non-ephemeral certificate based key exchange.
mapping
(int(508..511)
:Crypto.DH.Parameters
) SSL.Context.private_ffdhe_groups
DHE parameter lookup for the FFDHE private range.
Add any custom FFDHE-groups here.
Defaults to the empty mapping.
If you add any groups here, you will also need to update
ffdhe_groups
accordingly.
function
(int(0..)
:string(8bit)
) SSL.Context.random
Used to generate random cookies for the hello-message. If we use
the RSA keyexchange method, and this is a server, this random
number generator is not used for generating the master_secret. By
default set to random_string
.
int
SSL.Context.require_trust
When set, require the chain to be known, even if the root is self signed.
Note that if set, and certificates are set to be verified, trusted issuers must be provided, or no connections will be accepted.
Replaced by auth_level
.
int
SSL.Context.session_lifetime
Sessions are removed from the cache when they have been inactive more than this number of seconds. Sessions are also removed from the cache if a connection using the session dies unexpectedly.
array
(int
) SSL.Context.signature_algorithms
The set of <hash, signature> combinations to use by us.
Only used with TLS 1.2 and later.
Defaults to all combinations supported by Pike except for MD5.
This list is typically filtered by get_signature_algorithms()
to get rid of combinations not supported by the runtime.
According to RFC 5246 section 7.4.2 all certificates need to be signed by any of the supported signature algorithms. To be forward compatible this list needs to be limited to the combinations that have existing PKCS identifiers.
get_signature_algorithms()
array
(ProtocolVersion
) SSL.Context.supported_versions
List of supported versions, in order of preference. Defaults to
PROTOCOL_TLS_1_2
, PROTOCOL_TLS_1_1
and PROTOCOL_TLS_1_0
.
mapping
(string(8bit)
:array
(Standards.X509.Verifier
)) SSL.Context.trusted_issuers_cache
Mapping from DER-encoded issuer to Standards.X509.Verifier
s
compatible with eg Standards.X509.verify_certificate()
and
Standards.X509.load_authorities()
.
get_trusted_issuers()
, set_trusted_issuers()
int
SSL.Context.use_cache
Non-zero to enable caching of sessions
mapping
(Standards.ASN1.Types.Identifier
:Crypto.Hash
) SSL.Context.verifier_algorithms
Mapping of supported verifier algorithms to hash implementation.
Standards.X509.get_algorithms()
int
SSL.Context.verify_certificates
Determines whether certificates presented by the peer are verified, or just accepted as being valid.
Replaced by auth_level
.
void
add_cert(Crypto.Sign.State
key
, array
(string(8bit)
) certs
, array
(string(8bit)
)|void
extra_name_globs
)
variant
void
add_cert(string(8bit)
key
, array
(string(8bit)
) certs
, array
(string(8bit)
)|void
extra_name_globs
)
variant
void
add_cert(CertificatePair
cp
)
Add a certificate.
This function is used on both servers and clients to add
a key and chain of certificates to the set of certificate
candidates to use in find_cert()
.
On a server these are used in the normal initial handshake, while on a client they are only used if a server requests client certificate authentication.
key
Private key matching the first certificate in certs
.
Supported key types are currently:
| Rivest-Shamir-Adelman. |
| Digital Signing Algorithm. |
| Elliptic Curve Digital Signing Algorithm. |
This key MUST match the public key in the first certificate
in certs
.
certs
A chain of X509.v1 or X509.v3 certificates, with the local certificate first and root-most certificate last.
extra_name_globs
Further SNI globs (than the ones in the first certificate), that
this certificate should be selected for. Typically used to set
the default certificate(s) by specifying ({ "*" })
.
The SNI globs are only relevant for server-side certificates.
cp
An alternative is to send an initialized CertificatePair
.
The function performs various validations of the key
and certs
, and throws errors if the validation fails.
find_cert()
Alert
alert_factory(SSL.Connection
con
, int
level
, int
description
, ProtocolVersion
version
, string
|void
message
, mixed
|void
trace
)
Alert factory.
This function may be overloaded to eg obtain logging of generated alerts.
con
Connection which caused the alert.
level
Level of alert.
description
Description code for the alert.
message
Optional log message for the alert.
Not all alerts are fatal, and some (eg ALERT_close_notify
) are used
during normal operation.
void
configure_suite_b(int(128..)
|void
min_keylength
, int(0..)
|void
strictness_level
)
Configure the context for Suite B compliant operation.
This restricts the context to the cipher suites specified by RFC 6460 in strict mode.
Additional suites may be enabled, but they will only be selected if a Suite B suite isn't available.
min_keylength
Minimum supported key length in bits. Either 128
or 192
.
strictness_level
Allow additional suites.
| Strict mode. Allow only the Suite B suites from RFC 6460 and TLS 1.2. |
| Transitional mode. Also allow the transitional suites from RFC 5430 for use with TLS 1.0 and 1.1. |
| Permissive mode (default). Also allow other suites that conform to the minimum key length. |
This function is only present when Suite B compliant operation is possible (ie both elliptic curves and GCM are available).
Note also that for Suite B server operation compliant certificates
need to be added with add_cert()
.
get_suites()
Session
|zero
decode_ticket(string(8bit)
ticket
)
Decode a session ticket and return the corresponding session if valid or zero if invalid.
The default implementation just calls lookup_session()
.
Override this function (and encode_ticket()
) to implement
server-side state-less session resumption.
encode_ticket()
, lookup_session()
array
(string(8bit)
|int
)|zero
encode_ticket(Session
session
)
Generate a session ticket for a session.
The default implementation just generates a random ticket
and calls record_session()
to store it.
Over-ride this function (and decode_ticket()
) to implement
server-side state-less session resumption.
Array | |
| Non-empty string with the ticket. |
| Lifetime hint for the ticket. |
If the context signals that it does offer tickets via
offers_tickets()
, this function must offer an encoded ticket
for the session as the connection may have signalled to the client
that a ticket will be offered. However, tickets are not guaranteed
to be actually usable, so if you cannot offer a ticket when you must,
"INVALID"
might be an option...
decode_ticket()
, record_session()
, RFC 4507 section 3.3
void
filter_weak_suites(int
min_keylength
)
Filter cipher suites from preferred_suites
that don't have a
key with an effective length of at least min_keylength
bits.
array
(CertificatePair
)|zero
find_cert_domain(string(8bit)
domain
)
Look up a suitable set of certificates for the specified domain.
UNDEFINED
if no certificate was found. Called only by the
Server.
array
(CertificatePair
)|zero
find_cert_issuer(array
(string
) ders
)
Look up a suitable set of certificates for the specified issuer.
UNDEFIEND
if no certificate was found. Called only by the
ClientConnection as a response to a certificate request.
array
(string
) get_authorities()
Get the list of allowed authorities. See set_authorities
.
array
(CertificatePair
) get_certificates()
Returns a list of all server certificates added with add_cert
.
Crypto.RSA
get_export_rsa_key()
Called by the KeyExchangeExportRSA during KE_rsa_export key exchanges to get the weak RSA key. By default a new 512 bit key is generated for each key exchange. This method can be overloaded to provide caching or alternative means to generate keys.
optional
string(8bit)
get_psk(string(8bit)
id
)
A context created for PSK use must implement a get_psk method, which will be called with the key id, and should return the key to be used for the connection. If the id is not valid, 0 should be returned.
optional
string(8bit)
get_psk_hint()
A context created for server side PSK use can optionally implement get_psk_hint to return a hint string to be sent to the client. If not implemented, or returning 0, no PSK hint will be sent.
optional
string(8bit)
get_psk_id(string(8bit)
hint
)
A context created for client side PSK use must implement a get_psk_id method, which will be called with the server provided hint, or 0 if no hint was sent. Note that while there is an API difference between no hint and a zero length hint, some PSK modes are unable to send no hints.
The method should return a key id for the PSK, which will be sent to the server. If the hint is not valid, 0 should be returned.
array
(int
) get_signature_algorithms(array
(int
)|void
signature_algorithms
)
Get the (filtered) set of locally supported signature algorithms.
signature_algorithms
array
(int
) get_suites(int(-1..)
|void
min_keylength
, int(0..2)
|void
ke_mode
, multiset
(int
)|void
blacklisted_ciphers
, multiset
(KeyExchangeType
)|void
blacklisted_kes
, multiset
(HashAlgorithm
)|void
blacklisted_hashes
, multiset
(CipherModes
)|void
blacklisted_ciphermodes
)
Get the prioritized list of supported cipher suites that satisfy the requirements.
min_keylength
Minimum supported effective keylength in bits. Defaults to 128
.
Specify -1
to enable null ciphers.
ke_mode
Level of protection for the key exchange.
| Require forward secrecy (ephemeral keys). |
| Also allow certificate based key exchanges. |
| Also allow anonymous server key exchange. Note that this allows for man in the middle attacks. |
blacklisted_ciphers
Multiset of ciphers that are NOT to be used. By default RC4, DES and export ciphers are blacklisted. An empty multiset needs to be given to unlock these.
blacklisted_kes
Multiset of key exchange methods that are NOT to be used.
blacklisted_hashes
Multiset of hash algoriths that are NOT to be used.
blacklisted_ciphermodes
Multiset of cipher modes that are NOT to be used.
The list of suites is also filtered on the current settings of
supported_versions
.
Note that the effective keylength may differ from the actual keylength for old ciphers where there are known attacks.
array
(array
(string(8bit)
)) get_trusted_issuers()
Get the list of trusted issuers. See set_trusted_issuers
.
array
(ProtocolVersion
) get_versions(ProtocolVersion
client
)
Returns a list of possible versions to use, given the version in the client hello header.
Session
|zero
lookup_session(string
id
)
Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.
Session
new_session()
Create a new session.
bool
offers_tickets()
Signals if the context will offer a session ticket via
encode_ticket()
.
void
purge_session(Session
s
)
Invalidate a session for resumption and remove it from the cache.
void
record_session(Session
s
)
Add a session to the cache (if caching is enabled).
void
set_authorities(array
(string
) a
)
Array of authorities that are accepted for client certificates.
The server will only accept connections from clients whose
certificate is signed by one of these authorities. The string is a
DER-encoded certificate, which typically must be decoded using
MIME.decode_base64
or Standards.PEM.Messages
first.
Note that it is presumed that the issuer will also be trusted by
the server. See trusted_issuers
for details on specifying
trusted issuers.
If empty, the server will accept any client certificate whose issuer is trusted by the server.
void
set_trusted_issuers(array
(array
(string(8bit)
)) issuers
)
Sets the list of trusted certificate issuers.
issuers
An array of certificate chains whose root is self signed (ie a
root issuer), and whose final certificate is an issuer that we
trust. The root of the certificate should be first certificate in
the chain. The string is a DER-encoded certificate, which
typically must be decoded using MIME.decode_base64
or
Standards.PEM.Messages
first.
If this array is left empty, and the context is set to verify certificates, a certificate chain must have a root that is self signed.
array
(int
) sort_suites(array
(int
) suites
)
Sort a set of cipher suites according to our preferences.
Returns the array sorted with the most preferrable (aka "best") cipher suite first.
The original array (suites
) is modified destructively,
but is not the same array as the result.
Interface similar to Stdio.File
.
Handles blocking and nonblocking mode.
Handles callback mode in an arbitrary backend (also in blocking mode).
Read and write operations may each do both reading and writing. In callback mode that means that installing either a read or a write callback may install both internally.
In Pike 8.0 and later, blocking read and write in concurrent threads is supported.
Callback changing operations like set_blocking
and
set_nonblocking
aren't atomic.
Apart from the above, thread safety/atomicity characteristics are retained.
Blocking characterstics are retained for all functions.
is_open
, connection init (create
) and close (close
) can
do both reading and writing.
_destruct
attempts to close the stream properly by sending the
close packet, but since it can't do blocking I/O it's not
certain that it will succeed. The stream should therefore always
be closed with an explicit close
call.
Abrupt remote close without the proper handshake gets the errno
System.EPIPE
.
Objects do not contain cyclic references, so they are closed and destructed timely when dropped.
string
SSL.File.application_protocol
The application protocol chosen by the client during application layer protocol negotiation (ALPN).
Read only
protected
int
SSL.File.fragment_max_size
The max amount of data to send in each packet. Initialized from the context when the object is created.
protected
void
_destruct()
Try to close down the connection properly since it's customary to
close files just by dropping them. No guarantee can be made that
the close packet gets sent successfully though, because we can't
risk blocking I/O here. You should call close
explicitly.
close
bool
accept(string
|void
pending_data
)
Configure as server and set up the connection.
pending_data
Any data that has already been read from the stream. This is typically used with protocols that use START TLS or similar, where there's a risk that "too much" data (ie part of the TLS ClientHello) has been read from the stream before deciding that the connection is to enter TLS-mode.
Returns 0
on handshaking failure in blocking mode,
and otherwise 1
.
connect()
protected
int(0)
|float
backend_once(int
|void
nonwaiting_mode
)
Run one pass of the backend.
int
close(void
|string
how
, void
|int
clean_close
, void
|int
dont_throw
)
Close the connection. Both the read and write ends are always closed
how
This argument is only for Stdio.File
compatibility
and must be either "rw"
or 0
.
clean_close
If set then close messages are exchanged to shut down the SSL connection but not the underlying stream. It may then continue to be used for other communication afterwards. The default is to send a close message and then close the stream without waiting for a response.
dont_throw
I/O errors are normally thrown, but that can be turned off with
dont_throw
. In that case errno
is set instead and 0
is
returned. 1
is always returned otherwise. It's not an error to
close an already closed connection.
If a clean close is requested in nonblocking mode then the stream
is most likely not closed right away, and the backend is then
still needed for a while afterwards to exchange the close packets.
is_open
returns 2 in that time window.
I/O errors from both reading and writing might occur in blocking mode.
If a clean close is requested and data following the close message
is received at the same time, then this object will read it and
has no way to undo that. That data can be retrieved with read
afterwards.
shutdown
SSL.Session
|zero
connect(string
|void
dest_addr
, SSL.Session
|void
session
)
Configure as client and set up the connection.
dest_addr
Optional name of the server that we are connected to.
session
Session to resume (if any).
Returns 0
on handshaking failure in blocking mode,
and otherwise the Session
object for the connection.
Throws an error if a connection already has been established.
accept()
SSL.File SSL.File(
Stdio.File
stream
, SSL.Context
ctx
)
Create an SSL connection over an open stream
.
stream
Open socket or pipe to create the connection over.
ctx
The SSL context.
The backend used by stream
is taken over and restored after the
connection is closed (see close
and shutdown
). The callbacks
and id in stream
are overwritten.
The operation mode defaults to nonblocking mode.
accept()
, connect()
int
errno()
Returns the current error number for the connection. Notable values are:
| No error |
| Connection closed by other end. |
mapping
get_peer_certificate_info()
Returns peer certificate information, if any.
array
get_peer_certificates()
Returns the peer certificate chain, if any.
mixed
get_server_name()
Returns the server name indication value for the connection.
protected
void
internal_poll()
Check whether any callbacks may need to be called.
Always run via the real_backend
.
schedule_poll()
int
is_open()
Returns nonzero if the stream currently is open, zero otherwise.
This function does nonblocking I/O to check for a close packet in the input buffer.
If a clean close has been requested in nonblocking mode, then 2 is returned until the close packet exchanged has been completed.
In Pike 7.8 and earlier, this function returned zero in the case above where it now returns 2.
bool
linger(int(-1..65535)
|void
seconds
)
Set the linger time on close()
.
function
(void
|object
, void
|mixed
:int
)|zero
query_accept_callback()
Returns the current accept callback.
set_accept_callback
string
query_address(int
|void
arg
)
Returns the address and port of the connection.
See Stdio.File.query_address
for details.
Stdio.File.query_address
function
(object
, int
|object
, string
:void
)|zero
query_alert_callback()
Returns the current alert callback.
set_alert_callback
string(8bit)
query_application_protocol()
Returns the negotiated application level protocol (ALPN)
if any, and otherwise 0
(zero).
Context.advertised_protocols
Pike.Backend
query_backend()
Return the backend used for the file callbacks.
set_backend
array
(Stdio.Buffer
|int(0)
) query_buffer_mode()
Get the active input and output buffers that have been
set with set_buffer_mode()
(if any).
Returns an array with two elements:
Array | |
| The current input buffer. |
| The current output buffer. |
set_buffer_mode()
array
(function
(mixed
, void
|string
:int
)|zero
) query_callbacks()
Returns the currently set callbacks in the same order
as the arguments to set_callbacks
.
set_callbacks
, set_nonblocking
function
(void
|mixed
:int
)|zero
query_close_callback()
Returns the current close callback.
set_close_callback
, set_nonblocking
, query_callbacks
.Connection
query_connection()
Return the SSL connection object.
This returns the low-level SSL.connection
object.
SSL.Context
query_context()
Return the SSL context object.
int
query_fd()
Returns the file descriptor number associated with this object.
mixed
query_id()
Returns the currently set id.
set_id
Stdio.read_callback_t
|zero
query_read_callback()
Returns the current read callback.
set_read_callback
, set_nonblocking
, query_callbacks
Stdio.File
query_stream()
Return the underlying stream.
Avoid any temptation to do
destruct(file_obj->query_stream())
. That almost certainly
creates more problems than it solves.
You probably want to use shutdown
.
shutdown
int
query_suite()
Return the currently active cipher suite.
int(0)
|float
query_timeout()
Get the timeout for blocking operations.
set_timeout()
ProtocolVersion
query_version()
Return the currently active SSL/TLS version.
Stdio.write_callback_t
|zero
query_write_callback()
Returns the current write callback.
set_write_callback
, set_nonblocking
, query_callbacks
string
read(void
|int
length
, void
|bool
not_all
)
Read some (decrypted) data from the connection. Works like
Stdio.File.read
.
I/O errors from both reading and writing might occur in blocking mode.
write
int
renegotiate()
Renegotiate the connection by starting a new handshake. Note that the accept callback will be called again when the handshake is finished.
Returns zero if there are any I/O errors. errno()
will give the
details.
The read buffer is not cleared - a read()
afterwards will
return data from both before and after the renegotiation.
Data in the write queue in nonblocking mode is not properly
written before resetting the connection. Do a blocking
write("")
first to avoid problems with that.
protected
void
schedule_poll()
Schedule calling of any relevant callbacks the next
time the real_backend
is run.
internal_poll()
void
set_accept_callback(function
(void
|object
, void
|mixed
:int
)|zero
accept
)
Install a function that will be called when the handshake is finished and the connection is ready for use.
The callback function will be called with the File object and the
additional id arguments (set with set_id
).
Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.
set_nonblocking
, set_callbacks
,
query_accept_callback
, query_callbacks
void
set_alert_callback(function
(object
, int
|object
, string
:void
)|zero
alert
)
Install a function that will be called when an alert packet is about
to be sent. It doesn't affect the callback mode - it's called both
from backends and from within normal function calls like read
and write
.
This callback can be used to implement fallback to other protocols
when used on the server side together with shutdown()
.
This object is part of a cyclic reference whenever this is set, just like setting any other callback.
This callback is not cleared by set_blocking
, or settable
by set_callbacks
or set_nonblocking
. It is also not
part of the set returned by query_callbacks
.
query_alert_callback
void
set_backend(Pike.Backend
backend
)
Set the backend used for the file callbacks.
query_backend
void
set_blocking()
Set the stream in blocking mode. All but the alert callback are zapped.
There might be some data still waiting to be written to the stream. That will be written in the next blocking call, regardless what it is.
This function doesn't solve the case when the connection is used nonblocking in some backend thread and another thread switches it to blocking and starts using it. To solve that, put a call out in the backend from the other thread that switches it to blocking, and then wait until that call out has run.
Prior to version 7.5.12, this function didn't clear the accept callback.
set_nonblocking
, set_blocking_keep_callbacks
,
set_nonblocking_keep_callbacks
void
set_blocking_keep_callbacks()
Set blocking mode like set_blocking
, but don't alter any
callbacks.
set_blocking
, set_nonblocking
void
set_buffer_mode(Stdio.Buffer
|int(0)
in
, Stdio.Buffer
|int(0)
out
)
Toggle the file to Buffer mode.
In this mode reading and writing will be done via Buffer objects, in the directions you included buffers.
in
Input buffer. If this buffer is non-empty, its contents will be returned after any already received data.
out
Output buffer. If this buffer is non-empty, its contents will be sent after any data already queued for sending.
query_buffer_mode()
void
set_callbacks(void
|Stdio.read_callback_t
read
, void
|Stdio.write_callback_t
write
, void
|function
(mixed
:int
) close
, void
|function
(mixed
, string
:int
) read_oob
, void
|function
(mixed
:int
) write_oob
, void
|function
(void
|mixed
:int
) accept
)
Installs all the specified callbacks at once. Use UNDEFINED
to keep the current setting for a callback.
Like set_nonblocking
, the callbacks are installed atomically.
As opposed to set_nonblocking
, this function does not do
anything with the stream, and it doesn't even have to be open.
read_oob
and write_oob
are currently ignored.
set_read_callback
, set_write_callback
,
set_close_callback
, set_accept_callback
, query_callbacks
void
set_close_callback(function
(void
|mixed
:int
)|zero
close
)
Install a function to be called when the connection is closed,
either normally or due to an error (use errno
to retrieve it).
query_close_callback
, set_nonblocking
, query_callbacks
void
set_id(mixed
id
)
Set the value to be sent as the first argument to the
callbacks installed by set_callbacks
.
query_id
bool
set_nodelay(bool
|void
state
)
Controle Nagle's Algorithm (RFC 896).
void
set_nonblocking(void
|Stdio.read_callback_t
read
, void
|Stdio.write_callback_t
write
, void
|function
(void
|mixed
:int
) close
, void
|function
(void
|mixed
:int
) read_oob
, void
|function
(void
|mixed
:int
) write_oob
, void
|function
(void
|mixed
:int
) accept
)
Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.
Prior to version 7.5.12, this function didn't set the accept callback.
read_oob
and write_oob
are currently ignored.
set_callbacks
, query_callbacks
, set_nonblocking_keep_callbacks
,
set_blocking
void
set_nonblocking_keep_callbacks()
Set nonblocking mode like set_nonblocking
, but don't alter any
callbacks.
set_nonblocking
, set_blocking
, set_blocking_keep_callbacks
void
set_read_callback(Stdio.read_callback_t
|zero
read
)
Install a function to be called when data is available.
query_read_callback
, set_nonblocking
, query_callbacks
void
set_timeout(int(0)
|float
seconds
)
Set timeout for blocking operations.
seconds
Time in seconds allowed for blocking operations
before triggering a timeout. Set to 0
(zero) to disable.
By default there is no timeout.
query_timeout()
void
set_write_callback(Stdio.write_callback_t
|zero
write
)
Install a function to be called when data can be written.
query_write_callback
, set_nonblocking
, query_callbacks
Stdio.File
shutdown()
Shut down the SSL connection without sending any more packets.
If the connection is open then the underlying (still open) stream is returned.
If a nonclean (i.e. normal) close has been requested then the underlying stream is closed now if it wasn't closed already, and zero is returned.
If a clean close has been requested (see the second argument to
close
) then the behavior depends on the state of the close
packet exchange: The first shutdown
call after a successful
exchange returns the (still open) underlying stream, and later
calls return zero and clears errno
. If the exchange hasn't
finished then the stream is closed, zero is returned, and errno
will return System.EPIPE
.
close
, set_alert_callback
int
write(string
|array
(string
) data
, mixed
... args
)
Write some (unencrypted) data to the connection. Works like
Stdio.File.write
except that this function often buffers some data
internally, so there's no guarantee that all the consumed data has
been successfully written to the stream in nonblocking mode. It
keeps the internal buffering to a minimum, however.
This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.
I/O errors from both reading and writing might occur in blocking mode.
read
constant
SSL.File.ABRUPT_CLOSE
constant
SSL.File.STREAM_OPEN
constant
SSL.File.STREAM_UNINITIALIZED
constant
SSL.File.NORMAL_CLOSE
constant
SSL.File.CLEAN_CLOSE
SSL Record Layer. Handle formatting and parsing of packets.
protected
int
SSL.Packet.marginal_size
The fragment max size is 2^14 (RFC 5246 6.2.1). Compressed fragments are however allowed to be 1024 bytes over (6.2.2), and Ciphertexts 2048 bytes (6.2.3). State the additional headroom in this variable.
SSL.Packet SSL.Packet(
ProtocolVersion
version
, void
|int
extra
)
version
The version sent packets will be created for.
extra
Additional fragment size, over the 2^14 bytes for a plaintext TLS fragment.
int(-1..1)
recv(Stdio.Buffer
data
)
Receive data read from the network.
data
Raw data from the network.
Returns a 1
data if packet is complete, otherwise
0
.
If there's an error, an alert object is returned.
void
send(Stdio.Buffer
output
)
Serialize the packet for sending.
Interface similar to Stdio.Port
.
inherit Stdio.Port : socket
function
(mixed
|void
:void
) SSL.Port.accept_callback
protected
ADT.Queue
SSL.Port.accept_queue
Queue of new SSL.File
s that have been negotiated.
Context
SSL.Port.ctx
Context
to use for the connections.
The Context
is created (by calling context_factory()
)
on first access to the variable.
Read only
File
accept()
Get the next pending File
from the accept_queue
.
Returns the next pending File
if any, and 0
(zero) if
there are none.
int
bind(int
port
, function
(mixed
|void
:int
)|void
callback
, string
|void
ip
, int
|void
reuse_port
)
Bind an SSL port.
port
Port number to bind.
callback
Callback to call when an SSL connection has been negotiated.
The callback is called with the _id
as the argument.
The new SSL.File
is then typically retrieved by
calling accept()
.
If the callback
is 0
(zero), then connections
will not be accepted until the first call of accept()
,
or a callback has been installed with set_accept_callback()
.
ip
Optional IP-number to bind.
reuse_port
If true, enable SO_REUSEPORT if the OS supports it.
Returns 1
if binding of the port succeeded,
and 0
(zero) on failure.
Stdio.Port()->bind()
, File()->set_accept_callback()
,
listen_fd()
Context
context_factory()
Function called to create the Context
object for this Port
.
By overriding this function the setup of certificates, etc for the port can be delayed until the first access to the port.
Returns the Context
to be used with this Port
.
SSL.Port SSL.Port(
Context
|void
ctx
)
Create a new port for accepting SSL connections.
ctx
Context
to be used with this Port
.
If left out, it will be created on demand on first access
by calling context_factory()
.
bind()
, listen_fd()
void
finished_callback(SSL.File
f
, mixed
|void
id
)
SSL connection accept callback.
f
The File
that just finished negotiation.
This function is installed as the File
accept callback by
ssl_callback()
, and enqueues the newly negotiated File
on
the accept queue.
If there has been an accept_callback
installed by bind()
or
listen_fd()
, it will be called with all pending File
s on the
accept queue.
If there's no accept_callback
, then the File
will have to be
retrieved from the queue by calling accept()
.
int
listen_fd(int
fd
, function
(mixed
|void
:int
)|void
callback
)
Set up listening for SSL connections on an already opened fd.
fd
File descriptor to listen on.
callback
Callback to call when the SSL connection has been negotiated.
The callback is called with an File
as the first argument,
and the id for the File
as the second.
If the callback
is 0
(zero), then negotiated File
s
will be enqueued for later retrieval with accept()
.
Returns 1
if listening on the fd succeeded,
and 0
(zero) on failure.
Stdio.Port()->listen_fd()
, File()->set_accept_callback()
,
bind()
void
set_accept_callback(function
(:void
)|void
accept_callback
)
Set the accept callback.
Stdio.File
socket_accept()
Low-level accept.
Stdio.Port()->accept()
void
ssl_callback(mixed
id
)
Connection accept callback.
This function is installed as the Stdio.Port
callback, and
accepts the connection and creates a corresponding File
with
finished_callback()
as the accept callback.
If no accept_callback
has been installed via bind()
,
listen_fd()
or set_accept_callback()
, installation
of this function as the Stdio.Port
callback will be
delayed until the first call of accept()
.
bind()
, finished_callback()
, set_accept_callback()
Server-side connection state.
inherit Connection : Connection
int(-1..1)
handle_handshake(int
type
, Buffer
input
, Stdio.Buffer
raw
)
Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).
This function returns 0 if handshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.
On entry the handshake header has been removed from input
.
void
send_renegotiate()
Renegotiate the connection (server initiated).
Sends a hello_request
to force a new round of handshaking.
protected
bool
server_derive_master_secret(Buffer
data
)
Derive the new master secret from the state of ke
and
the payload data
received fron the client in its
HANDSHAKE_client_key_exchange
packet.
protected
Packet
|zero
server_key_exchange_packet()
Initialize the KeyExchange ke
, and generate a
HANDSHAKE_server_key_exchange
packet if the
key exchange needs one.
The most important information in a session object is a choice of encryption algorithms and a "master secret" created by keyexchange with a client. Each connection can either do a full key exchange to established a new session, or reuse a previously established session. That is why we have the session abstraction and the session cache. Each session is used by one or more connections, in sequence or simultaneously.
It is also possible to change to a new session in the middle of a connection.
mapping
|zero
SSL.Session.cert_data
Information about the certificate in use by the peer, such as issuing authority, and verification status.
array
(string(8bit)
)|zero
SSL.Session.certificate_chain
Our certificate chain
Cipher.CipherSpec
|zero
SSL.Session.cipher_spec
Information about the encryption method derived from the cipher_suite.
int
SSL.Session.cipher_suite
Constant defining a choice of keyexchange, encryption and mac algorithm.
int
|zero
SSL.Session.compression_algorithm
Always COMPRESSION_null.
Crypto.ECC.Curve
|zero
SSL.Session.curve
The ECC curve selected by the key exchange.
| The curve from the server certificate. |
| |
| The curve selected for the ECDHE key exchange (typically the largest curve supported by both the client and the server). |
| |
|
array
(int
) SSL.Session.ecc_curves
Supported elliptical curve cipher curves in order of preference.
int
SSL.Session.ecc_point_format
The selected elliptical curve point format.
May be -1
to indicate that there's no supported overlap
between the server and client.
int
SSL.Session.encrypt_then_mac
Negotiated encrypt-then-mac mode.
bool
SSL.Session.extended_master_secret
Indicates that the connection uses the Extended Master Secret method of deriving the master secret.
This setting is only relevant for TLS 1.2 and earlier.
array
(int
)|zero
SSL.Session.ffdhe_groups
Supported finite field diffie-hellman groups in order of preference.
| Zero indicates that none have been specified. |
| The empty array indicates that none are supported. |
| List of supported groups, with the most preferred first. |
HeartBeatModeType
SSL.Session.heartbeat_mode
Heartbeat mode.
string(8bit)
|zero
SSL.Session.identity
Identifies the session to the server
int
SSL.Session.last_activity
When this session object was used last.
string(8bit)
|zero
SSL.Session.master_secret
48 byte secret shared between the client and the server. Used for deriving the actual keys.
int
SSL.Session.max_packet_size
The max fragment size requested by the client.
array
(string(8bit)
)|zero
SSL.Session.peer_certificate_chain
The peer certificate chain
Crypto.Sign.State
|zero
SSL.Session.peer_public_key
The peer's public key (from the certificate).
Crypto.Sign.State
|zero
SSL.Session.private_key
Our private key.
string(8bit)
|zero
SSL.Session.server_name
RFC 6066 section 3.1 (SNI)
array
(int
) SSL.Session.signature_algorithms
The set of <hash, signature> combinations supported by the peer.
Only used with TLS 1.2 and later.
Defaults to the settings from RFC 5246 section 7.4.1.4.1.
string(8bit)
|zero
SSL.Session.ticket
Alternative identification of the session to the server.
int
|zero
SSL.Session.ticket_expiry_time
Expiry time for ticket
.
bool
SSL.Session.truncated_hmac
Indicates that the packet HMACs should be truncated to the first 10 bytes (80 bits). Cf RFC 3546 section 3.5.
ProtocolVersion
|zero
SSL.Session.version
Negotiated protocol version.
array
(string(8bit)
) generate_keys(string(8bit)
client_random
, string(8bit)
server_random
, ProtocolVersion
version
)
Generates keys appropriate for the SSL version given in version
,
based on the client_random
and server_random
.
Array | |
| Client write MAC secret |
| Server write MAC secret |
| Client write key |
| Server write key |
| Client write IV |
| Server write IV |
bool
has_required_certificates()
Indicates if this session has the required server certificate keys set. No means that no or the wrong type of certificate was sent from the server.
protected
bool
is_supported_cert(CertificatePair
cp
, int
ke_mask
, int
h_max
, ProtocolVersion
version
, array
(int
) ecc_curves
)
Used to filter certificates not supported by the peer.
cp
Candidate CertificatePair
.
version
Negotiated version of SSL.
ecc_curves
The set of ecc_curves supported by the peer.
bool
is_supported_suite(int
suite
, int
ke_mask
, ProtocolVersion
version
)
Used to filter the set of cipher suites suggested by the peer based on our available certificates.
suite
Candidate cipher suite.
ke_mask
The bit mask of the key exchange algorithms supported by the set of available certificates.
version
The negotiated version of SSL/TLS.
array
(State
) new_client_states(.Connection
con
, string(8bit)
client_random
, string(8bit)
server_random
, ProtocolVersion
version
)
Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.
Array | |
| Read state |
| Write state |
array
(State
) new_server_states(.Connection
con
, string(8bit)
client_random
, string(8bit)
server_random
, ProtocolVersion
version
)
Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.
Array | |
| Read state |
| Write state |
bool
reusable_as(Session
other
)
Returns true if this session object can be used in place of the
session object other
.
int
select_cipher_suite(array
(CertificatePair
) certs
, array
(int
) cipher_suites
, ProtocolVersion
version
)
Selects an apropriate certificate, authentication method and cipher suite for the parameters provided by the client.
certs
The list of CertificatePair
s that are applicable to the
server_name
of this session.
cipher_suites
The set of cipher suites that the client and server have in common.
version
The SSL protocol version to use.
Typical client extensions that also are used:
signature_algorithms
The set of signature algorithm tuples that the client claims to support.
int
set_cipher_suite(int
suite
, ProtocolVersion
version
, array
(int
)|zero
signature_algorithms
, int
max_hash_size
)
Sets the proper authentication method and cipher specification for the given parameters.
suite
The cipher suite to use, selected from the set that the client claims to support.
version
The SSL protocol version to use.
signature_algorithms
The set of signature algorithms tuples that the client claims to support.
max_hash_size
void
set_compression_method(int
compr
)
Sets the compression method. Currently only COMPRESSION_null
and COMPRESSION_deflate
are supported.
bool
validate_rsa_key(Crypto.RSA.State
rsa
)
Validate that KE RSA key is more than 512 bits or exportable.
The state object handles a one-way stream of packets, and operates in either decryption or encryption mode. A connection switches from one set of state objects to another, one or more times during its lifetime.
Cipher.CipherAlgorithm
SSL.State.crypt
Encryption or decryption object.
Cipher.MACAlgorithm
SSL.State.mac
Message Authentication Code
int
SSL.State.next_seq_num
64-bit sequence number.
string
SSL.State.salt
TLS 1.2 IV salt. This is used as a prefix for the IV for the AEAD cipher algorithms.
Session
SSL.State.session
Information about the used algorithms.
int
SSL.State.tls_iv
TLS IV prefix length.
Alert
|Packet
decrypt_packet(Packet
packet
)
Destructively decrypts a packet (including inflating and MAC-verification, if needed). On success, returns the decrypted packet. On failure, returns an alert packet. These cases are distinguished by looking at the is_alert attribute of the returned packet.
Alert
|Packet
encrypt_packet(Packet
packet
, Context
ctx
)
Encrypts a packet (including deflating and MAC-generation).
Dummy HTTPS server/client
SSL.File
SSL.https.Conn.sslfile
protected
local
void
__create__(SSL.File
sslfile
)
Encryption and MAC algorithms used in SSL.
protected
string(8bit)
P_hash(Crypto.Hash
hashfn
, string(8bit)
secret
, string(8bit)
seed
, int
len
)
Hashfn is either a Crypto.MD5
, Crypto.SHA
or Crypto.SHA256
.
CipherSpec
|zero
lookup(int
suite
, ProtocolVersion
|int
version
, array
(int
)|zero
signature_algorithms
, int
max_hash_size
)
Lookup the crypto parameters for a cipher suite.
suite
Cipher suite to lookup.
version
Version of the SSL/TLS protocol to support.
signature_algorithms
The set of SignatureScheme
values that
are supported by the other end.
max_hash_size
The maximum hash size supported for the signature algorithm.
Returns 0
(zero) for unsupported combinations, otherwise
returns an initialized CipherSpec
for the suite
.
string(8bit)
prf_sha384(string(8bit)
secret
, string(8bit)
label
, string(8bit)
seed
, int
len
)
This Pseudo Random Function is used to derive secret keys for some ciphers suites defined after TLS 1.2.
string(8bit)
prf_sha512(string(8bit)
secret
, string(8bit)
label
, string(8bit)
seed
, int
len
)
This Pseudo Random Function could be used to derive secret keys for some ciphers suites defined after TLS 1.2.
string(8bit)
prf_ssl_3_0(string(8bit)
secret
, string(8bit)
label
, string(8bit)
seed
, int
len
)
This Pseudo Random Function is used to derive secret keys in SSL 3.0.
The argument label
is ignored.
string(8bit)
prf_tls_1_0(string(8bit)
secret
, string(8bit)
label
, string(8bit)
seed
, int
len
)
This Pseudo Random Function is used to derive secret keys in TLS 1.0 and 1.1.
string(8bit)
prf_tls_1_2(string(8bit)
secret
, string(8bit)
label
, string(8bit)
seed
, int
len
)
This Pseudo Random Function is used to derive secret keys in TLS 1.2.
Cipher algorithm interface.
int(0..)
block_size()
Return the block size for this crypto.
this_program
set_encrypt_key(string
)
this_program
set_decrypt_key(string
)
Set the key used for encryption/decryption, and enter encryption mode.
Cipher specification.
program
SSL.Cipher.CipherSpec.bulk_cipher_algorithm
The algorithm to use for the bulk of the transfered data.
int
SSL.Cipher.CipherSpec.explicit_iv_size
The number of bytes of explicit data needed for initialization vectors.
This is used by AEAD ciphers in TLS 1.2, where there's a secret part of
the iv "salt" of length iv_size
, and an explicit part that is sent in
the clear.
This is usually bulk_cipher_algorithm->iv_size() - iv_size
,
but may be set to zero to just have the sequence number expanded
to the same size as an implicit iv. This is used by the suites
with Crypto.ChaCha20.POLY1305
.
Crypto.Hash
SSL.Cipher.CipherSpec.hash
The hash algorithm for signing the handshake.
Usually the same hash as is the base for the prf
.
Only used in TLS 1.2 and later.
int
SSL.Cipher.CipherSpec.hash_size
The number of bytes in the MAC hashes.
int
SSL.Cipher.CipherSpec.is_exportable
Indication whether the combination uses strong or weak (aka exportable) crypto.
int
SSL.Cipher.CipherSpec.iv_size
The number of bytes of random data needed for initialization vectors.
program
SSL.Cipher.CipherSpec.ke_factory
Key exchange factory.
int
SSL.Cipher.CipherSpec.key_bits
The effective number of bits in key_material
.
This is typically key_material * 8
, but for eg DES
this is key_material * 7
.
int
SSL.Cipher.CipherSpec.key_material
The number of bytes of key material used on initialization.
program
SSL.Cipher.CipherSpec.mac_algorithm
The Message Authentication Code to use for the packets.
int
SSL.Cipher.CipherSpec.max_bytes
The number of bytes that is safe to send before we must renegotiate the keys.
function
(string(8bit)
, string(8bit)
, string(8bit)
, int
:string(8bit)
) SSL.Cipher.CipherSpec.prf
The Pseudo Random Function to use.
prf_ssl_3_0()
, prf_tls_1_0()
, prf_tls_1_2()
SignatureAlgorithm
SSL.Cipher.CipherSpec.signature_alg
The signature algorithm used for key exchange signatures.
HashAlgorithm
SSL.Cipher.CipherSpec.signature_hash
The hash algorithm used for key exchange signatures.
Stdio.Buffer
sign(object
session
, string(8bit)
cookie
, Stdio.Buffer
struct
)
The function used to sign packets.
bool
verify(object
session
, string
data
, Stdio.Buffer
input
)
The function used to verify the signature for packets.
inherit Crypto.DES.CBC.Buffer.State : State
inherit Crypto.DES3.CBC.Buffer.State : State
KeyExchange method base class.
int
SSL.Cipher.KeyExchange.anonymous
Indicates whether a certificate isn't required.
object
SSL.Cipher.KeyExchange.context
object
SSL.Cipher.KeyExchange.session
object
SSL.Cipher.KeyExchange.connection
ProtocolVersion
SSL.Cipher.KeyExchange.client_version
int
SSL.Cipher.KeyExchange.message_was_bad
Indicates whether the key exchange has failed due to bad MACs.
protected
local
void
__create__(object
context
, object
session
, object
connection
, ProtocolVersion
client_version
)
string(8bit)
client_key_exchange_packet(Stdio.Buffer
packet_data
, ProtocolVersion
version
)
Returns the premaster secret, and fills in the payload for
a HANDSHAKE_client_key_exchange
packet in the submitted buffer.
May return 0
(zero) to generate an ALERT_unexpected_message
.
SSL.Cipher.KeyExchange SSL.Cipher.KeyExchange(
object
context
, object
session
, object
connection
, ProtocolVersion
client_version
)
string(8bit)
|int(8bit)
got_client_key_exchange(Stdio.Buffer
data
, ProtocolVersion
version
)
data
Payload from a HANDSHAKE_client_key_exchange
.
Premaster secret or alert number.
May set message_was_bad
and return a fake premaster secret.
int
got_server_key_exchange(Stdio.Buffer
input
, string
client_random
, string
server_random
)
input
Stdio.Buffer
with the content of a
HANDSHAKE_server_key_exchange
.
The default implementation calls parse_server_key_exchange()
,
and then verifies the signature.
| Returns zero on success. |
| Returns negative on verification failure. |
bool
init_client()
Initialize for client side use.
Returns 1
on success, and 0
(zero)
on failure.
bool
init_server()
Initialize for server side use.
Returns 1
on success, and 0
(zero)
on failure.
optional
void
make_key_share_offer(Stdio.Buffer
offer
)
TLS 1.3 and later.
Generate a key share offer for the configured named group
(currently only implemented in KeyShareECDHE
and KeyShareDHE
).
Stdio.Buffer
parse_server_key_exchange(Stdio.Buffer
input
)
input
Stdio.Buffer
with the content of a
HANDSHAKE_server_key_exchange
.
The key exchange information should be extracted from input
,
so that it is positioned at the signature.
Returns a new Stdio.Buffer
with the unsigned payload of
input
.
optional
string(8bit)
receive_key_share_offer(string(8bit)
offer
)
TLS 1.3 and later.
Receive a key share offer key exchange for the configured group
(currently only implemented in KeyShareECDHE
and KeyShareDHE
).
Clears the secret state.
Returns the shared pre-master key.
string(8bit)
|zero
server_key_exchange_packet(string
client_random
, string
server_random
)
The default implementation calls server_key_params()
to generate
the base payload.
Returns the signed payload for a HANDSHAKE_server_key_exchange
.
Stdio.Buffer
server_key_params()
Returns an Stdio.Buffer
with the
HANDSHAKE_server_key_exchange
payload.
optional
void
set_group(int
group
)
TLS 1.3 and later.
Set the group or curve to be used.
Key exchange for KE_dh_dss
and KE_dh_dss
.
KeyExchange
that uses Diffie-Hellman with a key from
a DSS certificate.
inherit KeyExchangeDHE : KeyExchangeDHE
KeyExchange for KE_dhe_rsa
, KE_dhe_dss
and KE_dh_anon
.
KeyExchange that uses Diffie-Hellman to generate an Ephemeral key.
inherit KeyExchange : KeyExchange
Crypto.DH.Parameters
SSL.Cipher.KeyExchangeDHE.parameters
Finite field Diffie-Hellman parameters.
string(8bit)
|int(8bit)
got_client_key_exchange(Stdio.Buffer
input
, ProtocolVersion
version
)
Premaster secret or alert number.
protected
bool
set_other(Gmp.smpz
o
)
Set the value received from the peer.
Returns 1
if o
is valid for the set parameters
.
Otherwise returns UNDEFINED
.
Key exchange for KE_dhe_psk
.
inherit KeyExchangeDHE : DHE
inherit KeyExchangePSK : PSK
KeyExchange for KE_ecdh_rsa
and KE_ecdh_ecdsa
.
NB: The only difference between the two is whether the certificate is signed with RSA or ECDSA.
This KeyExchange uses the Elliptic Curve parameters from the ECDSA certificate on the server side, and ephemeral parameters on the client side.
Deprecated in RFC 8422 section 5.5.
inherit KeyExchangeECDHE : KeyExchangeECDHE
KeyExchange for KE_ecdhe_rsa
, KE_ecdhe_ecdsa
and KE_ecdh_anon
.
KeyExchange that uses Elliptic Curve Diffie-Hellman or Edwards Curve Diffie-Hellman to generate an Ephemeral key.
inherit KeyExchange : KeyExchange
string(8bit)
|int(8bit)
got_client_key_exchange(Stdio.Buffer
data
, ProtocolVersion
version
)
Premaster secret or alert number.
Key exchange for KE_ecdhe_psk
.
inherit KeyExchangeECDHE : ECDHE
inherit KeyExchangePSK : PSK
Key exchange for KE_rsa_export
.
KeyExchange
that uses the Rivest Shamir Adelman algorithm,
but limited to 512 bits for encryption and decryption.
inherit KeyExchangeRSA : KeyExchangeRSA
Key exchange for KE_krb
.
KeyExchange
that uses Kerberos (RFC 2712).
inherit KeyExchange : KeyExchange
string(8bit)
|int
got_client_key_exchange(Stdio.Buffer
input
, ProtocolVersion
version
)
Premaster secret or alert number.
Key exchange for KE_null
.
This is the NULL KeyExchange
, which is only used for the
SSL_null_with_null_null
cipher suite, which is usually disabled.
inherit KeyExchange : KeyExchange
string(8bit)
got_client_key_exchange(Stdio.Buffer
data
, ProtocolVersion
version
)
Premaster secret or alert number.
Key exchange for KE_psk
, pre shared keys.
inherit KeyExchange : KeyExchange
Key exchange for KE_rsa
.
KeyExchange
that uses the Rivest Shamir Adelman algorithm.
inherit KeyExchange : KeyExchange
string(8bit)
|int(8bit)
got_client_key_exchange(Stdio.Buffer
input
, ProtocolVersion
version
)
Premaster secret or alert number.
Key exchange for KE_rsa_psk
.
inherit KeyExchangePSK : KeyExchangePSK
Message Authentication Code interface.
constant
int
SSL.Cipher.MACAlgorithm.hash_header_size
The length of the header prefixed by hash()
.
int
block_size()
The block size of the underlying hash algorithm.
string
hash(string
data
)
Creates a HMAC hash of the data
with the underlying hash
algorithm.
string
hash_packet(object
packet
, int
|void
adjust_len
)
Generates a header and creates a HMAC hash for the given
packet
.
packet
Packet
to generate a MAC hash for.
adjust_len
Added to sizeof(packet) to get the packet length.
Returns the MAC hash for the packet
.
string
hash_raw(string
data
)
Creates a normal hash of the data
using the underlying hash
algorithm.
HMAC using MD5.
This is the MAC algorithm used by TLS 1.0 and later.
inherit MAChmac_sha : MAChmac_sha
HMAC using SHA.
This is the MAC algorithm used by TLS 1.0 and later.
inherit MACAlgorithm : MACAlgorithm
SSL.Cipher.MAChmac_sha SSL.Cipher.MAChmac_sha(
string
|void
s
)
HMAC using SHA256.
This is the MAC algorithm used by some cipher suites in TLS 1.2 and later.
inherit MAChmac_sha : MAChmac_sha
HMAC using SHA384.
This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.
inherit MAChmac_sha : MAChmac_sha
HMAC using SHA512.
This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.
inherit MAChmac_sha : MAChmac_sha
MAC using MD5.
Note: This uses the algorithm from the SSL 3.0 draft.
inherit MACsha : MACsha
MAC using SHA.
Note: This uses the algorithm from the SSL 3.0 draft.
inherit MACAlgorithm : MACAlgorithm
inherit Crypto.Arctwo.CBC.Buffer.State : State
Protocol constants
constant
int
SSL.Constants.AUTHLEVEL_ask
As a server, request a certificate, but don't require a response. This AUTHLEVEL is not relevant for clients.
constant
int
SSL.Constants.AUTHLEVEL_none
Don't request nor check any certificate.
constant
int
SSL.Constants.AUTHLEVEL_require
Require other party to send a valid certificate.
constant
int
SSL.Constants.AUTHLEVEL_verify
Don't request, but verify any certificate.
constant
SSL.Constants.CIPHER_SUITES
A mapping from cipher suite identifier to an array defining the algorithms to be used in that suite.
Array | |
| The key exchange algorithm to be used for this suite, or 0.
E.g. |
| The cipher algorithm to be used for this suite, or 0. E.g.
|
| The hash algorithm to be used for this suite, or 0. E.g.
|
| Optionally for TLS 1.2 and later cipher suites the mode of
operation. E.g. |
constant
SSL.Constants.CIPHER_effective_keylengths
Mapping from cipher algorithm to effective key length.
constant
SSL.Constants.ECC_NAME_TO_CURVE
Lookup for Pike ECC name to NamedGroup
.
constant
SSL.Constants.HASH_lookup
Lookup from HashAlgorithm
to corresponding Crypto.Hash
.
constant
SSL.Constants.KE_Anonymous
Lists KeyExchangeType
that doesn't require certificates.
constant
SSL.Constants.PROTOCOL_TLS_MAX
Max supported TLS version.
string
fmt_cipher_suite(int
suite
)
Return a descriptive name for a cipher suite.
suite
Cipher suite to format.
string
fmt_cipher_suites(array
(int
) s
)
Pretty-print an array of cipher suites.
s
Array of cipher suites to format.
string
fmt_constant(int
c
, string
prefix
)
Return a descriptive name for a constant value.
c
Value to format.
prefix
Constant name prefix. Eg "CONNECTION"
.
string
fmt_signature_pairs(array
(int
) pairs
)
Pretty-print an array of SignatureScheme
s.
pairs
Array of signature pairs to format.
string
fmt_version(ProtocolVersion
version
)
Pretty-print a ProtocolVersion
.
version
ProtocolVersion
to format.
Application Level Protocol Negotiation protocol identifiers.
EXTENSION_application_layer_protocol_negotiation
constant
SSL.Constants.ALPN_http_1_1
constant
SSL.Constants.ALPN_spdy_1
constant
SSL.Constants.ALPN_spdy_2
constant
SSL.Constants.ALPN_spdy_3
constant
SSL.Constants.ALPN_turn
constant
SSL.Constants.ALPN_stun
constant
SSL.Constants.ALPN_http_2
constant
SSL.Constants.ALPN_http_2_reserved
constant
SSL.Constants.ADF_x509_attr_cert
constant
SSL.Constants.ADF_saml_assertion
constant
SSL.Constants.ADF_x509_attr_cert_url
constant
SSL.Constants.ADF_saml_assertion_url
constant
SSL.Constants.CERTTYPE_x509
constant
SSL.Constants.CERTTYPE_openpgp
constant
SSL.Constants.CERTTYPE_raw_public_key
Cipher operation modes.
constant
SSL.Constants.MODE_cbc
CBC - Cipher Block Chaining mode.
constant
SSL.Constants.MODE_ccm
CCM - Counter with CBC-MAC mode.
constant
SSL.Constants.MODE_ccm_8
CCM - Counter with 8 bit CBC-MAC mode.
constant
SSL.Constants.MODE_gcm
GCM - Galois Cipher Mode.
constant
SSL.Constants.MODE_poly1305
Poly1305 - Used only with ChaCha20.
constant
SSL.Constants.SSL_invalid_suite
constant
SSL.Constants.SSL_null_with_null_null
constant
SSL.Constants.SSL_rsa_with_null_md5
constant
SSL.Constants.SSL_rsa_with_null_sha
constant
SSL.Constants.SSL_rsa_export_with_rc4_40_md5
constant
SSL.Constants.SSL_rsa_with_rc4_128_md5
constant
SSL.Constants.SSL_rsa_with_rc4_128_sha
constant
SSL.Constants.SSL_rsa_export_with_rc2_cbc_40_md5
constant
SSL.Constants.SSL_rsa_with_idea_cbc_sha
constant
SSL.Constants.TLS_rsa_with_idea_cbc_sha
constant
SSL.Constants.SSL_rsa_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_rsa_with_des_cbc_sha
constant
SSL.Constants.TLS_rsa_with_des_cbc_sha
constant
SSL.Constants.SSL_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_dh_dss_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_dh_dss_with_des_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_des_cbc_sha
constant
SSL.Constants.SSL_dh_dss_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_dh_rsa_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_dh_rsa_with_des_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_des_cbc_sha
constant
SSL.Constants.SSL_dh_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_dhe_dss_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_dhe_dss_with_des_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_des_cbc_sha
constant
SSL.Constants.SSL_dhe_dss_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_dhe_rsa_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_dhe_rsa_with_des_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_des_cbc_sha
constant
SSL.Constants.SSL_dhe_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_dh_anon_export_with_rc4_40_md5
constant
SSL.Constants.SSL_dh_anon_with_rc4_128_md5
constant
SSL.Constants.SSL_dh_anon_export_with_des40_cbc_sha
constant
SSL.Constants.SSL_dh_anon_with_des_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_des_cbc_sha
constant
SSL.Constants.SSL_dh_anon_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_rsa_fips_with_des_cbc_sha
constant
SSL.Constants.SSL_rsa_fips_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_rsa_oldfips_with_des_cbc_sha
constant
SSL.Constants.SSL_rsa_oldfips_with_3des_ede_cbc_sha
constant
SSL.Constants.SSL_rsa_with_rc2_cbc_md5
constant
SSL.Constants.SSL_rsa_with_idea_cbc_md5
constant
SSL.Constants.SSL_rsa_with_des_cbc_md5
constant
SSL.Constants.SSL_rsa_with_3des_ede_cbc_md5
constant
SSL.Constants.TLS_aes_128_gcm_sha256
constant
SSL.Constants.TLS_aes_256_gcm_sha384
constant
SSL.Constants.TLS_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_aes_128_ccm_sha256
constant
SSL.Constants.TLS_aes_128_ccm_8_sha256
constant
SSL.Constants.TLS_krb5_with_des_cbc_sha
constant
SSL.Constants.TLS_krb5_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_krb5_with_rc4_128_sha
constant
SSL.Constants.TLS_krb5_with_idea_cbc_sha
constant
SSL.Constants.TLS_krb5_with_des_cbc_md5
constant
SSL.Constants.TLS_krb5_with_3des_ede_cbc_md5
constant
SSL.Constants.TLS_krb5_with_rc4_128_md5
constant
SSL.Constants.TLS_krb5_with_idea_cbc_md5
constant
SSL.Constants.TLS_krb5_export_with_des_cbc_40_sha
constant
SSL.Constants.TLS_krb5_export_with_rc2_cbc_40_sha
constant
SSL.Constants.TLS_krb5_export_with_rc4_40_sha
constant
SSL.Constants.TLS_krb5_export_with_des_cbc_40_md5
constant
SSL.Constants.TLS_krb5_export_with_rc2_cbc_40_md5
constant
SSL.Constants.TLS_krb5_export_with_rc4_40_md5
constant
SSL.Constants.TLS_psk_with_null_sha
constant
SSL.Constants.TLS_dhe_psk_with_null_sha
constant
SSL.Constants.TLS_rsa_psk_with_null_sha
constant
SSL.Constants.TLS_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_rsa_with_null_sha256
constant
SSL.Constants.TLS_rsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_dh_dss_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_dh_rsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_dss_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_camellia_128_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_dh_dss_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_dh_rsa_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_dhe_dss_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_dh_anon_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_dh_anon_with_aes_256_cbc_sha256
constant
SSL.Constants.TLS_rsa_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_camellia_256_cbc_sha
constant
SSL.Constants.TLS_psk_with_rc4_128_sha
constant
SSL.Constants.TLS_psk_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_psk_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_psk_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_dhe_psk_with_rc4_128_sha
constant
SSL.Constants.TLS_dhe_psk_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_dhe_psk_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_dhe_psk_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_rsa_psk_with_rc4_128_sha
constant
SSL.Constants.TLS_rsa_psk_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_rsa_psk_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_rsa_psk_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_rsa_with_seed_cbc_sha
constant
SSL.Constants.TLS_dh_dss_with_seed_cbc_sha
constant
SSL.Constants.TLS_dh_rsa_with_seed_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_with_seed_cbc_sha
constant
SSL.Constants.TLS_dhe_rsa_with_seed_cbc_sha
constant
SSL.Constants.TLS_dh_anon_with_seed_cbc_sha
constant
SSL.Constants.TLS_rsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_rsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dh_rsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dh_rsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_dss_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_dss_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dh_dss_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dh_dss_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dh_anon_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dh_anon_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_psk_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_psk_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_psk_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_psk_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_rsa_psk_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_psk_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_psk_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_psk_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_psk_with_null_sha256
constant
SSL.Constants.TLS_psk_with_null_sha384
constant
SSL.Constants.TLS_dhe_psk_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_psk_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_dhe_psk_with_null_sha256
constant
SSL.Constants.TLS_dhe_psk_with_null_sha384
constant
SSL.Constants.TLS_rsa_psk_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_psk_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_psk_with_null_sha256
constant
SSL.Constants.TLS_rsa_psk_with_null_sha384
constant
SSL.Constants.TLS_rsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dh_dss_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dh_rsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_dss_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dh_anon_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_dh_dss_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_dh_rsa_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_dhe_dss_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_dh_anon_with_camellia_256_cbc_sha256
constant
SSL.Constants.TLS_sm4_gcm_sm3
constant
SSL.Constants.TLS_sm4_ccm_sm3
constant
SSL.Constants.TLS_ecdh_ecdsa_with_null_sha
constant
SSL.Constants.TLS_ecdh_ecdsa_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdh_ecdsa_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_null_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdh_rsa_with_null_sha
constant
SSL.Constants.TLS_ecdh_rsa_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdh_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_null_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdh_anon_with_null_sha
constant
SSL.Constants.TLS_ecdh_anon_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdh_anon_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdh_anon_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdh_anon_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_srp_sha_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_srp_sha_rsa_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_srp_sha_dss_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_srp_sha_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_srp_sha_rsa_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_srp_sha_dss_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_srp_sha_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_srp_sha_rsa_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_srp_sha_dss_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_psk_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdhe_psk_with_3des_ede_cbc_sha
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_128_cbc_sha
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_256_cbc_sha
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_psk_with_null_sha
constant
SSL.Constants.TLS_ecdhe_psk_with_null_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_null_sha384
constant
SSL.Constants.TLS_rsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dh_dss_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dh_dss_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dh_rsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dh_rsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dhe_dss_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_dss_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dhe_rsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dh_anon_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dh_anon_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_rsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dh_rsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dh_rsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_dss_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_dss_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dh_dss_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dh_dss_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dh_anon_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dh_anon_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_psk_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_psk_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_dhe_psk_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_psk_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_psk_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_psk_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_psk_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_psk_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_psk_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_psk_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_rsa_psk_with_aria_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_psk_with_aria_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_psk_with_aria_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_aria_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dh_rsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dh_rsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_dss_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_dss_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dh_dss_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dh_dss_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dh_anon_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dh_anon_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_ecdsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_ecdsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_rsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_ecdh_rsa_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_ecdh_rsa_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_psk_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_psk_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_dhe_psk_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_dhe_psk_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_rsa_psk_with_camellia_128_gcm_sha256
constant
SSL.Constants.TLS_rsa_psk_with_camellia_256_gcm_sha384
constant
SSL.Constants.TLS_psk_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_psk_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_dhe_psk_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_dhe_psk_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_psk_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_rsa_psk_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_ecdhe_psk_with_camellia_128_cbc_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_camellia_256_cbc_sha384
constant
SSL.Constants.TLS_rsa_with_aes_128_ccm
constant
SSL.Constants.TLS_rsa_with_aes_256_ccm
constant
SSL.Constants.TLS_dhe_rsa_with_aes_128_ccm
constant
SSL.Constants.TLS_dhe_rsa_with_aes_256_ccm
constant
SSL.Constants.TLS_rsa_with_aes_128_ccm_8
constant
SSL.Constants.TLS_rsa_with_aes_256_ccm_8
constant
SSL.Constants.TLS_dhe_rsa_with_aes_128_ccm_8
constant
SSL.Constants.TLS_dhe_rsa_with_aes_256_ccm_8
constant
SSL.Constants.TLS_psk_with_aes_128_ccm
constant
SSL.Constants.TLS_psk_with_aes_256_ccm
constant
SSL.Constants.TLS_dhe_psk_with_aes_128_ccm
constant
SSL.Constants.TLS_dhe_psk_with_aes_256_ccm
constant
SSL.Constants.TLS_psk_with_aes_128_ccm_8
constant
SSL.Constants.TLS_psk_with_aes_256_ccm_8
constant
SSL.Constants.TLS_psk_dhe_with_aes_128_ccm_8
constant
SSL.Constants.TLS_psk_dhe_with_aes_256_ccm_8
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_128_ccm
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_256_ccm
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_128_ccm_8
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_aes_256_ccm_8
constant
SSL.Constants.TLS_eccpwd_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_eccpwd_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_eccpwd_with_aes_128_ccm_sha256
constant
SSL.Constants.TLS_eccpwd_with_aes_256_ccm_sha384
constant
SSL.Constants.TLS_rsa_export1024_with_rc4_56_md5
constant
SSL.Constants.TLS_rsa_export1024_with_rc2_cbc_56_md5
constant
SSL.Constants.TLS_rsa_export1024_with_des_cbc_sha
constant
SSL.Constants.TLS_dhe_dss_export1024_with_des_cbc_sha
constant
SSL.Constants.TLS_rsa_export1024_with_rc4_56_sha
constant
SSL.Constants.TLS_dhe_dss_export1024_with_rc4_56_sha
constant
SSL.Constants.TLS_dhe_dss_with_rc4_128_sha
constant
SSL.Constants.TLS_ecdhe_rsa_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_psk_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_dhe_psk_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_rsa_psk_with_chacha20_poly1305_sha256
constant
SSL.Constants.TLS_ecdhe_rsa_with_oldchacha20_poly1305_sha256
constant
SSL.Constants.TLS_ecdhe_ecdsa_with_oldchacha20_poly1305_sha256
constant
SSL.Constants.TLS_dhe_rsa_with_oldchacha20_poly1305_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_128_gcm_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_256_gcm_sha384
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_128_ccm_8_sha256
constant
SSL.Constants.TLS_ecdhe_psk_with_aes_128_ccm_sha256
constant
SSL.Constants.TLS_empty_renegotiation_info_scsv
constant
SSL.Constants.TLS_fallback_scsv
constant
SSL.Constants.SSL2_ck_rc4_128_with_md5
constant
SSL.Constants.SSL2_ck_rc4_128_export40_with_md5
constant
SSL.Constants.SSL2_ck_rc2_128_cbc_with_md5
constant
SSL.Constants.SSL2_ck_rc2_128_cbc_export40_with_md5
constant
SSL.Constants.SSL2_ck_idea_128_cbc_with_md5
constant
SSL.Constants.SSL2_ck_des_64_cbc_with_md5
constant
SSL.Constants.SSL2_ck_des_192_ede3_cbc_with_md5
Compression methods.
constant
SSL.Constants.COMPRESSION_deflate
Deflate compression. RFC 3749
constant
SSL.Constants.COMPRESSION_lzs
LZS compression. RFC 3943
constant
SSL.Constants.COMPRESSION_null
No compression.
Connection states.
These are the states that a [Connection] may have.
Queueing of more application data is only
allowed in the states CONNECTION_ready
and
CONNECTION_handshaking
.
constant
SSL.Constants.CONNECTION_closed
Closed at both ends.
constant
SSL.Constants.CONNECTION_closing
Connection closing mask.
constant
SSL.Constants.CONNECTION_failing
Connection failing mask.
constant
SSL.Constants.CONNECTION_handshaking
Handshaking not done.
constant
SSL.Constants.CONNECTION_local_closed
Local close packet sent.
constant
SSL.Constants.CONNECTION_local_closing
Local close packet pending.
constant
SSL.Constants.CONNECTION_local_down
Local mask.
constant
SSL.Constants.CONNECTION_local_failing
Fatal alert pending.
constant
SSL.Constants.CONNECTION_local_fatal
Fatal alert sent.
constant
SSL.Constants.CONNECTION_peer_closed
Peer has closed the connection.
constant
SSL.Constants.CONNECTION_peer_down
Peer mask.
constant
SSL.Constants.CONNECTION_peer_fatal
Peer has issued a fatal alert.
constant
SSL.Constants.CONNECTION_ready
Connection is ready for use.
ECC curve types from RFC 4492 section 5.4 (ECCurveType).
constant
SSL.Constants.CURVETYPE_explicit_char2
Deprecated RFC 8422 section 5.4
constant
SSL.Constants.CURVETYPE_explicit_prime
Deprecated RFC 8422 section 5.4
constant
SSL.Constants.CURVETYPE_named_curve
Curve or group from NamedGroup
.
constant
SSL.Constants.ECBASIS_trinomial
constant
SSL.Constants.ECBASIS_pentanomial
Client Hello extensions.
constant
SSL.Constants.EXTENSION_server_name
constant
SSL.Constants.EXTENSION_max_fragment_length
constant
SSL.Constants.EXTENSION_client_certificate_url
constant
SSL.Constants.EXTENSION_trusted_ca_keys
constant
SSL.Constants.EXTENSION_truncated_hmac
constant
SSL.Constants.EXTENSION_status_request
constant
SSL.Constants.EXTENSION_user_mapping
constant
SSL.Constants.EXTENSION_client_authz
constant
SSL.Constants.EXTENSION_server_authz
constant
SSL.Constants.EXTENSION_cert_type
constant
SSL.Constants.EXTENSION_elliptic_curves
constant
SSL.Constants.EXTENSION_ec_point_formats
constant
SSL.Constants.EXTENSION_srp
constant
SSL.Constants.EXTENSION_signature_algorithms
constant
SSL.Constants.EXTENSION_use_srtp
constant
SSL.Constants.EXTENSION_heartbeat
constant
SSL.Constants.EXTENSION_application_layer_protocol_negotiation
constant
SSL.Constants.EXTENSION_status_request_v2
constant
SSL.Constants.EXTENSION_signed_certificate_timestamp
constant
SSL.Constants.EXTENSION_client_certificate_type
constant
SSL.Constants.EXTENSION_server_certificate_type
constant
SSL.Constants.EXTENSION_padding
constant
SSL.Constants.EXTENSION_encrypt_then_mac
constant
SSL.Constants.EXTENSION_extended_master_secret
constant
SSL.Constants.EXTENSION_session_ticket
constant
SSL.Constants.EXTENSION_key_share
constant
SSL.Constants.EXTENSION_pre_shared_key
constant
SSL.Constants.EXTENSION_early_data
constant
SSL.Constants.EXTENSION_supported_versions
constant
SSL.Constants.EXTENSION_cookie
constant
SSL.Constants.EXTENSION_psk_key_exchange_modes
constant
SSL.Constants.EXTENSION_certificate_authorities
constant
SSL.Constants.EXTENSION_oid_filters
constant
SSL.Constants.EXTENSION_post_handshake_auth
constant
SSL.Constants.EXTENSION_next_protocol_negotiation
constant
SSL.Constants.EXTENSION_origin_bound_certificates
constant
SSL.Constants.EXTENSION_encrypted_client_certificates
constant
SSL.Constants.EXTENSION_channel_id
constant
SSL.Constants.EXTENSION_channel_id_new
constant
SSL.Constants.EXTENSION_old_padding
constant
SSL.Constants.EXTENSION_renegotiation_info
constant
SSL.Constants.EXTENSION_draft_version
Fragment lengths for EXTENSION_max_fragment_length
.
constant
SSL.Constants.FRAGMENT_512
constant
SSL.Constants.FRAGMENT_1024
constant
SSL.Constants.FRAGMENT_2048
constant
SSL.Constants.FRAGMENT_4096
Hash algorithms as per RFC 5246 section 7.4.1.4.1.
constant
SSL.Constants.HASH_MASK
constant
SSL.Constants.HASH_none
constant
SSL.Constants.HASH_md5
constant
SSL.Constants.HASH_sha1
constant
SSL.Constants.HASH_sha224
constant
SSL.Constants.HASH_sha256
constant
SSL.Constants.HASH_sha384
constant
SSL.Constants.HASH_sha512
constant
SSL.Constants.HASH_intrinsic
constant
SSL.Constants.HEARTBEAT_MESSAGE_request
constant
SSL.Constants.HEARTBEAT_MESSAGE_response
constant
SSL.Constants.HEARTBEAT_MODE_disabled
constant
SSL.Constants.HEARTBEAT_MODE_peer_allowed_to_send
constant
SSL.Constants.HEARTBEAT_MODE_peer_not_allowed_to_send
Key exchange methods.
constant
SSL.Constants.KE_dh_anon
Diffie-Hellman Anonymous
constant
SSL.Constants.KE_dh_dss
Diffie-Hellman cert signed with DSS
constant
SSL.Constants.KE_dh_rsa
Diffie-Hellman cert signed with RSA
constant
SSL.Constants.KE_dhe_dss
Diffie-Hellman Ephemeral DSS
constant
SSL.Constants.KE_dhe_psk
Pre-shared Key with DHE
constant
SSL.Constants.KE_dhe_rsa
Diffie-Hellman Ephemeral RSA
constant
SSL.Constants.KE_dms
constant
SSL.Constants.KE_fortezza
constant
SSL.Constants.KE_ecdh_anon
Elliptic Curve DH Anonymous
constant
SSL.Constants.KE_ecdh_ecdsa
Elliptic Curve DH cert signed with ECDSA
constant
SSL.Constants.KE_ecdh_rsa
Elliptic Curve DH cert signed with RSA
constant
SSL.Constants.KE_ecdhe_ecdsa
Elliptic Curve DH Ephemeral with ECDSA
constant
SSL.Constants.KE_ecdhe_psk
Pre-shared Key with ECDHE
constant
SSL.Constants.KE_ecdhe_rsa
Elliptic Curve DH Ephemeral with RSA
constant
SSL.Constants.KE_null
None.
constant
SSL.Constants.KE_psk
Pre-shared Key
constant
SSL.Constants.KE_rsa
Rivest-Shamir-Adelman
constant
SSL.Constants.KE_rsa_export
Rivest-Shamir-Adelman (EXPORT)
constant
SSL.Constants.KE_rsa_fips
Rivest-Shamir-Adelman with FIPS keys.
constant
SSL.Constants.KE_rsa_psk
Pre-shared Key signed with RSA
constant
SSL.Constants.KE_srp_sha
Secure Remote Password (SRP)
constant
SSL.Constants.KE_srp_sha_dss
SRP signed with DSS
constant
SSL.Constants.KE_srp_sha_rsa
SRP signed with RSA
Groups used for elliptic curves DHE (ECDHE) and finite field DH (FFDHE).
RFC 4492 section 5.1.1 (NamedCurve) / TLS 1.3 7.4.2.5.2. */
constant
SSL.Constants.GROUP_arbitrary_explicit_char2_curves
Deprecated RFC 8422 section 5.1.1
constant
SSL.Constants.GROUP_arbitrary_explicit_prime_curves
Deprecated RFC 8422 section 5.1.1
constant
SSL.Constants.GROUP_brainpoolP256r1
constant
SSL.Constants.GROUP_brainpoolP384r1
constant
SSL.Constants.GROUP_brainpoolP512r1
constant
SSL.Constants.GROUP_ffdhe2048
constant
SSL.Constants.GROUP_ffdhe3072
constant
SSL.Constants.GROUP_ffdhe4096
constant
SSL.Constants.GROUP_ffdhe6144
constant
SSL.Constants.GROUP_ffdhe8192
constant
SSL.Constants.GROUP_ffdhe_private0
constant
SSL.Constants.GROUP_ffdhe_private1
constant
SSL.Constants.GROUP_ffdhe_private2
constant
SSL.Constants.GROUP_ffdhe_private3
constant
SSL.Constants.GROUP_secp160k1
constant
SSL.Constants.GROUP_secp160r1
constant
SSL.Constants.GROUP_secp160r2
constant
SSL.Constants.GROUP_secp192k1
constant
SSL.Constants.GROUP_secp192r1
constant
SSL.Constants.GROUP_secp224k1
constant
SSL.Constants.GROUP_secp224r1
constant
SSL.Constants.GROUP_secp256k1
constant
SSL.Constants.GROUP_secp256r1
constant
SSL.Constants.GROUP_secp384r1
constant
SSL.Constants.GROUP_secp521r1
constant
SSL.Constants.GROUP_sect163k1
constant
SSL.Constants.GROUP_sect163r1
constant
SSL.Constants.GROUP_sect163r2
constant
SSL.Constants.GROUP_sect193r1
constant
SSL.Constants.GROUP_sect193r2
constant
SSL.Constants.GROUP_sect233k1
constant
SSL.Constants.GROUP_sect233r1
constant
SSL.Constants.GROUP_sect239k1
constant
SSL.Constants.GROUP_sect283k1
constant
SSL.Constants.GROUP_sect283r1
constant
SSL.Constants.GROUP_sect409k1
constant
SSL.Constants.GROUP_sect409r1
constant
SSL.Constants.GROUP_sect571k1
constant
SSL.Constants.GROUP_sect571r1
constant
SSL.Constants.GROUP_x25519
constant
SSL.Constants.GROUP_x448
constant
SSL.Constants.POINT_uncompressed
constant
SSL.Constants.POINT_ansiX962_compressed_prime
constant
SSL.Constants.POINT_ansiX962_compressed_char2
Constants for specifying the versions of SSL/TLS to use.
Context
constant
SSL.Constants.PROTOCOL_DTLS_1_0
DTLS 1.0 - The RFC 4347 version of DTLS. This is essentially TLS 1.1 over UDP.
constant
SSL.Constants.PROTOCOL_DTLS_1_2
DTLS 1.2 - The RFC 6347 version of DTLS. This is essentially TLS 1.2 over UDP.
constant
SSL.Constants.PROTOCOL_IN_EXTENSION
Pike internal marker
constant
SSL.Constants.PROTOCOL_SSL_3_0
SSL 3.0 - The original SSL3 draft version.
constant
SSL.Constants.PROTOCOL_TLS_1_0
TLS 1.0 - The RFC 2246 version of TLS.
constant
SSL.Constants.PROTOCOL_TLS_1_1
TLS 1.1 - The RFC 4346 version of TLS.
constant
SSL.Constants.PROTOCOL_TLS_1_2
TLS 1.2 - The RFC 5246 version of TLS.
constant
SSL.Constants.PROTOCOL_TLS_1_3
TLS 1.3 - The RFC 8446 version of TLS.
Signature algorithms from TLS 1.2.
constant
SSL.Constants.SIGNATURE_MASK
constant
SSL.Constants.SIGNATURE_anonymous
No signature.
constant
SSL.Constants.SIGNATURE_dsa
DSS signature.
constant
SSL.Constants.SIGNATURE_ecdsa
ECDSA signature.
constant
SSL.Constants.SIGNATURE_ed25519
EdDSA 25519 signature.
constant
SSL.Constants.SIGNATURE_ed448
EdDSA 448 signature.
constant
SSL.Constants.SIGNATURE_rsa
RSASSA PKCS1 v1.5 signature.
constant
SSL.Constants.SIGNATURE_rsa_pss_256
RSA PSS signature with 256 bit hash.
constant
SSL.Constants.SIGNATURE_rsa_pss_384
RSA PSS signature with 384 bit hash.
constant
SSL.Constants.SIGNATURE_rsa_pss_512
RSA PSS signature with 512 bit hash.
Signature algorithms from TLS 1.3
constant
SSL.Constants.SIGNATURE_ecdsa_secp256r1_sha256
constant
SSL.Constants.SIGNATURE_ecdsa_secp384r1_sha384
constant
SSL.Constants.SIGNATURE_ecdsa_secp521r1_sha512
constant
SSL.Constants.SIGNATURE_rsa_pkcs1_sha1
constant
SSL.Constants.SIGNATURE_ecdsa_sha1
constant
SSL.Constants.SIGNATURE_ed25519_intrinsic
constant
SSL.Constants.SIGNATURE_ed448_intrinsic
constant
SSL.Constants.SIGNATURE_rsa_pkcs1_sha256
constant
SSL.Constants.SIGNATURE_rsa_pkcs1_sha384
constant
SSL.Constants.SIGNATURE_rsa_pkcs1_sha512
constant
SSL.Constants.SIGNATURE_rsa_pss_sha256
constant
SSL.Constants.SIGNATURE_rsa_pss_sha384
constant
SSL.Constants.SIGNATURE_rsa_pss_sha512
Values used for supp_data_type in SupplementalDataEntry (cf RFC 4681 section 3).
constant
SSL.Constants.SDT_user_mapping_data
constant
SSL.Constants.UMT_upn_domain_hint
A chain of X509 certificates with corresponding private key.
It also contains some derived metadata.
int
SSL.Constants.CertificatePair.cert_type
Cerificate type for the leaf cert.
One of the AUTH_*
constants.
array
(string(8bit)
) SSL.Constants.CertificatePair.certs
Chain of certificates, root cert last.
array
(string(8bit)
) SSL.Constants.CertificatePair.globs
Array of commonName globs from the first certificate in certs
.
array
(string(8bit)
) SSL.Constants.CertificatePair.issuers
Array of DER for the issuers matching certs
.
int(0..)
SSL.Constants.CertificatePair.ke_mask
Bitmask of the key exchange algorithms supported by the main certificate. This is used for TLS 1.1 and earlier.
ke_mask_invariant
int(0..)
SSL.Constants.CertificatePair.ke_mask_invariant
Bitmask of the key exchange algorithms supported by the main certificate.
This is the same as ke_mask
, but unified with respect to
KE_dh_dss
/KE_dh_rsa
and KE_ecdh_ecdsa
/KE_ecdh_rsa
,
as supported by TLS 1.2 and later.
Crypto.Sign.State
SSL.Constants.CertificatePair.key
Private key.
array
(SignatureScheme
) SSL.Constants.CertificatePair.sign_algs
TLS 1.2-style hash and signature pairs matching the certs
.
SSL.Constants.CertificatePair SSL.Constants.CertificatePair(
Crypto.Sign.State
key
, array
(string(8bit)
) certs
, array
(string(8bit)
)|void
extra_name_globs
)
Initializa a new CertificatePair
.
key
Private key.
certs
Chain of certificates, root cert last.
extra_globs
The set of globs
from the first certificate
is optionally extended with these.
Performs various validation checks.
Support for the Domain Name System protocol.
final
constantint
Protocols.DNS.FORMERR
The name server was unable to interpret the request due to a format error.
final
constantint
Protocols.DNS.NOERROR
No error condition.
final
constantint
Protocols.DNS.NOTAUTH
Server not authoritative for zone.
final
constantint
Protocols.DNS.NOTIMP
final
constantint
Protocols.DNS.NOTIMPL
The name server does not support the specified Opcode.
final
constantint
Protocols.DNS.NOTZONE
Name not contained in zone.
final
constantint
Protocols.DNS.NXDOMAIN
Some name that ought to exist, does not exist.
final
constantint
Protocols.DNS.NXRRSET
Some RRset that ought to exist, does not exist.
final
constantint
Protocols.DNS.REFUSED
The name server refuses to perform the specified operation for policy or security reasons.
final
constantint
Protocols.DNS.SERVFAIL
The name server encountered an internal failure while processing this request, for example an operating system error or a forwarding timeout.
final
constantint
Protocols.DNS.YXDOMAIN
Name that should not exist, does exist.
final
constantint
Protocols.DNS.YXRRSET
RRset that should not exist, does exist.
client.Request
async_get_mx(string
host
, function
(:void
) cb
, mixed
... cba
)
Concurrent.Future
async_get_mx(string
host
)
Calls get_mx in a global async_client created on demand.
async_client.get_mx()
client.Request
async_get_mx_all(string
host
, function
(:void
) cb
, mixed
... cba
)
Concurrent.Future
async_get_mx_all(string
host
)
Calls get_mx_all in a global async_client created on demand.
async_client.get_mx_all()
client.Request
async_host_to_ip(string
host
, function
(:void
) cb
, mixed
... cba
)
Concurrent.Future
async_host_to_ip(string
host
)
Calls host_to_ip in a global async_client created on demand.
async_client.host_to_ip()
client.Request
async_host_to_ips(string
host
, function
(:void
) cb
, mixed
... cba
)
Concurrent.Future
async_host_to_ips(string
host
)
Calls host_to_ips in a global async_client created on demand.
async_client.host_to_ips()
client.Request
async_ip_to_host(string
ip
, function
(:void
) cb
, mixed
... cba
)
Concurrent.Future
async_ip_to_host(string
ip
)
Calls ip_to_host in a global async_client created on demand.
async_client.ip_to_host()
string
get_mx(string
host
)
string
get_primary_mx(string
host
)
array
gethostbyaddr(string
host
)
array
gethostbyname(string
host
)
Flag bits used in T_DNSKEY
RRs.
constant
Protocols.DNS.F_SECUREENTRYPOINT
Secure Entry Point.
constant
Protocols.DNS.F_ZONEKEY
Zone Key.
DNSSEC Digest types.
constant
Protocols.DNS.DNSSEC_SHA1
SHA1 digest RFC 4035 appendix A.2.
DNSSEC Protocol types.
RFC 4034 obsoleted all but DNSSEC_DNSSEC
.
constant
Protocols.DNS.DNSSEC_ALL
Any use. Discouraged.
constant
Protocols.DNS.DNSSEC_DNSSEC
Key for use by DNSSEC. RFC 4034 section 2.1.2.
constant
Protocols.DNS.DNSSEC_EMAIL
Reserved for use by SMTP et al.
constant
Protocols.DNS.DNSSEC_IPSEC
Reserved for use by IPSEC.
constant
Protocols.DNS.DNSSEC_TLS
Reserved for use by TLS.
DNSSEC Algorithm types.
constant
Protocols.DNS.DNSSEC_DH
Diffie-Hellman RFC 2539.
constant
Protocols.DNS.DNSSEC_DSA
DSA/SHA1 RFC 2536.
constant
Protocols.DNS.DNSSEC_ECC
constant
Protocols.DNS.DNSSEC_RSASHA1
RSA/SHA1 RFC 3110.
constant
Protocols.DNS.DNSSEC_INDIRECT
constant
Protocols.DNS.DNSSEC_PRIVATEDNS
Private algorithm DNS-based RFC 4035 appendix A.1.1.
constant
Protocols.DNS.DNSSEC_PRIVATEOID
Private algorithm OID-based RFC 4035 appendix A.1.1.
constant
Protocols.DNS.DNSSEC_RSAMD5
RSA/MD5 RFC 2537.
Entry types
constant
Protocols.DNS.T_A
Type - host address
constant
Protocols.DNS.T_A6
constant
Protocols.DNS.T_AAAA
Type - IPv6 address record (RFC 1886)
constant
Protocols.DNS.T_AFSDB
Type - AFC database record (RFC 1183)
constant
Protocols.DNS.T_ANY
Type - ANY - A request for all records
constant
Protocols.DNS.T_APL
Type - Address Prefix List (RFC 3123)
constant
Protocols.DNS.T_ATMA
Type - ATM End System Address (af-saa-0069.000)
constant
Protocols.DNS.T_AXFR
Type - Authoritative Zone Transfer (RFC 1035)
constant
Protocols.DNS.T_CAA
Type - Certificate Authority Authorization (RFC 6844)
constant
Protocols.DNS.T_CERT
Type - Certificate Record (RFC 4398)
constant
Protocols.DNS.T_CNAME
Type - canonical name for an alias
constant
Protocols.DNS.T_DHCID
Type - DHCP identifier (RFC 4701)
constant
Protocols.DNS.T_DLV
Type - DNSSEC Lookaside Validation Record (RFC 4431)
constant
Protocols.DNS.T_DNAME
Type - Delegation Name (RFC 2672)
constant
Protocols.DNS.T_DNSKEY
Type - DNS Key record (RFC 4034)
constant
Protocols.DNS.T_DS
Type - Delegation Signer (RFC 4034)
constant
Protocols.DNS.T_EID
Type - Nimrod Endpoint IDentifier (draft)
constant
Protocols.DNS.T_UINFO
constant
Protocols.DNS.T_UID
constant
Protocols.DNS.T_GID
constant
Protocols.DNS.T_UNSPEC
constant
Protocols.DNS.T_GPOS
Type - Global Position (RFC 1712 Obsolete use LOC).
constant
Protocols.DNS.T_HINFO
Type - host information
constant
Protocols.DNS.T_HIP
Type - Host Identity Protocol (RFC 5205)
constant
Protocols.DNS.T_IPSECKEY
Type - IPsec Key (RFC 4025)
constant
Protocols.DNS.T_ISDN
Type - ISDN address (RFC 1183)
constant
Protocols.DNS.T_IXFR
Type - Incremental Zone Transfer (RFC 1996)
constant
Protocols.DNS.T_KX
Type - Key eXchanger record (RFC 2230)
constant
Protocols.DNS.T_LOC
Type - Location Record (RFC 1876)
constant
Protocols.DNS.T_MAILA
Type - Mail Agent (both MD and MF) (Obsolete - use MX)
constant
Protocols.DNS.T_MAILB
Type - Mail Box (MB, MG or MR) (Obsolete - use MX)
constant
Protocols.DNS.T_MB
Type - mailbox domain name (Obsolete)
constant
Protocols.DNS.T_MD
Type - mail destination (Obsolete - use MX)
constant
Protocols.DNS.T_MF
Type - mail forwarder (Obsolete - use MX)
constant
Protocols.DNS.T_MG
Type - mail group member (Obsolete)
constant
Protocols.DNS.T_MINFO
Type - mailbox or mail list information (Obsolete)
constant
Protocols.DNS.T_MR
Type - mail rename domain name (Obsolete)
constant
Protocols.DNS.T_MX
Type - mail exchange
constant
Protocols.DNS.T_NAPTR
Type - NAPTR (RFC 3403)
constant
Protocols.DNS.T_NIMLOC
Type - Nimrod Locator (draft)
constant
Protocols.DNS.T_NS
Type - authoritative name server
constant
Protocols.DNS.T_NSAP
Type - OSI Network Service Access Protocol (RFC 1348, RFC 1637 and RFC 1706)
constant
Protocols.DNS.T_NSAP_PTR
constant
Protocols.DNS.T_NSEC
Type - Next-Secure record (RFC 4034)
constant
Protocols.DNS.T_NSEC3
Type - NSEC record version 3 (RFC 5155)
constant
Protocols.DNS.T_NSEC3PARAM
Type - NSEC3 parameters (RFC 5155)
constant
Protocols.DNS.T_NULL
Type - null RR (Obsolete RFC 1035)
constant
Protocols.DNS.T_NXT
constant
Protocols.DNS.T_OPT
Type - Option (RFC 2671)
constant
Protocols.DNS.T_PTR
Type - domain name pointer
constant
Protocols.DNS.T_PX
Type - Pointer to X.400 mapping information (RFC 1664)
constant
Protocols.DNS.T_RP
Type - Responsible Person
constant
Protocols.DNS.T_RRSIG
Type - DNSSEC signature (RFC 4034)
constant
Protocols.DNS.T_RT
Type - Route Through (RFC 1183)
constant
Protocols.DNS.T_SIG
Type - Signature (RFC 2535)
constant
Protocols.DNS.T_SINK
Type - Kitchen Sink (draft)
constant
Protocols.DNS.T_SOA
Type - start of a zone of authority
constant
Protocols.DNS.T_SPF
Type - SPF - Sender Policy Framework (RFC 4408)
constant
Protocols.DNS.T_SRV
Type - Service location record (RFC 2782)
constant
Protocols.DNS.T_SSHFP
Type - SSH Public Key Fingerprint (RFC 4255)
constant
Protocols.DNS.T_TA
Type - DNSSEC Trust Authorities (draft)
constant
Protocols.DNS.T_TKEY
Type - Secret key record (RFC 2930)
constant
Protocols.DNS.T_TLSA
Type - TLSA certificate association (RFC 6698)
constant
Protocols.DNS.T_TSIG
Type - Transaction Signature (RFC 2845)
constant
Protocols.DNS.T_TXT
Type - text strings
constant
Protocols.DNS.T_WKS
Type - well known service description (Obsolete RFC 1123 and RFC 1127)
constant
Protocols.DNS.T_X25
Type - X25 PSDN address (RFC 1183)
Resource classes
constant
Protocols.DNS.C_ANY
Class ANY
constant
Protocols.DNS.C_CH
Class CHAOS
constant
Protocols.DNS.C_CS
Class CSNET (Obsolete)
constant
Protocols.DNS.C_HS
Class Hesiod
constant
Protocols.DNS.C_IN
Class Internet
Asynchronous DNS client.
inherit client : client
inherit Stdio.UDP : udp
void
close()
Close the client.
All active requests are aborted.
Protocols.DNS.async_client Protocols.DNS.async_client(
void
|string
|array
(string
) server
, void
|string
|array
(string
) domain
)
Request
do_query(string
domain
, int
cl
, int
type
, function
(string
, mapping
, __unknown__
... :void
) callback
, mixed
... args
)
Enqueue a new raw DNS request.
Returns a Request
object.
Pike versions prior to 8.0 did not return the Request
object.
void
generic_query(string
type
, string
domain
, function
(array
(string
)|zero
, __unknown__
... :void
) callback
, mixed
... restargs
)
Asynchronous DNS query with multiple results and a distinction between failure and empty results.
type
DNS query type. Currenlty supported:
| Return just IPv4 records. |
| Return both IPv6 and IPv4 records. |
| Reverse lookup for IP addresses, it expects normal
IP addresses for |
| Return TXT records. |
| Return MX records sorted by |
| Like querying for |
domain
The domain name we are querying. Add a trailing dot to prohibit domain-postfix searching.
callback
The callback function that receives the result of the DNS query.
It should be declared as follows:
void callback(array(string)|zero results, mixed ... restargs);
If the request fails it will return zero
for results
.
restargs
They are passed unaltered to the callback
function.
There is a notable difference between results
equal
to zero
(= request failed and can be retried) and
({})
(= request definitively answered the record
does not exist; retries are pointless).
This method uses the exact same heuristics as the standard DNS resolver library (regarding the use of /etc/hosts, and when to perform a domain-postfix search, and when not to (i.e. trailing dot)).
All queries sort automatically by preference (lowest numbers first).
Request
get_mx(string
host
, function
(array
(string
), __unknown__
... :void
) callback
, mixed
... args
)
Looks up the mx pointers for a host, and when done calls the function callback with the results as an array of strings. These can be host names, IP numbers, or a mix.
Returns a Request
object where progress can be observed
from the retries variable and the request can be cancelled
using the cancel
method.
variant
Concurrent.Future
get_mx(string
host
)
Looks up the mx pointers for a host. Returns a
Concurrent.Future
object that resolves into an array of
strings.
Request
get_mx_all(string
host
, function
(string
, array
(mapping
(string
:string
|int
)), __unknown__
... :void
) callback
, mixed
... args
)
Looks up the mx pointers for a host, and when done calls the function callback with the results as an array of mappings.
Returns a Request
object where progress can be observed
from the retries variable and the request can be cancelled
using the cancel
method.
variant
Concurrent.Future
get_mx_all(string
host
)
Looks up the mx pointers for a host. Returns a
Concurrent.Future
object that resolves into an array of
mappings.
Request
host_to_ip(string
host
, function
(string
, string
, __unknown__
... :void
) callback
, mixed
... args
)
Looks up the IPv4 address for a host, and when done calls the function callback with the host name and IP number as arguments.
Returns a Request
object where progress can be observed
from the retries variable and the request can be cancelled
using the cancel
method.
host_to_ips
variant
Concurrent.Future
host_to_ip(string
host
)
Looks up the IPv4 address for a host. Returns a
Concurrent.Future
object that resolves into the IP number as
a string, or 0 if it is missing.
host_to_ips
Request
host_to_ips(string
host
, function
(string
, array
, __unknown__
... :void
) callback
, mixed
... args
)
Looks up the IP number(s) for a host, and when done calls the function callback with the host name and array of IP addresses as arguments. If IPv6 and IPv4 addresses are both available, IPv6 addresses will be earlier in the array.
Returns a Request
object where progress can be observed
from the retries variable and the request can be cancelled
using the cancel
method.
variant
Concurrent.Future
host_to_ips(string
host
)
Looks up the IP number for a host. Returns a
Concurrent.Future
object that resolves into an array of
IP addresses as strings, or an empty array if it is missing.
Request
ip_to_host(string
ip
, function
(string
, string
, __unknown__
... :void
) callback
, mixed
... args
)
Looks up the host name for an IP number, and when done calls the function callback with the IP number adn host name as arguments.
Returns a Request
object where progress can be observed
from the retries variable and the request can be cancelled
using the cancel
method.
variant
Concurrent.Future
ip_to_host(string
ip
)
Looks up the host name for an IP number. Returns a
Concurrent.Future
object that resolves into the host name, or
0 if it is missing.
private
void
low_generic_query(int
restrictsearch
, string
type
, string
domain
, function
(array
(string
)|zero
, __unknown__
... :void
) callback
, mixed
... restargs
)
restrictsearch
| Try |
| Try |
| Just try an unaltered query on the DNS servers. |
Both an async_client
and an async_tcp_client
.
inherit async_tcp_client : TCP
inherit async_client : UDP
Request
do_query(string
domain
, int
cl
, int
type
, function
(string
, mapping
, __unknown__
... :void
) callback
, mixed
... args
)
Asynchronous DNS client using TCP
inherit async_client : async_client
Request
do_query(string
domain
, int
cl
, int
type
, function
(string
, mapping
, __unknown__
... :void
) callback
, mixed
... args
)
inherit ::this_program : this_program
Synchronous DNS client.
inherit protocol : protocol
Protocols.DNS.client Protocols.DNS.client()
Protocols.DNS.client Protocols.DNS.client(
void
|string
|array
server
, void
|int
|array
domain
)
mapping
|zero
do_sync_query(string
s
)
Perform a synchronous DNS query.
s
Result of Protocols.DNS.protocol.mkquery
mapping containing query result or 0 on failure/timeout
// Perform a hostname lookup, results stored in r->an object d=Protocols.DNS.client(); mapping r=d->do_sync_query(d->mkquery("pike.lysator.liu.se", C_IN, T_A));
array
(string
)|zero
get_mx(string
host
)
string
get_primary_mx(string
hostname
)
Queries the primary mx for the host.
Returns the hostname of the primary mail exchanger.
array
gethostbyaddr(string
hostip
)
Queries the host name or ip from the default or given DNS server. The result is an array with three elements,
The requested data about the specified host.
Array | |
| The host IP. |
| IP number(s). |
| DNS name(s). |
array
gethostbyname(string
hostname
)
Queries the host name from the default or given DNS server. The result is an array with three elements,
An array with the requested information about the specified host.
Array | |
| Hostname. |
| IP number(s). |
| DNS name(s). |
Prior to Pike 7.7 this function only returned IPv4 addresses.
array
getsrvbyname(string
service
, string
protocol
, string
|void
name
)
Queries the service record (RFC 2782) from the default or given DNS server. The result is an array of arrays with the following six elements for each record. The array is sorted according to the priority of each record.
Each element of the array returned represents a service record. Each service record contains the following:
An array with the requested information about the specified service.
Array | |
| Priority |
| Weight in event of multiple records with same priority. |
| port number |
| target dns name |
array
(string
)|zero
match_etc_hosts(string
host
)
Return /etc/hosts records
string
Protocols.DNS.client.Request.domain
string
Protocols.DNS.client.Request.req
function
(string
, mapping
|zero
, __unknown__
... :void
)|zero
Protocols.DNS.client.Request.callback
array
(mixed
) Protocols.DNS.client.Request.args
protected
local
void
__create__(string
domain
, string
req
, function
(string
, mapping
|zero
, __unknown__
... :void
)|zero
callback
, array
(mixed
) args
)
void
cancel()mixed
Protocols.DNS.client.Request.retry_co
Cancel the current request.
Protocols.DNS.client.Request Protocols.DNS.client.Request(
string
domain
, string
req
, function
(string
, mapping
|zero
, __unknown__
... :void
)|zero
callback
, array
(mixed
) args
)
Both a client
and a tcp_client
.
inherit tcp_client : TCP
inherit client : UDP
mapping
do_sync_query(string
s
)
This is both a server
and tcp_server
.
inherit tcp_server : TCP
inherit server : UDP
Low level DNS protocol
array
decode_entries(string
s
, int
num
, array
(int
) next
)
Decode a set of entries from an answer.
s
Encoded entries.
num
Number of entires in s
.
next
Array with a single element containing the start position in s
on entry and the continuation position on return.
Returns an array of mappings describing the decoded entires:
Array | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Mapping describing a single entry:
Depending on the type of entry the mapping may contain different additional fields:
|
string
mkquery(string
|mapping
dnameorquery
, int
|void
cl
, int
|void
type
)
create a DNS query PDU
dnameorquery
cl
record class such as Protocols.DNS.C_IN
type
query type such Protocols.DNS.T_A
data suitable for use with
Protocols.DNS.client.do_sync_query
// generate a query PDU for a address lookup on the hostname pike.lysator.liu.se string q=Protocols.DNS.protocol()->mkquery("pike.lysator.liu.se", Protocols.DNS.C_IN, Protocols.DNS.T_A);
Base class for implementing a Domain Name Service (DNS) server operating over UDP.
This class is typically used by inheriting it,
and overloading reply_query()
and handle_response()
.
dual_server
inherit server_base : server_base
Protocols.DNS.server Protocols.DNS.server()
Protocols.DNS.server Protocols.DNS.server(
int
port
)
Protocols.DNS.server Protocols.DNS.server(
string
ip
)
Protocols.DNS.server Protocols.DNS.server(
string
ip
, int
port
)
Protocols.DNS.server Protocols.DNS.server(
string
ip
, int
port
, string
|int
... more
)
Open one or more new DNS server ports.
ip
The IP to bind to. Defaults to "::"
or 0
(ie ANY)
depending on whether IPv6 support is present or not.
port
The port number to bind to. Defaults to 53
.
more
Optional further DNS server ports to open.
Must be a set of ip
, port
argument pairs.
Base class for server
, tcp_server
.
inherit protocol : protocol
protected
void
handle_decode_error(mapping
err
, mapping
m
, Stdio.UDP
|object
udp
)
Respond to a query that cannot be decoded.
This method exists so that servers can override the default behaviour.
protected
void
handle_query(mapping
q
, mapping
m
, Stdio.UDP
|object
udp
)
Handle a query.
This function calls reply_query()
,
and dispatches the result to send_reply()
.
protected
void
handle_response(mapping
r
, mapping
m
, Stdio.UDP
|object
udp
)
Handle a query response (stub).
Overload this function to handle responses to possible recursive queries.
protected
void
rec_data(mapping
m
, Stdio.UDP
|object
udp
)
Low-level DNS-data receiver.
This function receives the raw DNS-data from the Stdio.UDP
socket
or TCP connection object udp
, decodes it, and dispatches the decoded
DNS request to handle_query()
and handle_response()
.
protected
mapping
|zero
reply_query(mapping
query
, mapping
udp_data
, function
(mapping
:void
) cb
)
Reply to a query (stub).
query
Parsed query.
udp_data
Raw UDP data. If the server operates in TCP mode (tcp_server
),
it will contain an additional tcp_con entry. In that case,
udp_data->tcp_con->con
will contain the TCP connection the
request was received on as Stdio.File
object.
cb
Callback you can call with the result instead of returning it.
In that case, return 0
(zero).
Overload this function to implement the proper lookup.
To indicate the default failure cb
must be called with an
argument of 0
(zero), and 0
(zero) be returned.
Returns 0
(zero) when the cb
callback will be used,
or a result mapping if not:
| 0 (or omit) for success, otherwise one of the Protocols.DNS.* constants | |||||||
| Answer section:
| |||||||
| Question section, same format as | |||||||
| Authority section (usually NS records), same format as | |||||||
| Additional section, same format as | |||||||
| Set to 1 to include the Authoritative Answer bit in the response | |||||||
| Set to 1 to include the TrunCated bit in the response | |||||||
| Set to 1 to include the Recursion Desired bit in the response | |||||||
| Set to 1 to include the Recursion Available bit in the response | |||||||
| Set to 1 to include the Checking Disabled bit in the response | |||||||
| Set to 1 to include the Authenticated Data bit in the response |
protected
void
report_decode_error(mixed
err
, mapping
m
, Stdio.UDP
|object
udp
)
Report a failure to decode a DNS request.
The default implementation writes a backtrace to stderr. This method exists so that derived servers can replace it with more appropriate error handling for their environment.
Synchronous DNS client using TCP
Can handle larger responses than client
can.
inherit client : client
mapping
|zero
do_sync_query(string
s
)
Perform a synchronous DNS query.
s
Result of Protocols.DNS.protocol.mkquery
mapping containing query result or 0 on failure/timeout
// Perform a hostname lookup, results stored in r->an object d=Protocols.DNS.tcp_client(); mapping r=d->do_sync_query(d->mkquery("pike.lysator.liu.se", C_IN, T_A));
Base class for implementing a Domain Name Service (DNS) server operating over TCP.
This class is typically used by inheriting it,
and overloading reply_query()
and handle_response()
.
inherit server_base : server_base
Protocols.DNS.tcp_server Protocols.DNS.tcp_server()
Protocols.DNS.tcp_server Protocols.DNS.tcp_server(
int
port
)
Protocols.DNS.tcp_server Protocols.DNS.tcp_server(
string
ip
)
Protocols.DNS.tcp_server Protocols.DNS.tcp_server(
string
ip
, int
port
)
Protocols.DNS.tcp_server Protocols.DNS.tcp_server(
string
ip
, int
port
, string
|int
... more
)
Open one or more new DNS server ports.
ip
The IP to bind to. Defaults to "::"
or 0
(ie ANY)
depending on whether IPv6 support is present or not.
port
The port number to bind to. Defaults to 53
.
more
Optional further DNS server ports to open.
Must be a set of ip
, port
argument pairs.
This class contains nice abstractions for calls into the server. They are named "call", "async_call" or "async_cb_call", depending on how you want the call to be done.
int
Protocols.LysKOM.Connection.protocol_level
string
Protocols.LysKOM.Connection.session_software
string
Protocols.LysKOM.Connection.software_version
Description of the connected server.
mixed
XXX(mixed
... args
)
object
async_XXX(mixed
... args
)
object
async_cb_XXX(function
(:void
) callback
, mixed
... args
)
Perform a call to the server. This actually
clones a Protocols.LysKOM.Request
object,
and initializes it. XXX is to be read as
one of the calls in the lyskom protocol. ('-' is replaced
with '_'.) (ie, logout, async_login or async_cb_get_conf_stat.)
The first variant is a synchronous call. This will send the command, wait for the server to execute it, and then return the result.
The last two are asynchronous calls, returning an
initialized Protocols.LysKOM.Request
object.
Protocols.LysKOM.Connection Protocols.LysKOM.Connection(
string
server
)
Protocols.LysKOM.Connection Protocols.LysKOM.Connection(
string
server
, mapping
options
)
The options
argument is a mapping with the following members:
| login as this person number (get number from name). |
| send this login password. |
| if set, login invisible. |
| server port (default is 4894). |
| present as this user (default is from uid/getpwent and hostname). |
object
Protocols.LysKOM.Session.user
This variable contains the
Protocols.LysKOM.Session.Person
that is logged in.
Conference
conference(int
no
)
Returns conference number no
.
Protocols.LysKOM.Session Protocols.LysKOM.Session(
string
server
)
Protocols.LysKOM.Session Protocols.LysKOM.Session(
string
server
, mapping
options
)
Initializes the session object, and opens a connection to that server.
options
is a mapping of options:
| login as this person number (get number from name). |
| create a new person and login with it. |
| send this login password. |
| if set, login invisible. |
| server port (default is 4894). |
| present as this user (default is from uid/getpwent and hostname). |
Connection
object
create_person(string
name
, string
password
)
Create a person, which will be logged in. returns the new person object
object
create_text(string
subject
, string
body
, mapping
options
)
object
create_text(string
subject
, string
body
, mapping
options
, function
(:void
) callback
, mixed
... extra
)
Creates a new text.
if callback
is given, the function will be called when the text
has been created, with the text as first argument.
Otherwise, the new text is returned.
options
is a mapping that may contain:
| recipient conferences. |
| cc-recipient conferences. |
| bcc-recipient conferences*. |
| The text(s) to be commented. |
| The text(s) to be footnoted. |
| send text anonymously. |
| AuxItems you want to set for the text*. |
The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.
Conference.create_text()
, Text.comment()
, Text.footnote()
object
login(int
user_no
, string
password
)
object
login(int
user_no
, string
password
, int
invisible
)
Performs a login. Throws a lyskom error if unsuccessful.
The session object logged in.
this_program
logout()
Logouts from the server. returns the called object
Person
person(int
no
)
Returns the Person
no
.
void
register_async_message_callback(function
(int
, int
, string
:void
) cb
)
object
|void
send_message(string
textstring
, mapping
options
)
Sends a message.
options
is a mapping that may contain:
| recipient conference. |
Text
text(int
no
)
Returns the text no
.
array
(ProtocolTypes.ConfZInfo
) try_complete_person(string
orig
)
Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.
Undocumented
inherit ProtocolTypes.AuxItemInput : AuxItemInput
Undocumented
mixed
Protocols.LysKOM.Session.Conference.prefetch_stat
int
Protocols.LysKOM.Session.Conference.no
object
Protocols.LysKOM.Session.Conference.error
Text
Protocols.LysKOM.Session.Conference.msg_of_day
Conference
Protocols.LysKOM.Session.Conference.supervisor
Conference
Protocols.LysKOM.Session.Conference.permitted_submitters
Conference
Protocols.LysKOM.Session.Conference.super_conf
Person
Protocols.LysKOM.Session.Conference.creator
mixed
Protocols.LysKOM.Session.Conference.aux_items
mixed
Protocols.LysKOM.Session.Conference.name
mixed
Protocols.LysKOM.Session.Conference.type
mixed
Protocols.LysKOM.Session.Conference.creation_time
mixed
Protocols.LysKOM.Session.Conference.last_written
mixed
Protocols.LysKOM.Session.Conference.nice
mixed
Protocols.LysKOM.Session.Conference.no_of_members
mixed
Protocols.LysKOM.Session.Conference.first_local_no
mixed
Protocols.LysKOM.Session.Conference.no_of_texts
mixed
Protocols.LysKOM.Session.Conference.presentation
Undocumented
Protocols.LysKOM.Session.Conference Protocols.LysKOM.Session.Conference(
int
no
)
All variables in this class is read only.
object
Protocols.LysKOM.Session.Membership.added_at
object
Protocols.LysKOM.Session.Membership.conf
int
Protocols.LysKOM.Session.Membership.last_text_read
object
Protocols.LysKOM.Session.Membership.last_time_read
int
Protocols.LysKOM.Session.Membership.position
int(8bit)
Protocols.LysKOM.Session.Membership.priority
array
(int
) Protocols.LysKOM.Session.Membership.read_texts
multiset
(string
) Protocols.LysKOM.Session.Membership.type
int
number_unread()
void
query_read_texts()
array
(object
) unread_texts()
object
Protocols.LysKOM.Session.Person.error
Text
Protocols.LysKOM.Session.Person.user_area
mixed
Protocols.LysKOM.Session.Person.username
mixed
Protocols.LysKOM.Session.Person.privileges
mixed
Protocols.LysKOM.Session.Person.flags
mixed
Protocols.LysKOM.Session.Person.last_login
mixed
Protocols.LysKOM.Session.Person.total_time_present
mixed
Protocols.LysKOM.Session.Person.sessions
mixed
Protocols.LysKOM.Session.Person.created_lines
mixed
Protocols.LysKOM.Session.Person.created_bytes
mixed
Protocols.LysKOM.Session.Person.read_texts
mixed
Protocols.LysKOM.Session.Person.no_of_text_fetches
mixed
Protocols.LysKOM.Session.Person.created_persons
mixed
Protocols.LysKOM.Session.Person.created_confs
mixed
Protocols.LysKOM.Session.Person.first_created_local_no
mixed
Protocols.LysKOM.Session.Person.no_of_created_texts
mixed
Protocols.LysKOM.Session.Person.no_of_marks
mixed
Protocols.LysKOM.Session.Person.no_of_confs
mixed
Protocols.LysKOM.Session.Person.unread
int(0)
Protocols.LysKOM.Session.Person.clear_membership
mixed
Protocols.LysKOM.Session.Person.membership
Undocumented
int
Protocols.LysKOM.Session.Person.no
mixed
Protocols.LysKOM.Session.Person.prefetch_stat
mixed
Protocols.LysKOM.Session.Person.prefetch_conf
mixed
Protocols.LysKOM.Session.Person.prefetch_membership
Undocumented
Protocols.LysKOM.Session.Person Protocols.LysKOM.Session.Person(
int
no
)
All variables in this class is read only.
Undocumented
string
Protocols.LysKOM.Session.Text.author
The author of the text.
mixed
Protocols.LysKOM.Session.Text.prefetch_text
mixed
Protocols.LysKOM.Session.Text.prefetch_stat
mixed
Protocols.LysKOM.Session.Text.lines
mixed
Protocols.LysKOM.Session.Text.characters
mixed
Protocols.LysKOM.Session.Text.clear_stat
mixed
Protocols.LysKOM.Session.Text.aux_items
Undocumented
mixed
Protocols.LysKOM.Session.Text.creation_time
The time the text was created on the server.
object
Protocols.LysKOM.Session.Text.err
Undocumented
int
Protocols.LysKOM.Session.Text.marks
The number of marks on this text.
mixed
Protocols.LysKOM.Session.Text.misc
Misc info, including what conferences the message is posted to.
Needs a more complete description.
int
Protocols.LysKOM.Session.Text.no
The text number, as spicified to create
.
string
Protocols.LysKOM.Session.Text.subject
The message subject.
string
Protocols.LysKOM.Session.Text.text
The actual text (or body if you wish).
Protocols.LysKOM.Session.Text Protocols.LysKOM.Session.Text(
string
textnumber
)
Initializes a Text object.
void
mark_as_read()
Undocumented.
Data types as defined by the LysKOM protocol specification.
This module contains nice abstractions for calls into the server. They are named "call", "async_call" or "async_cb_call", depending on how you want the call to be done.
This is the base class for lyskom requests. All lyskom request classes inherit this class.
object
Protocols.LysKOM.Request._Request.error
How the call failed.
The call has completed if (ok||error)
.
bool
Protocols.LysKOM.Request._Request.ok
Tells if the call has executed ok
void
_async(int
call
, mixed_data
)
mixed
_sync(int
call
, mixed_data
)
Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.
mixed
_reply(object
|array
what
)
mixed
reply(object
|array
what
)
_reply()
is called as callback to evaluate the result,
and calls reply()
in itself to do the real work.
mixed
res = Protocols.LysKOM.Request._Request()
()
Wait for the call to finish.
void
async(mixed
... args
)
mixed
sync(mixed
... args
)
Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. This calls indata() in itself, to get the correct arguments to the lyskom protocol call.
DHT implementation for bittorrent Implemented BEPs*: [X] BEP005 DHT Protocol [ ] BEP032 IPv6 extension for DHT [ ] BEP033 DHT scrape [ ] BEP042 DHT security extensions [ ] BEP043 Read-only DHT nodes [ ] BEP044 Storing arbitrary data in the DHT [ ] BEP045 Multiple-address operation for the Bittorrent DHT
*) See http://bittorrent.org/beps/bep_0000.html for a list of all BEPs
int
Protocols.Bittorrent.DHT.MAX_PEERS_PER_HASH
Maximum number of peers per hash that we store.
int
Protocols.Bittorrent.DHT.PEER_TABLE_MAX_SIZE
Maximum number hashes we store data for in this node.
mapping
(string
:mixed
) Protocols.Bittorrent.DHT.callbacks_by_txid
mapping
(string
:mixed
) Protocols.Bittorrent.DHT.request_timeouts
Keep track of callbacks by transaction id
mapping
(string
:function
(:void
)) Protocols.Bittorrent.DHT.command_handlers
Mapping of query names to handlers. Allows for extensions to be implemented.
int
Protocols.Bittorrent.DHT.is_running
Indicates if the DHT instance is up and running or not.
protected
string
|zero
Protocols.Bittorrent.DHT.my_node_id
Our global ID for this DHT router, expressed as a 20 byte hash.
mapping
(string
:mapping
) Protocols.Bittorrent.DHT.peers_by_hash
Peers we know of.
Stdio.UDP
|zero
Protocols.Bittorrent.DHT.port
The UDP port on which we listen for messages.
DHTNode
add_node(string
|DHTNode
n
, void
|string
ip
, void
|int
port
)
Gateway into the routing table for now. This is in preparation for BEP045.
void
add_peer_for_hash(Peer
n
, string
hash
, string
ip
, int
port
)
Insert a peer for a hash in our table of known peers. Ignores the request if the given node is already a peer for the given hash.
void
announce(string
hash
, int
port
)
Announce a hash to the world on the given port.
This is done by executing a get_peers request to the DHT and then announcing to the K closest nodes to that hash.
protected
void
announce_to(string
peer_ip
, int
peer_port
, string
token
, string
info_hash
, int
announced_port
, void
|int
implied_port
)
This is the internal announce callback - it is called for each node that we should send an announcement to.
Protocols.Bittorrent.DHT Protocols.Bittorrent.DHT(
void
|string
my_node_id
)
Create a new DHT instance with an optional predefined node id.
string
distance(string
h1
, string
h2
)
Calculate the distance between two hashes using XOR. Fails unless both h1 and h2 are strings of the same length.
int
distance_exp(string
h1
, string
h2
)
Calculate the order of magnitude of the distance. Basically count leading zeros...
string
generate_node_id()
Generate a 160 bit node id.
Token
generate_token_for(string
ip
, int
port
, void
|int
dont_sha1
)
Generate a token for a specific node. If it fails to generate a unique token for this request, it will return UNDEFINED, otherwise a string token is returned.
string
generate_txid()
Generates suitable transaction ids making sure to not collide with existing ones.
string
get_node_id()
Allows outsiders to examine the node id of this instance.
void
handle_announce_peer(mapping
data
, string
ip
, int
port
)
Handles other peers announcing to us for safekeeping.
void
handle_find_node(mapping
data
, string
ip
, int
req_port
)
Handles request for nodes closer to a hash.
void
handle_get_peers(mapping
data
, string
ip
, int
port
)
Returns peers to the requestor or our closest nodes if we don't know of any peers.
void
handle_ping(mapping
data
, string
ip
, int
port
)
Handles PONG responses to incoming PINGs.
void
handle_unknown_method(mapping
data
, string
ip
, int
port
)
Responds to unknown methods. Currently does nothing at all.
mapping
info()
Returns some basic information about this DHT instance.
protected
void
read_callback(mapping
(string
:int
|string
) datagram
, mixed
... extra
)
Called when we recieve a datagram on the UDP port we are listening to.
protected
void
read_timeout(string
txid
)
Internal timeout method to ensure we don't wait forever on responses from nodes that are no longer available.
Note: The timeout is not propagated to higher levels, so callers cannot rely on the send_dht_query() callback to propagate this.
string
send_dht_query(string
to
, int
dstport
, mapping
data
, void
|function
(:void
) response_callback
, mixed
... args
)
Sends a DHT query and calls the callback when a response is recieved or when a timeout occurs.
int
send_dht_request(string
to
, int
dstport
, mapping
data
)
Do the actual sending part... No timeout handling or etherwise - just send the message.
Returns the TXID if the message was sent successfully and UNDEFINED if not.
string
send_ping(string
ip
, int
port
, function
(mapping
, string
, int
:void
) cb
)
Sends a PING to a remote port and calls the callback cb if we get a response.
void
set_node_id(string
my_node_id
)
Sets the node id of this instance. This has implications for the routing table, so we need to reinitialize it if this happens...
void
start(int
port
, void
|string
bind_address
)
Start up the DHT instance.
void
stop()
Stop the DHT instance. When the instance is stopped, it will close its port and therefore stop responding to queries. It will not destroy the DHT routing table or other states that could be reused if the DHT instance is started back up.
Token
token_by_endpoint(string
ip
, int
port
)
Returns a token object for the given ip/port if one exists.
constant
Protocols.Bittorrent.DHT.DHT_GENERIC_ERROR
constant
Protocols.Bittorrent.DHT.DHT_SERVER_ERROR
constant
Protocols.Bittorrent.DHT.DHT_PROTOCOL_ERROR
constant
Protocols.Bittorrent.DHT.DHT_UNKNOWN_METHOD
constant
Protocols.Bittorrent.DHT.DHT_QUERY_TIMEOUT
Represents a node in our routing table. These nodes also have a state compared to the Node class above along with some other fancy stuff.
inherit Node : Node
int
Protocols.Bittorrent.DHT.DHTNode.age
Time since last response seen from this node
Read only
void
activity()
Call when we see activity from this node to ensure it returns to good standing. Will set the node state to DHT_ACTIVE, update last_response and set ping_fails to 0.
void
cancel_check_node()
Removes any outstanding callouts to check the node.
string
compact_node_info()
Returns the compact node info for this node.
mapping
node_info()
Extend the Node::node_info() method to include info relevant to a DHTNode.
mapping
node_info_human()
Human readable output version of the node_info
method.
string
node_state()
Returns the node state as a string.
void
ping()
Ping the node to see if it is still responding.
protected
void
ping_timeout(string
txid
)
Called when a ping request to this peer times out. We set the state to DHT_BAD and leave it at that.
protected
void
remove_txid(string
txid
)
Removes an outstanding ping TXID from the pings_inflight mapping.
constant
Protocols.Bittorrent.DHT.DHTNode.DHT_UNKNOWN
constant
Protocols.Bittorrent.DHT.DHTNode.DHT_BAD
constant
Protocols.Bittorrent.DHT.DHTNode.DHT_ACTIVE
Base class for operations that need to iterate over the DHT in some way like get_peers and find_node.
int
Protocols.Bittorrent.DHT.DHTOperation.desired_results
Desired number of results before the op considers itself done
string
Protocols.Bittorrent.DHT.DHTOperation.target_hash
function
(:void
)|zero
Protocols.Bittorrent.DHT.DHTOperation.done_cb
array
(mixed
) Protocols.Bittorrent.DHT.DHTOperation.done_cb_args
int
Protocols.Bittorrent.DHT.DHTOperation.max_no_requests
Maximum number of requests that may be generated before bailing out.
int(0..)
Protocols.Bittorrent.DHT.DHTOperation.max_outstanding_requests
Maximum number of concurrent requests allowed
float
|int
Protocols.Bittorrent.DHT.DHTOperation.query_timeout_period
Timeout for the query
int
Protocols.Bittorrent.DHT.DHTOperation.reqs
Number of requests generated by this query
array
Protocols.Bittorrent.DHT.DHTOperation.result
Result of the operation to be inspected by the done callback. Content of the result array varies depending on the concrete implementation of the operation
int
Protocols.Bittorrent.DHT.DHTOperation.result_count
Result counter - may differ from actual number of objects in the result array in some cases. For example in the get_peers query, closest nodes may be added in addition to any peers found.
protected
local
void
__create__(string
target_hash
, function
(:void
)|zero
done_cb
, mixed
... done_cb_args
)
void
add_node_to_query(Node
n
)
Add a node to the list of nodes to query.
Protocols.Bittorrent.DHT.DHTOperation Protocols.Bittorrent.DHT.DHTOperation(
string
target_hash
, function
(:void
)|zero
done_cb
, mixed
... done_cb_args
)
private
void
do_query_peer(Node
peer
)
Create a request to the peer info given. The peer info array is expected to contain peer hash, peer ip, peer port.
protected
void
done()
Internal done callback called when the operation finishes. The main purpose of this callback is to simply call the application level callback but in some cases it can also be used to modify the result before calling the application callback.
this_program
execute()
Execute the DHTOperation by ensuring there are nodes in the
nodes_to_query array as well as calling run
. If this method
is overridden, it should always call the parent execute methods!
protected
mapping
generate_query()
This method should be overridden by the actual handlers for the operation.
private
void
got_response_cb(mapping
resp
)
Callback when we get responses. This is private to the DHTOperation class and should not be overridden. Instead override the got_response method declared above.
int
is_done()
This method will return 1 if we consider ourselves done. This
should result in the done
method being called. Typically, we
are done if there are no transactions in flight.
private
void
query_timeout(string
txid
)
Called when a transaction ID has been in flight for too long and
we want to stop waiting for an answer. We call run
to
ensure we continue processing requests if more are needed.
private
void
run()
Processes the queue of nodes to query and calls done
if we
have enough results or there are no transactions in flight.
This is the method called to initiate a query.
int
want_more_results()
This method returns 1 if we want more results. This will control
if we send out more requests or if we just let the ones in
flight finish before calling the done
callback.
FindNode implements the find_node query on the DHT.
Upon completion, the callback given at instance creation will be called and the result can be found in the results array.
For this operation, the results array will contain Node objects. In some cases these objects may also be DHTNode objects, but the callback must not expect this.
inherit DHTOperation : DHTOperation
int
Protocols.Bittorrent.DHT.FindNode.desired_results
Override the default number of desired results
this_program
execute()
Execute method that also checks if we have the targets in our routing table.
protected
mapping
generate_query()
Callback called by parent to generate the query for this operation
The GetPeers class is used to initiate queries to the DHT where peers for a hash is desired. Upon completion, the done_db will be called with the GetPeers instance as the first argument and the done_cb_args as the following arguments.
The done_cb function is expected to examine the results array to find out what the result of the query actually contains. For this query, the result array will be an array with two elements; the first one containing any responses from nodes that knows of peers and the second one will contain the closest nodes to the target hash that we saw during the query.
inherit DHTOperation : DHTOperation
array
Protocols.Bittorrent.DHT.GetPeers.closest_nodes
Sorted array of the closest K nodes we've seen in the query.
int
Protocols.Bittorrent.DHT.GetPeers.desired_results
Override the default number of desired results
void
done()
Add the closest nodes we know of and call the callback.
protected
mapping
generate_query()
Implementation of DHTNode:generate_query
that returns a
get_peers query.
Utility class that represents a node that we learned of somehow. Node objects are not part of the DHT yet but can be used to create fullfledged DHTNode objects.
string
endpoint()
Returns the node endpoint as plain text
string
endpoint_compact()
Returns just the IP and port as an 8-bit string.
mapping
(string
:mixed
) node_info()
Return basic info about the node as a mapping. All values are human readable.
mapping
(string
:mixed
) node_info_human()
Like node_info
but encodes node id and token as hex-strings.
Information about the peeer for a hash
inherit Node : Node
Abstraction for the routing table.
function
(DHTNode
:int
) Protocols.Bittorrent.DHT.Routingtable.allow_node_in_routing_table
Callback method that determines if a peer is allowed into our routing table or not. Return 1 to allow the peer or 0 to ignore it.
mapping
(string
:Bucket
) Protocols.Bittorrent.DHT.Routingtable.bucket_by_uuid
array
(Bucket
) Protocols.Bittorrent.DHT.Routingtable.buckets
Buckets in our routing table
protected
string
|zero
Protocols.Bittorrent.DHT.Routingtable.my_node_id
Node ID that this routing table belongs to
mapping
(string
:DHTNode
) Protocols.Bittorrent.DHT.Routingtable.nodes_by_hash
mapping
(string
:DHTNode
) Protocols.Bittorrent.DHT.Routingtable.nodes_by_endpoint
Lookup table for nodess so we can quickly find out if any given hash is already in our table somewhere.
DHTNode
add_node(string
|DHTNode
n
, void
|string
ip
, void
|int
port
)
Attepmts to add a node to our routing table. If a node with the same hash and/or endpoint already exists, that node is returned instead. If this node is inserted into the routing table, it is returned. If the node could not be inserted at all, UNDEFINED is returned.
Bucket
bucket_for(string
|DHTNode
n
)
Calculate and return the bucket in which DHTNode n should belong to.
void
copy_from(this_program
rt
)
Iterate over the given routingtable, copying the nodes as we go along.
void
deserialize(array
(mapping
) nodes
)
Deserialize an array created by serialize
.
array
serialize()
Serialize the routing table into basic types so that it may be encoded for storage
int
split_bucket(Bucket
b
, void
|int
dont_promote
)
Splits the given bucket into two by pushing a new bucket to the end of the bucket array. All nodes in the given bucket are removed and re-added to redistribute them. Candidate nodes are also readded and then a separate promotion pass is done. The promotion pass can be inhibited by setting dont_promote to 1.
int
add_node(DHTNode
n
, void
|int
dont_notify
)
Attempts to add a node to the bucket either as a live node or as a candidate if the bucket is already full. Optionally supresses notifications of the new node. Returns 0 if the node was successfully added.
mapping
details()
Returns a mapping with details about the bucket, including a complete list of live and candidate nodes.
void
evict_bad_nodes()
Used to evict bad nodes from the bucket. Used by add_node() before attempting to add nodes the bucket.
mapping
info()
returns a mapping with overall information about the bucket.
bool
is_full()
Returns 1 if the bucket is full of live nodes.
protected
int
low_add_candidate(DHTNode
n
, void
|int
dont_notify
)
Adds a node to the bucket as a candidate with the option of suppressing notifications. Returns 0 on success.
int
low_add_node(DHTNode
n
, void
|int
dont_notify
)
Adds a node to the bucket as a live node with the option to surpress notifications. Returns 0 on success.
void
promote_nodes()
Attempts to promote nodes if there is space and we have candidates. Called by add_node() before adding a node to ensure we upgrade viable candidates before adding a new node. This ensures that new nodes starts their life in the candidates section until there is space for them.
int
remove_node(DHTNode
n
, void
|int
dont_notify
)
Remove a node from this bucket and optionally surpress notification of the event. Returns 0 if the node was successfully removed.
Protocols.Bittorrent.DHT.Token Protocols.Bittorrent.DHT.Token(
string
ip
, int
port
, void
|int
dont_sha1
)
Generate a new token for the given IP/port. Optionally don't apply SHA1 to the token for debugging purposes.
Token
invalidate()
Invalidates a token if it exists,
this_program
refresh()
Refreshes a token's lifetime to the configured token_lifetime value. Note: If called on an old token, this will violate recommendations in BEP005.
int
valid_for(string
ip
, int
port
)
Checks if a token is valid for a given node. This is done by checking that we handed out the token to the IP/port that attempts to use it.
Generate a .torrent binary string from files in the filesystem
// usage: thisprogram [<file/dir>] [<file/dir>...] <target .torrent> int main(int ac,array am) { Generator g=Generator(); foreach (am[1..<1];;string f) g->add(f);
string dest=am[-1]; if (-1==search(dest,"torrent")) dest+=".torrent";
Stdio.write_file(dest,g->digest()); return 0; }
inherit .Torrent : Torrent
this_program
add(string
path
, void
|string
base
)
Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.
this_program
add_announce(string
|array
(string
) announce_url
)
Add one or multiple announcers (trackers). This is needed to get a valid .torrent file. If this is called more then once, more announcers (trackers) will be added with lower priority.
this_program
add_directory_tree(string
path
, void
|string
dirbase
)
Add a directory tree to the torrent. The second argument is what the directory will be called in the torrent. This will call add_file on all non-directories in the tree.
this_program
add_file(string
path
, void
|string
filename
)
Add a file to the torrent. The second argument is what the file will be called in the torrent.
void
build_sha1s(void
|function
(int
, int
:void
) progress_callback
)
Build the SHA hashes from the files.
Protocols.Bittorrent.Generator Protocols.Bittorrent.Generator(
void
|string
base
, void
|int
piece_size
)
Create a generator.
base
The base filename/path in the torrent.
piece_size
The size of the pieces that the SHA hashes are calculated on. Default 262144 and this value should probably be 2^n.
string
digest(void
|function
(int
, int
:void
) progress_callback
)
Finally make a torrent string out of this information. Will call build_sha1's if the sha1's aren't generated already.
progress_callback
is called with (pos,of) arguments, similar
to Torrent.verify_targets
.
void
connect()
Connect to the peer; this is done async.
status/mode will change from "connecting"
to
"dead"
or to "connected"
depending on result.
Will throw error if already online.
Upon connect, protocol will be initiated in choked mode.
When the protocol is up, status will change to "online"
(or "failed"
if the handshake failed).
void
disconnect()
Disconnect a peer.
Does nothing if we aren't online.
status/mode will change to "disconnected"
,1 if we were online.
multiset
(int
) downloading_pieces()
Returns as multiset what this peer is downloading.
int
is_activated()
Returns true if this peer is activated, as in we're downloading from it.
int
is_available()
Returns true if this peer is available, as in we can use it to download stuff.
int
is_choked()
Returns true if this peer is choking, as in doesn't send more data to us.
int
is_completed()
Returns true if this peer is completed, as in has downloaded everything already - and we shouldn't need to upload to get stuff.
int
is_connectable()
Returns true if we can connect to this peer, when new or disconnected but not fatally.
int
is_online()
Returns true if this peer is online and connected.
int
is_strangled()
Returns true if this peer is strangled; as in we don't want to upload more, because we're not getting any back.
void
request(int
piece
, int
offset
, int
bytes
, function
(int
, int
, string
, object
:void
|mixed
) callback
)
Called to request a chunk from this peer.
void
send_have(int
n
)
Send a have message to tell I now have piece n. Ignored if not online.
void
status(string
type
, void
|int
|string
data
)
Called whenever there is a status change for this peer.
Always called with "created"
when the object is created.
Does not need to call inherited function.
Protocols.Bittorrent.Port Protocols.Bittorrent.Port(
.Torrent
_parent
)
Bind a port for this Torrent.
Bittorrent peer - download and share. Read more about bittorrent at http://bitconjurer.org/BitTorrent/introduction.html
The smallest usable torrent downloader. As first argument, it expects a filename to a .torrent file.
int main(int ac,array am) { // initialize Torrent from file: Protocols.Bittorrent.Torrent t=Protocols.Bittorrent.Torrent(); t->load_metainfo(am[1]); // Callback when download status changes: // t->downloads_update_status=...; // Callback when pieces status change (when we get new stuff): // t->pieces_update_status=...; // Callback when peer status changes (connect, disconnect, choked...): // t->peer_update_status=...; // Callback when download is completed: t->download_completed_callback= lambda() { call_out(exit,3600,0); // share for an hour, then exit }; // Callback to print warnings (same args as sprintf): // t->warning=werror; // type of progress function used below: void progress(int n,int of) { /* ... */ }; // Initiate targets from Torrent, // if target was created, no need to verify: if (t->fix_targets(1,0,progress)==1) t->verify_targets(progress); // Open port to listen on, // we want to do this to be able to talk to firewalled peers: t->open_port(6881); // Ok, start calling tracker to get peers, // and tell about us: t->start_update_tracker(); // Finally, start the download: t->start_download(); return -1; }
function
(.Peer
, int
, int
:bool
) Protocols.Bittorrent.Torrent.do_we_strangle
Function to determine if we should strangle this peer. Default is to allow 100000 bytes of data over the ratio, which is 2:1 per default; upload twice as much as we get.
Arguments are the peer, bytes in (downloaded) and bytes out (uploaded). Return 1 to strangle and 0 to allow the peer to proceed downloading again.
function
(:void
) Protocols.Bittorrent.Torrent.download_completed_callback
If set, called when download is completed.
function
(:void
) Protocols.Bittorrent.Torrent.downloads_update_status
If set, called when we start to download another piece (no args).
function
(:void
) Protocols.Bittorrent.Torrent.peer_update_status
If set, called when peer status changes.
function
(:void
) Protocols.Bittorrent.Torrent.pieces_update_status
If set, called when we got another piece downloaded (no args).
function
(string
, __unknown__
... :void
|mixed
) Protocols.Bittorrent.Torrent.warning
Called if there is a protocol error.
int
bytes_done()
Calculate the bytes successfully downloaded (full pieces).
int
bytes_left()
Calculate the bytes left to download.
void
contact_peers(void
|int
n
)
Contact all or n peers.
string
file_got_bitfield()
Returns the file got field as a string bitfield (cached).
int
fix_targets(void
|int(-1..2)
allocate
, void
|string
base_filename
, void
|function
(int
, int
:void
) progress_callback
)
Opens target datafile(s).
If all files are created, the verify info will be filled as well,
but if it isn't created, a call to verify_target()
is necessary
after this call.
allocate
Determines allocation procedure if the file doesn't exist:
| Don't allocate. |
| Allocate virtual file size (seek, write end byte). |
| Allocate for real (will call progress_callback(pos,length)). |
| Means never create a file, only open old files. |
my_filename
A new base filename to substitute the metainfo base target filename with.
| The (a) file was already there. |
| All target files were created. |
void
load_metainfo(string
filename
)
Loads the metainfo from a file.
void
open_port(void
|int
port
)
Open the port we're listening on.
void
start_download()
Initiate the downloading scheme.
void
start_update_tracker(void
|int
interval
)
Starts to contact the tracker at regular intervals, giving it the status and recieving more peers to talk to. Will also contact these peers. The default interval is 5 minutes. If given an event, will update tracker with it.
void
stop_update_tracker(void
|string
event
)
Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.
void
update_tracker(void
|string
event
, void
|int
contact
)
Contact and update the tracker with current status will fill the peer list.
void
verify_targets(void
|function
(int
, int
:void
) progress_callback
)
Verify the file and fill file_got (necessary after load_info, but needs open_file before this call). [ progress_callback(at chunk,total chunks) ]
Each bittorrent has one or more target files. This represents one of those.
string
Protocols.Bittorrent.Torrent.Target.base
int
Protocols.Bittorrent.Torrent.Target.length
int
Protocols.Bittorrent.Torrent.Target.offset
void
|array
Protocols.Bittorrent.Torrent.Target.path
protected
local
void
__create__(string
base
, int
length
, int
offset
, void
|array
path
)
Protocols.Bittorrent.Torrent.Target Protocols.Bittorrent.Torrent.Target(
string
base
, int
length
, int
offset
, void
|array
path
)
bool
Protocols.Bittorrent.Tracker.dynamic_add_torrents
Allow clients to dynamically add torrents to the tracker.
int(0..)
Protocols.Bittorrent.Tracker.interval
The query interval reported back to clients. Defaults to
1800
.
void
add_torrent(string
id
)
Add a torrent to the tracker.
id
The info hash of the torrent file.
string
announce(mapping
args
, string
ip
)
Handles HTTP announce queries to the tracker.
string
scrape(mapping
args
)
Returns the result of a scrape query.
string
Protocols.Bittorrent.Tracker.Client.ip
int
Protocols.Bittorrent.Tracker.Client.port
protected
local
void
__create__(string
ip
, int
port
)
Protocols.Bittorrent.Tracker.Client Protocols.Bittorrent.Tracker.Client(
string
ip
, int
port
)
string
bits2string(array
(bool
) v
)
Convert an array of int(0..1)
to a Bittorrent style
bitstring. Input will be padded to even bytes.
string
|int
|array
|mapping
decode(Stdio.Buffer
buf
)
Decodes a Bittorrent bencoded data chunk and ignores the remaining
string. Returns UNDEFINED
if the data is incomplete.
string
encode(string
|int
|array
|mapping
data
)
Encodes a Bittorrent bencoded data chunk.
array
(int
) string2arr(string
s
)
Convert a Bittorrent style bitstring to an array of indices.
array
(bool
) string2bits(string
s
)
Convert a Bittorrent style bitstring to an array of
int(0..1)
.
string
identify_peer(string
peerid
)
Decodes the given peerid
, returning an identification string
for the client software. Assumes the peerid
string is exactly
20 characters long.
This class provides an interface to DNS Service Discovery. The functionality of DNS-SD is described at <http://www.dns-sd.org/>.
Using the Proctocols.DNS_SD.Service class a Pike program can announce services, for example a web site or a database server, to computers on the local network.
When registering a service you need to provide the service name. service type, domain and port number. You can also optionally specify a TXT record. The contents of the TXT record varies between different services; for example, a web server can announce a path to a web page, and a printer spooler is able to list printer features such as color support or two-sided printing.
The service is registered on the network for as long as the instance of the Service class is valid.
inherit _Protocols_DNS_SD.Service : Service
Protocols.DNS_SD.Service Protocols.DNS_SD.Service(
string
name
, string
service
, string
domain
, int
port
, void
|string
|array
(string
) txt
)
Registers a service on the local network.
name
User-presentable name of the service.
service
Type of service on the form _type._protocol. Type is an
identifier related to the service type. A list of registered
service types can be found at
http://http://www.dns-sd.org/ServiceTypes.html/. Protocol
is normally tcp but udp is also a valid choice. For
example, a web server would get a service
of _http._tcp.
domain
Domain name. Normally an empty string which the DNS-SD library will translate into local..
port
Port number for the service (e.g. 80 for a web site).
txt
An optional TXT record with service-specific information. It can
be given as a plain string or an array of property assignment
strings. The TXT record can be changed later by calling update_txt
in the object returned when you register the service.
object svc = Protocols.DNS_SD.Service( "Company Intranet Forum", // name "_http._tcp", // service type "", // domain (default) 80, // port ({ "path=/forum/" }) // TXT record );
void
update_txt(string
|array
(string
) txt
)
Updates the TXT record for the service.
txt
A TXT record with service-specific information. It can be given as a plain string or an array of property assignment strings. To remove an existing TXT record you give an empty string as the argument.
HTTP/2 protocol.
constant
Protocols.HTTP2.TLS_CIPHER_SUITE_BLACK_LIST
constant
Protocols.HTTP2.ERROR_no_error
constant
Protocols.HTTP2.ERROR_protocol_error
constant
Protocols.HTTP2.ERROR_internal_error
constant
Protocols.HTTP2.ERROR_flow_control_error
constant
Protocols.HTTP2.ERROR_settings_timeout
constant
Protocols.HTTP2.ERROR_stream_closed
constant
Protocols.HTTP2.ERROR_frame_size_error
constant
Protocols.HTTP2.ERROR_refused_stream
constant
Protocols.HTTP2.ERROR_cancel
constant
Protocols.HTTP2.ERROR_compression_error
constant
Protocols.HTTP2.ERROR_connect_error
constant
Protocols.HTTP2.ERROR_enhance_your_calm
constant
Protocols.HTTP2.ERROR_inadequate_security
constant
Protocols.HTTP2.ERROR_http_1_1_required
constant
Protocols.HTTP2.FLAG_end_stream
constant
Protocols.HTTP2.FLAG_ack
constant
Protocols.HTTP2.FLAG_end_headers
constant
Protocols.HTTP2.FLAG_padded
constant
Protocols.HTTP2.FLAG_priority
constant
Protocols.HTTP2.FRAME_data
constant
Protocols.HTTP2.FRAME_headers
constant
Protocols.HTTP2.FRAME_priority
constant
Protocols.HTTP2.FRAME_rst_stream
constant
Protocols.HTTP2.FRAME_settings
constant
Protocols.HTTP2.FRAME_push_promise
constant
Protocols.HTTP2.FRAME_ping
constant
Protocols.HTTP2.FRAME_goaway
constant
Protocols.HTTP2.FRAME_window_update
constant
Protocols.HTTP2.FRAME_continuation
constant
Protocols.HTTP2.SETTING_header_table_size
constant
Protocols.HTTP2.SETTING_enable_push
constant
Protocols.HTTP2.SETTING_max_concurrent_streams
constant
Protocols.HTTP2.SETTING_initial_window_size
constant
Protocols.HTTP2.SETTING_max_frame_size
constant
Protocols.HTTP2.SETTING_max_header_list_size
HTTP/2 frame.
FrameType
Protocols.HTTP2.Frame.frame_type
Flag
Protocols.HTTP2.Frame.flags
int
|Stdio.Buffer
|array
(array
(string(8bit)
)) Protocols.HTTP2.Frame.payload
Data length for received packets, and payload for packets to send.
NB: To avoid frame reordering issues with HPack,
this is the set of headers for FRAME_header
and FRAME_push_promise
.
int
|void
Protocols.HTTP2.Frame.promised_stream_id
Only used with FRAME_push_promise
, and
overrides stream_id
.
int
|void
Protocols.HTTP2.Frame.stream_id
Stream identifier.
protected
local
void
__create__(FrameType
frame_type
, Flag
flags
, int
|Stdio.Buffer
|array
(array
(string(8bit)
)) payload
, int
|void
stream_id
, int
|void
promised_stream_id
)
Protocols.HTTP2.Frame Protocols.HTTP2.Frame(
FrameType
frame_type
, Flag
flags
, int
|Stdio.Buffer
|array
(array
(string(8bit)
)) payload
, int
|void
stream_id
, int
|void
promised_stream_id
)
IMAP (Internet Message Access Protocol) server support
imap_server.pike
parse_line.pike
mapping
|zero
get_atom_options(int
max_depth
)
Reads an atom, optionally followd by a list enclosed in square brackets. Naturally, the atom itself cannot contain any brackets.
Returns a mapping type : "atom", atom : name, raw : name[options] options : parsed options, range : ({ start, size })
array
(string
)|zero
get_flag_list()
Get a list of atoms. Primarily intended for use by STORE for the flags argument.
mapping
|zero
get_range(mapping
atom
)
Reads a <start.size> suffix
object
|zero
get_set()
Returns a set object.
mapping
|zero
get_simple_list(int
max_depth
)
Parses an object that (recursivly) can contain atoms (possible with options in brackets) or lists. Note that strings are not accepted, as it is a little difficult to wait for the continuation of the request.
FIXME: This function is used to read fetch commands. This breaks rfc-2060 compliance, as the names of headers can be represented as string literals.
mapping
get_token(int
eol
, int
accept_options
)
Parses an object that can be a string, an atom (possibly with options in brackets) or a list.
eol can be 0, meaning no end of line or list expected, a positive int, meaning a character (e.g. ')' or ']' that terminates the list, or -1, meaning that the list terminates at end of line.
Continuation based imap parser.
IMAP.server
Handles the server side of the protocol.
inherit Protocols.Line.imap_style : imap_style
IMAP.requests
IMAP.types
string
format_addr_short(array
(int(16bit)
) bin_addr
)
Formats an IPv6 address to the colon-separated hexadecimal form as
defined in RFC 2373 section 2.2. bin_addr
must be an 8-element array
containing the 16-bit fields.
The returned address is on a canonical shortest form as follows: The longest sequence of zeroes is shortened using "::". If there are several of equal length then the leftmost is shortened. All hexadecimal letters are lower-case. There are no superfluous leading zeroes in the fields.
parse_addr
string
|zero
normalize_addr_basic(string
addr
)
Normalizes a formatted IPv6 address to a string with eight
hexadecimal numbers separated by ":". addr
is given on
the same form, or any of the shorthand varieties as specified in
RFC 2373 section 2.2.
All hexadecimal letters in the returned address are lower-case, and there are no superfluous leading zeroes in the fields.
Zero is returned if addr
is incorrectly formatted.
normalize_addr_short
string
|zero
normalize_addr_short(string
addr
)
Normalizes a formatted IPv6 address to a canonical shortest form.
addr
is parsed according to the hexadecimal
"x:x:x:x:x:x:x:x"
syntax or any of its shorthand varieties
(see RFC 2373 section 2.2).
The returned address is normalized as follows: The longest sequence of zeroes is shortened using "::". If there are several of equal length then the leftmost is shortened. All hexadecimal letters are lower-case. There are no superfluous leading zeroes in the fields.
Zero is returned if addr
is incorrectly formatted.
normalize_addr_basic
array
(int(16bit)
)|zero
parse_addr(string
addr
)
Parses an IPv6 address on the formatted hexadecimal
"x:x:x:x:x:x:x:x"
form, or any of the shorthand varieties
(see RFC 2373 section 2.2).
The address is returned as an 8-element array where each element
is the value of the corresponding field. Zero is returned if addr
is incorrectly formatted.
format_addr_short
IRC client and connection handling.
Start with Client
and Channel
.
Protocols.IRC.client irc; class channel_notif { inherit Protocols.IRC.Channel; void not_message(object person,string msg) { if (msg == "!hello") irc->send_message(name, "Hello, "+person->nick+"!"); } } int main() { irc = Protocols.IRC.Client("irc.freenode.net", ([ "nick": "DemoBot12345", "realname": "Demo IRC bot", "channel_program": channel_notif, ])); irc->join_channel("#bot-test"); return -1; }
Abstract class for an IRC channel.
string
Protocols.IRC.Channel.name
The name of the channel.
void
not_join(Person
who
)
Called whenever someone joins this channel.
void
not_message(Person
who
, string
message
)
Called whenever a message arrives on this channel.
void
close()
Closes the connection to the server.
Protocols.IRC.Client Protocols.IRC.Client(
string
|object
server
, void
|mapping
(string
:mixed
) options
)
server
The IRC server to connect to.
If server is an object, it is assumed to be a newly established
connection to the IRC server to be used. Pass SSL.File
connections here to connect to SSL secured IRC networks.
options
An optional mapping with additional IRC client options.
| Defaults to 6667. |
| Defaults to |
| Defaults to |
| Server password, if any. Public servers seldom require this. |
| Defaults to |
| Defaults to |
| Defaults to 120. |
| Defaults to 120. |
| This function is called when the connection to the IRC server is lost or when a ping isn't answered with a pong within the time set by the ping_timeout option. The default behaviour is to complain on stderr and self destruct. |
| An instance of this is created for each channel connected to via join_channel() - should be a subclass of Protocols.IRC.Channel. |
| This function is called when a KILL or ERROR command is recieved from the IRC server. |
| |
| |
| |
| The arguments are from, type, to, message and extra. |
| The arguments are who and why. |
| The arguments are originator, message and to. |
| The arguments are originator, message and to. |
| The arguments are originator and to. |
Abstract class for a person.
string
Protocols.IRC.Person.ip
User domain, e.g. "mistel.idonex.se"
.
int
Protocols.IRC.Person.last_action
Time of last action, represented as posix time.
string
Protocols.IRC.Person.nick
User nickname, e.g. "Mirar"
.
string
Protocols.IRC.Person.user
User name, e.g. "mirar"
.
An implementation of the IDENT protocol, specified in RFC 0931.
array
(string
) lookup(object
fd
)
Throws exception upon any error.
Protocols.Ident.AsyncLookup Protocols.Ident.AsyncLookup(
object
fd
, function
(array
(string
), mixed
... :void
) cb
, mixed
... args
)
constant
string
Protocols.LDAP.GUID_USERS_CONTAINER
constant
string
Protocols.LDAP.GUID_COMPUTERS_CONTAINER
constant
string
Protocols.LDAP.GUID_SYSTEMS_CONTAINER
constant
string
Protocols.LDAP.GUID_DOMAIN_CONTROLLERS_CONTAINER
constant
string
Protocols.LDAP.GUID_INFRASTRUCTURE_CONTAINER
constant
string
Protocols.LDAP.GUID_DELETED_OBJECTS_CONTAINER
constant
string
Protocols.LDAP.GUID_LOSTANDFOUND_CONTAINER
constant
string
Protocols.LDAP.GUID_FOREIGNSECURITYPRINCIPALS_CONTAINER
constant
string
Protocols.LDAP.GUID_PROGRAM_DATA_CONTAINER
constant
string
Protocols.LDAP.GUID_MICROSOFT_PROGRAM_DATA_CONTAINER
constant
string
Protocols.LDAP.GUID_NTDS_QUOTAS_CONTAINER
Constants for Microsoft AD Well-Known Object GUIDs. These are e.g. used in LDAP URLs:
"ldap://server/<WKGUID=" + Protocols.LDAP.GUID_USERS_CONTAINER +
",dc=my,dc=domain,dc=com>"
constant
int
Protocols.LDAP.LDAP_SUCCESS
constant
int
Protocols.LDAP.LDAP_OPERATIONS_ERROR
constant
int
Protocols.LDAP.LDAP_PROTOCOL_ERROR
constant
int
Protocols.LDAP.LDAP_TIMELIMIT_EXCEEDED
constant
int
Protocols.LDAP.LDAP_SIZELIMIT_EXCEEDED
constant
int
Protocols.LDAP.LDAP_COMPARE_FALSE
constant
int
Protocols.LDAP.LDAP_COMPARE_TRUE
constant
int
Protocols.LDAP.LDAP_AUTH_METHOD_NOT_SUPPORTED
constant
Protocols.LDAP.LDAP_STRONG_AUTH_NOT_SUPPORTED
constant
int
Protocols.LDAP.LDAP_STRONG_AUTH_REQUIRED
constant
int
Protocols.LDAP.LDAP_PARTIAL_RESULTS
constant
int
Protocols.LDAP.LDAP_REFERRAL
constant
int
Protocols.LDAP.LDAP_ADMINLIMIT_EXCEEDED
constant
int
Protocols.LDAP.LDAP_UNAVAILABLE_CRITICAL_EXTENSION
constant
int
Protocols.LDAP.LDAP_CONFIDENTIALITY_REQUIRED
constant
int
Protocols.LDAP.LDAP_SASL_BIND_IN_PROGRESS
constant
int
Protocols.LDAP.LDAP_NO_SUCH_ATTRIBUTE
constant
int
Protocols.LDAP.LDAP_UNDEFINED_TYPE
constant
int
Protocols.LDAP.LDAP_INAPPROPRIATE_MATCHING
constant
int
Protocols.LDAP.LDAP_CONSTRAINT_VIOLATION
constant
int
Protocols.LDAP.LDAP_TYPE_OR_VALUE_EXISTS
constant
int
Protocols.LDAP.LDAP_INVALID_SYNTAX
constant
int
Protocols.LDAP.LDAP_NO_SUCH_OBJECT
constant
int
Protocols.LDAP.LDAP_ALIAS_PROBLEM
constant
int
Protocols.LDAP.LDAP_INVALID_DN_SYNTAX
constant
int
Protocols.LDAP.LDAP_IS_LEAF
constant
int
Protocols.LDAP.LDAP_ALIAS_DEREF_PROBLEM
constant
int
Protocols.LDAP.LDAP_INAPPROPRIATE_AUTH
constant
int
Protocols.LDAP.LDAP_INVALID_CREDENTIALS
constant
int
Protocols.LDAP.LDAP_INSUFFICIENT_ACCESS
constant
int
Protocols.LDAP.LDAP_BUSY
constant
int
Protocols.LDAP.LDAP_UNAVAILABLE
constant
int
Protocols.LDAP.LDAP_UNWILLING_TO_PERFORM
constant
int
Protocols.LDAP.LDAP_LOOP_DETECT
constant
int
Protocols.LDAP.LDAP_SORT_CONTROL_MISSING
constant
int
Protocols.LDAP.LDAP_NAMING_VIOLATION
constant
int
Protocols.LDAP.LDAP_OBJECT_CLASS_VIOLATION
constant
int
Protocols.LDAP.LDAP_NOT_ALLOWED_ON_NONLEAF
constant
int
Protocols.LDAP.LDAP_NOT_ALLOWED_ON_RDN
constant
int
Protocols.LDAP.LDAP_ALREADY_EXISTS
constant
int
Protocols.LDAP.LDAP_NO_OBJECT_CLASS_MODS
constant
int
Protocols.LDAP.LDAP_RESULTS_TOO_LARGE
constant
int
Protocols.LDAP.LDAP_AFFECTS_MULTIPLE_DSAS
constant
int
Protocols.LDAP.LDAP_OTHER
LDAP result codes.
Protocols.LDAP.client.error_number
,
Protocols.LDAP.client.result.error_number
constant
string
Protocols.LDAP.LDAP_CONTROL_MANAGE_DSA_IT
LDAP control: Manage DSA IT LDAPv3 control (RFC 3296): Control to indicate that the operation is intended to manage objects within the DSA (server) Information Tree.
constant
string
Protocols.LDAP.LDAP_CONTROL_VLVREQUEST
LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to request virtual list view support from the server.
constant
string
Protocols.LDAP.LDAP_CONTROL_VLVRESPONSE
LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to pass virtual list view (VLV) data from the server to the client.
constant
string
Protocols.LDAP.LDAP_PAGED_RESULT_OID_STRING
LDAP control: Microsoft AD: Control to instruct the server to return the results of a search request in smaller, more manageable packets rather than in one large block.
constant
string
Protocols.LDAP.LDAP_SERVER_ASQ_OID
LDAP control: Microsoft AD: Control to force the query to be based on a specific DN-valued attribute.
constant
string
Protocols.LDAP.LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID
LDAP control: Microsoft AD: Control used with an extended LDAP rename function to move an LDAP object from one domain to another.
constant
string
Protocols.LDAP.LDAP_SERVER_DIRSYNC_OID
LDAP control: Microsoft AD: Control that enables an application to search the directory for objects changed from a previous state.
constant
string
Protocols.LDAP.LDAP_SERVER_DOMAIN_SCOPE_OID
LDAP control: Microsoft AD: Control used to instruct the LDAP server not to generate any referrals when completing a request.
constant
string
Protocols.LDAP.LDAP_SERVER_EXTENDED_DN_OID
LDAP control: Microsoft AD: Control to request an extended form of an Active Directory object distinguished name.
constant
string
Protocols.LDAP.LDAP_SERVER_LAZY_COMMIT_OID
LDAP control: Microsoft AD: Control used to instruct the server to return the results of a DS modification command, such as add, delete, or replace, after it has been completed in memory, but before it has been committed to disk.
constant
string
Protocols.LDAP.LDAP_SERVER_NOTIFICATION_OID
LDAP control: Microsoft AD: Control used with an extended LDAP asynchronous search function to register the client to be notified when changes are made to an object in Active Directory.
constant
string
Protocols.LDAP.LDAP_SERVER_PERMISSIVE_MODIFY_OID
LDAP control: Microsoft AD: An LDAP modify request will normally fail if it attempts to add an attribute that already exists, or if it attempts to delete an attribute that does not exist. With this control, as long as the attribute to be added has the same value as the existing attribute, then the modify will succeed. With this control, deletion of an attribute that does not exist will also succeed.
constant
string
Protocols.LDAP.LDAP_SERVER_QUOTA_CONTROL_OID
LDAP control: Microsoft AD: Control used to pass the SID of a security principal, whose quota is being queried, to the server in a LDAP search operation.
constant
string
Protocols.LDAP.LDAP_SERVER_RESP_SORT_OID
LDAP control: Microsoft AD: Control used by the server to indicate
the results of a search function initiated using the
LDAP_SERVER_SORT_OID
control.
constant
string
Protocols.LDAP.LDAP_SERVER_SD_FLAGS_OID
LDAP control: Microsoft AD: Control used to pass flags to the server to control various security descriptor results.
constant
string
Protocols.LDAP.LDAP_SERVER_SEARCH_OPTIONS_OID
LDAP control: Microsoft AD: Control used to pass flags to the server to control various search behaviors.
constant
string
Protocols.LDAP.LDAP_SERVER_SHOW_DELETED_OID
LDAP control: Microsoft AD: Control used to specify that the search results include any deleted objects that match the search filter.
constant
string
Protocols.LDAP.LDAP_SERVER_SORT_OID
LDAP control: Microsoft AD: Control used to instruct the server to sort the search results before returning them to the client application.
constant
string
Protocols.LDAP.LDAP_SERVER_TREE_DELETE_OID
LDAP control: Microsoft AD: Control used to delete an entire subtree in the directory.
constant
string
Protocols.LDAP.LDAP_SERVER_VERIFY_NAME_OID
LDAP control: Microsoft AD: Control used to instruct the DC accepting the update which DC it should verify with, the existence of any DN attribute values.
constant
int
Protocols.LDAP.MODIFY_ADD
constant
int
Protocols.LDAP.MODIFY_DELETE
constant
int
Protocols.LDAP.MODIFY_REPLACE
Constants used in the attropval
argument to
Protocols.LDAP.client.modify
.
constant
int
Protocols.LDAP.SCOPE_BASE
constant
int
Protocols.LDAP.SCOPE_ONE
constant
int
Protocols.LDAP.SCOPE_SUB
Constants for the search scope used with e.g.
Protocols.LDAP.client.set_scope
.
Return the object specified by the DN.
Return the immediate subobjects of the object specified by the DN.
Return the object specified by the DN and all objects below it (on any level).
constant
int
Protocols.LDAP.SEARCH_LOWER_ATTRS
constant
int
Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY
constant
int
Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS
Bitfield flags given to Protocols.LDAP.client.search
:
Lowercase all attribute values. This makes it easier to match
specific attributes in the mappings returned by
Protocols.LDAP.client.result.fetch
since LDAP attribute names
are case insensitive.
Only use arrays for attribute values where the attribute syntax specify multiple values. I.e. the values for single valued attributes are returned as strings instead of arrays containing one string element.
If no value is returned for a single valued attribute, e.g. when
attrsonly
is set in the search call, then a zero will be
used as value.
The special "dn"
value is also returned as a string when
this flag is set.
Note that it's the attribute type descriptions that are used to decide this, not the number of values a particular attribute happens to have in the search result.
Don't throw attribute value decode errors, instead return them
in the result from Protocols.LDAP.client.result.fetch
in
place of the value. I.e. anywhere an attribute value string
occurs, you might instead have a Charset.DecodeError
object.
constant
string
Protocols.LDAP.SYNTAX_AD_CASE_IGNORE_STR
constant
string
Protocols.LDAP.SYNTAX_AD_LARGE_INT
constant
string
Protocols.LDAP.SYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR
LDAP syntax: Microsoft AD: Additional syntaxes used in AD. C.f. <http://community.roxen.com/(all)/developers/idocs/drafts/ draft-armijo-ldap-syntax-00.html>.
constant
string
Protocols.LDAP.SYNTAX_ATTR_TYPE_DESCR
constant
string
Protocols.LDAP.SYNTAX_BINARY
constant
string
Protocols.LDAP.SYNTAX_BIT_STRING
constant
string
Protocols.LDAP.SYNTAX_BOOLEAN
constant
string
Protocols.LDAP.SYNTAX_CERT
constant
string
Protocols.LDAP.SYNTAX_CERT_LIST
constant
string
Protocols.LDAP.SYNTAX_CERT_PAIR
constant
string
Protocols.LDAP.SYNTAX_COUNTRY_STR
constant
string
Protocols.LDAP.SYNTAX_DN
constant
string
Protocols.LDAP.SYNTAX_DIRECTORY_STR
constant
string
Protocols.LDAP.SYNTAX_DIT_CONTENT_RULE_DESCR
constant
string
Protocols.LDAP.SYNTAX_FACSIMILE_PHONE_NUM
constant
string
Protocols.LDAP.SYNTAX_FAX
constant
string
Protocols.LDAP.SYNTAX_GENERALIZED_TIME
constant
string
Protocols.LDAP.SYNTAX_IA5_STR
constant
string
Protocols.LDAP.SYNTAX_INT
constant
string
Protocols.LDAP.SYNTAX_JPEG
constant
string
Protocols.LDAP.SYNTAX_MATCHING_RULE_DESCR
constant
string
Protocols.LDAP.SYNTAX_MATCHING_RULE_USE_DESCR
constant
string
Protocols.LDAP.SYNTAX_MHS_OR_ADDR
constant
string
Protocols.LDAP.SYNTAX_NAME_AND_OPTIONAL_UID
constant
string
Protocols.LDAP.SYNTAX_NAME_FORM_DESCR
constant
string
Protocols.LDAP.SYNTAX_NUMERIC_STRING
constant
string
Protocols.LDAP.SYNTAX_OBJECT_CLASS_DESCR
constant
string
Protocols.LDAP.SYNTAX_OID
constant
string
Protocols.LDAP.SYNTAX_OTHER_MAILBOX
constant
string
Protocols.LDAP.SYNTAX_POSTAL_ADDR
constant
string
Protocols.LDAP.SYNTAX_PRESENTATION_ADDR
constant
string
Protocols.LDAP.SYNTAX_PRINTABLE_STR
constant
string
Protocols.LDAP.SYNTAX_PHONE_NUM
constant
string
Protocols.LDAP.SYNTAX_UTC_TIME
constant
string
Protocols.LDAP.SYNTAX_LDAP_SYNTAX_DESCR
constant
string
Protocols.LDAP.SYNTAX_DIT_STRUCTURE_RULE_DESCR
LDAP syntax: Standard syntaxes from RFC 2252.
constant
Protocols.LDAP.SYNTAX_CASE_EXACT_STR
"caseExactString"
is an alias used in e.g. RFC 2079.
constant
string
Protocols.LDAP.SYNTAX_DELIVERY_METHOD
constant
string
Protocols.LDAP.SYNTAX_ENHANCED_GUIDE
constant
string
Protocols.LDAP.SYNTAX_GUIDE
constant
string
Protocols.LDAP.SYNTAX_OCTET_STR
constant
string
Protocols.LDAP.SYNTAX_TELETEX_TERMINAL_ID
constant
string
Protocols.LDAP.SYNTAX_TELETEX_NUM
constant
string
Protocols.LDAP.SYNTAX_SUPPORTED_ALGORITHM
LDAP syntax: Standard syntaxes from RFC 2256.
constant
Protocols.LDAP.ldap_error_strings
Mapping from LDAP_*
result codes to descriptive strings.
constant
mapping
(string
:function
(string
:string
)) Protocols.LDAP.syntax_decode_fns
Mapping containing functions to decode charsets in syntaxes where that's necessary. If the syntax is complex in a way that makes the result ambiguous if decoded with a single charset transformation then it should typically not be decoded here.
These decoders are used on all attribute values returned by
Protocols.LDAP.client.result
functions.
constant
mapping
(string
:function
(string
:string
)) Protocols.LDAP.syntax_encode_fns
Mapping containing the reverse functions from syntax_decode_fns
.
string
canonicalize_dn(string
dn
, void
|int
strict
)
Returns the given distinguished name on a canonical form, so it reliably can be used in comparisons for equality. This means removing surplus whitespace, lowercasing attributes, normalizing quoting in string attribute values, lowercasing the hex digits in binary attribute values, and sorting the RDN parts separated by "+".
The returned string follows RFC 2253. The input string may use legacy LDAPv2 syntax and is treated according to RFC 2253 section 4.
If strict
is set then errors will be thrown if the given DN is
syntactically invalid. Otherwise the invalid parts remain
untouched in the result.
The result is not entirely canonical since no conversion is done from or to hexadecimal BER encodings of the attribute values. It's assumed that the input already has the suitable value encoding depending on the attribute type.
No UTF-8 encoding or decoding is done. The function can be used on both encoded and decoded input strings, and the result will be likewise encoded or decoded.
string
encode_dn_value(string
str
)
Encode the given string for use as an attribute value in a distinguished name (on string form).
The encoding is according to RFC 2253 section 2.4 with the exception
that characters above 0x7F
aren't UTF-8 encoded. UTF-8
encoding can always be done afterwards on the complete DN, which
also is done internally by the Protocols.LDAP
functions when
LDAPv3 is used.
object
get_cached_filter(string
filter
, void
|int
ldap_version
)
Like make_filter
but saves the generated objects for reuse.
Useful for filters that reasonably will occur often. The cache is
never garbage collected, however.
If there's a parse error in the filter then a FilterError
is
thrown as from make_filter
.
object
get_connection(string
ldap_url
, void
|string
binddn
, void
|string
password
, void
|int
version
, void
|SSL.Context
ctx
)
Returns a client connection to the specified LDAP URL. If a bind
DN is specified (either through a "bindname"
extension in
ldap_url
or, if there isn't one, through binddn
) then the
connection will be bound using that DN and the optional password.
If no bind DN is given then any connection is returned, regardless
of the bind DN it is using.
version
may be used to specify the required protocol version in
the bind operation. If zero or left out, a bind attempt with the
default version (currently 3
) is done with a fallback to
2
if that fails. Also, a cached connection for any version
might be returned if version
isn't specified.
ctx
may be specified to control SSL/TLS parameters to use
with the "ldaps"
-protocol. Note that changing this only
affects new connections.
As opposed to creating an Protocols.LDAP.client
instance
directly, this function can return an already established
connection for the same URL, provided connections are given back
using return_connection
when they aren't used anymore.
A client object with an error condition is returned if there's a bind error, e.g. invalid password.
string
get_constant_name(mixed
val
)
If val
matches any non-integer constant in this module, its
name is returned.
string
ldap_decode_string(string
str
)
Decodes all \xx
escapes in str
.
ldap_encode_string
string
ldap_encode_string(string
str
)
Quote characters in the given string as necessary for use as a string literal in filters and various composite LDAP attributes.
The quoting is compliant with RFC 2252 section 4.3 and
RFC 2254 section 4. All characters that can be special in those RFCs
are quoted using the \xx
syntax, but the set might be
extended.
ldap_decode_string
, Protocols.LDAP.client.search
object
make_filter(string
filter
, void
|int
ldap_version
)
Parses an LDAP filter string into an ASN1 object tree that can be
given to Protocols.LDAP.search
.
Using this function instead of giving the filter string directly to the search function has two advantages: This function provides better error reports for syntax errors, and the same object tree can be used repeatedly to avoid reparsing the filter string.
filter
The filter to parse, according to the syntax specified in RFC 2254. The syntax is extended a bit to allow and ignore whitespace everywhere except inside and next to the filter values.
ldap_version
LDAP protocol version to make the filter for. This controls what
syntaxes are allowed depending on the protocol version. Also, if
the protocol is 3
or later then full Unicode string
literals are supported. The default is the latest supported
version.
An ASN1 object tree representing the filter.
FilterError
is thrown if there's a syntax error in the
filter.
int
num_connections(string
ldap_url
)
Returns the number of currently stored connections for the given LDAP URL.
mapping
(string
:mixed
) parse_ldap_url(string
ldap_url
)
Parses an LDAP URL and returns its fields in a mapping.
The returned mapping contains these fields:
| The URL scheme, either |
| Self-explanatory. |
| |
| |
| Array containing the attributes. Undefined if none was specified. |
| The scope as one of the |
| The search filter. Undefined if none was specified. |
| The extensions. Undefined if none was specified. The mapping
values are |
| The original unparsed URL. |
get_parsed_url
void
return_connection(object
conn
)
Use this to return a connection to the connection pool after you've finished using it. The connection is assumed to be working.
Ensure that persistent connection settings such as the scope and the base DN are restored to the defaults
Error object thrown by make_filter
for parse errors.
constant
int
Protocols.LDAP.FilterError.is_ldap_filter_error
Recognition constant.
Contains the client implementation of the LDAP protocol. All of the version 2 protocol features are implemented but only the base parts of the version 3.
inherit .protocol : protocol
mapping
Protocols.LDAP.client.info
Several information about code itself and about active connection too
int
add(string
dn
, mapping
(string
:array
(string
)) attrs
)
The Add Operation allows a client to request the addition of an entry into the directory
dn
The Distinguished Name of the entry to be added.
attrs
The mapping of attributes and their values that make up the content of the entry being added. Values that are sent UTF-8 encoded according the the attribute syntaxes are encoded automatically.
Returns 1
on success, 0
otherwise.
The API change: the returning code was changed in Pike 7.3+ to follow his logic better.
int
bind()
int
bind(string
dn
, string
password
)
int
bind(string
dn
, string
password
, int
version
)
Authenticates connection to the direcory.
First form uses default value previously entered in create.
Second form uses value from parameters:
dn
The distinguished name (DN) of an entry aginst which will be made authentication.
password
Password used for authentication.
Third form allows specify the version of LDAP protocol used by connection to the LDAP server.
version
The desired protocol version (current 2
or 3
).
Defaults to 3
if zero or left out.
Returns 1
on success, 0
otherwise.
Only simple authentication type is implemented. So be warned clear text passwords are sent to the directory server.
The API change: the returning code was changed in Pike 7.3+ to follow his logic better.
int
compare(string
dn
, string
attr
, string
value
)
Compares an attribute value with one in the directory.
dn
The distinguished name of the entry.
attr
The type (aka name) of the attribute to compare.
value
The value to compare with. It's UTF-8 encoded automatically if the attribute syntax specifies that.
Returns 1
if at least one of the values for the
attribute in the directory is equal to value
, 0
if
it didn't match or there was some error (use error_number
to
find out).
This function has changed arguments since version 7.6. From 7.3 to 7.6 it was effectively useless since it always returned true.
The equality matching rule for the attribute governs the comparison. There are attributes where the assertion syntax used here isn't the same as the attribute value syntax.
Protocols.LDAP.client Protocols.LDAP.client()
Protocols.LDAP.client Protocols.LDAP.client(
string
|mapping
(string
:mixed
) url
)
Protocols.LDAP.client Protocols.LDAP.client(
string
|mapping
(string
:mixed
) url
, object
context
)
Create object. The first optional argument can be used later for subsequence operations. The second one can specify TLS context of connection. The default context only allows 128-bit encryption methods, so you may need to provide your own context if your LDAP server supports only export encryption.
url
LDAP server URL on the form
"ldap://hostname/basedn?attrlist?scope?ext"
. See RFC 2255.
It can also be a mapping as returned by Protocol.LDAP.parse_ldap_url
.
context
TLS context of connection
LDAP.client.bind
, LDAP.client.search
int
delete(string
dn
)
Deletes entry from the LDAP server.
dn
The distinguished name of deleted entry.
Returns 1
on success, 0
otherwise.
The API change: the returning code was changed in Pike 7.3+ to follow his logic better.
mapping
(string
:mixed
)|zero
get_attr_type_descr(string
attr
, v