13. Protocols

13.1. HTTP

Module Protocols.HTTP


Constant response_codes

constant Protocols.HTTP.response_codes

Description

Mapping from StatusCode to descriptive string.

See also

StatusCode


Method delete_url

.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)

Description

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.


Method do_async_method

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)

Description

Low level asynchronous HTTP call method.

Parameter method

The HTTP method to use, e.g. "GET".

Parameter url

The URL to perform method on. Should be a complete URL, including protocol, e.g. "https://pike.lysator.liu.se/".

Parameter query_variables

Calls http_encode_query and appends the result to the URL.

Parameter 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.

Parameter con

Previously initialized connection object. In particular the callbacks must have been set (Query.set_callbacks()).

Parameter data

Data payload to be transmitted in the request.

See also

do_method(), Query.set_callbacks()


Method do_async_proxied_method

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)

Description

Low level asynchronous proxied HTTP call method.

Makes an HTTP request through a proxy.

Parameter proxy

URL for the proxy.

Parameter user
Parameter password

Proxy authentication credentials.

Parameter method

The HTTP method to use, e.g. "GET".

Parameter url

The URL to perform method on. Should be a complete URL, including protocol, e.g. "https://pike.lysator.liu.se/".

Parameter query_variables

Calls http_encode_query and appends the result to the URL.

Parameter 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.

Parameter con

Previously initialized connection object. In particular the callbacks must have been set (Query.set_callbacks()).

Parameter data

Data payload to be transmitted in the request.

See also

do_async_method(), do_proxied_method(), Query.set_callbacks()


Method do_method

.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)

Description

Low level HTTP call method.

Parameter method

The HTTP method to use, e.g. "GET".

Parameter url

The URL to perform method on. Should be a complete URL, including protocol, e.g. "https://pike.lysator.liu.se/".

Parameter query_variables

Calls http_encode_query and appends the result to the URL.

Parameter 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.

Parameter con

Old connection object.

Parameter data

Data payload to be transmitted in the request.

See also

do_sync_method()


Method do_proxied_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)

Description

Makes an HTTP request through a proxy.

Parameter proxy

URL for the proxy.

Parameter user
Parameter password

Proxy authentication credentials.

Parameter method
Parameter url
Parameter query_variables
Parameter request_headers
Parameter con
Parameter data

The remaining arguments are identical to do_method().

See also

do_method(), do_async_proxied_method()


Method get_url

.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)

Description

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.


Method get_url_data

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)

Description

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.


Method get_url_nice

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)

Description

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.


Method http_encode_query

string http_encode_query(mapping(string:int|string|array(string)) variables)

Description

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"
	


Method iri_encode

string iri_encode(string s)

Description

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.

Bugs

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.

See also

percent_decode, uri_encode


Method percent_decode

string percent_decode(string s)

Description

Decodes URI-style %XX encoded chars in the given string.

See also

percent_encode, uri_decode

Bugs

This function currently does not accept wide string input, which is necessary to work as the reverse of iri_encode.


Method percent_encode

string percent_encode(string s)

Description

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.


Method post_url

.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)

Description

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.


Method post_url_data

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)

Description

Similar to get_url_data, except that query variables is sent as a POST request instead of a GET request.


Method post_url_nice

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)

Description

Similar to get_url_nice, except that query variables is sent as a POST request instead of a GET request.


Method put_url

.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)

Description

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.


Method quoted_string_decode

string quoted_string_decode(string s)

Description

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.

See also

quoted_string_encode


Method quoted_string_encode

string quoted_string_encode(string s)

Description

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.

Note

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.

See also

quoted_string_decode


Method uri_decode

string uri_decode(string s)

Description

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.

See also

uri_encode, uri_encode_invalids


Method uri_encode

string uri_encode(string s)

Description

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.

See also

uri_decode, uri_encode_invalids, iri_encode


Method uri_encode_invalids

string uri_encode_invalids(string s)

Description

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.

Note

The characters in the URI reserved set are: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =. In addition, this function doesn't touch the escape char %.

See also

uri_decode, uri_encode

Enum Protocols.HTTP.StatusCode

Description

HTTP Status codes.

See also

response_codes, https://www.iana.org/assignments/http-status-codes/http-status-codes.txt


Constant DAV_ALREADY_REPORTED

constant Protocols.HTTP.DAV_ALREADY_REPORTED

Description

RFC 5842 section 7.1: 208 Already Reported


Constant DAV_FAILED_DEP

constant Protocols.HTTP.DAV_FAILED_DEP

Description

RFC 2518 section 10.5: 424 Failed Dependency


Constant DAV_LOCKED

constant Protocols.HTTP.DAV_LOCKED

Description

RFC 2518 section 10.4: 423 Locked


Constant DAV_LOOP_DETECTED

constant Protocols.HTTP.DAV_LOOP_DETECTED

Description

RFC 5842 section 7.2: 508 Loop Detected


Constant DAV_MULTISTATUS

constant Protocols.HTTP.DAV_MULTISTATUS

Description

RFC 2518 section 10.2: 207 Multi-Status


Constant DAV_PROCESSING

constant Protocols.HTTP.DAV_PROCESSING

Description

RFC 2518 section 10.1: 102 Processing


Constant DAV_STORAGE_FULL

constant Protocols.HTTP.DAV_STORAGE_FULL

Description

RFC 2518 section 10.6: 507 Insufficient Storage


Constant DAV_UNPROCESSABLE

constant Protocols.HTTP.DAV_UNPROCESSABLE

Description

RFC 2518 section 10.3: 422 Unprocessable Entry


Constant DELTA_HTTP_IM_USED

constant Protocols.HTTP.DELTA_HTTP_IM_USED

Description

RFC 3229 section 10.4.1: 226 IM Used


Constant HTCPCP_TEAPOT

constant Protocols.HTTP.HTCPCP_TEAPOT

Description

RFC 2324 section 2.3.2: 418 I'm a teapot


Constant HTTP_ACCEPTED

constant Protocols.HTTP.HTTP_ACCEPTED

Description

RFC 2616 section 10.2.3: 202 Accepted


Constant HTTP_BAD

constant Protocols.HTTP.HTTP_BAD

Description

RFC 2616 section 10.4.1: 400 Bad Request


Constant HTTP_BAD_GW

constant Protocols.HTTP.HTTP_BAD_GW

Description

RFC 2616 section 10.5.3: 502 Bad Gateway


Constant HTTP_BAD_RANGE

constant Protocols.HTTP.HTTP_BAD_RANGE

Description

RFC 2616 section 10.4.17: 416 Requested Range Not Satisfiable


Constant HTTP_CONFLICT

constant Protocols.HTTP.HTTP_CONFLICT

Description

RFC 2616 section 10.4.10: 409 Conflict


Constant HTTP_CONTINUE

constant Protocols.HTTP.HTTP_CONTINUE

Description

RFC 2616 section 10.1.1: 100 Continue


Constant HTTP_CREATED

constant Protocols.HTTP.HTTP_CREATED

Description

RFC 2616 section 10.2.2: 201 Created


Constant HTTP_EARLY_HINTS

constant Protocols.HTTP.HTTP_EARLY_HINTS

Description

RFC 8297 section 2: 103 Early Hints


Constant HTTP_EXPECT_FAILED

constant Protocols.HTTP.HTTP_EXPECT_FAILED

Description

RFC 2616 section 10.4.18: 417 Expectation Failed


Constant HTTP_FORBIDDEN

constant Protocols.HTTP.HTTP_FORBIDDEN

Description

RFC 2616 section 10.4.4: 403 Forbidden


Constant HTTP_FOUND

constant Protocols.HTTP.HTTP_FOUND

Description

RFC 2616 section 10.3.3: 302 Found


Constant HTTP_GONE

constant Protocols.HTTP.HTTP_GONE

Description

RFC 2616 section 10.4.11: 410 Gone


Constant HTTP_GW_TIMEOUT

constant Protocols.HTTP.HTTP_GW_TIMEOUT

Description

RFC 2616 section 10.5.5: 504 Gateway Timeout


Constant HTTP_HEADERS_TOO_LARGE

constant Protocols.HTTP.HTTP_HEADERS_TOO_LARGE

Description

RFC 6585 section 5: 431 Request Header Fields Too Large


Constant HTTP_INTERNAL_ERR

constant Protocols.HTTP.HTTP_INTERNAL_ERR

Description

RFC 2616 section 10.5.1: 500 Internal Server Error


Constant HTTP_LEGALLY_RESTRICTED

constant Protocols.HTTP.HTTP_LEGALLY_RESTRICTED

Description

RFC 7725 section 3: 451 Unavailable For Legal Reasons


Constant HTTP_LENGTH_REQ

constant Protocols.HTTP.HTTP_LENGTH_REQ

Description

RFC 2616 section 10.4.12: 411 Length Required


Constant HTTP_METHOD_INVALID

constant Protocols.HTTP.HTTP_METHOD_INVALID

Description

RFC 2616 section 10.4.6: 405 Method Not Allowed


Constant HTTP_MISDIRECTED_REQ

constant Protocols.HTTP.HTTP_MISDIRECTED_REQ

Description

RFC 7540 section 9.1.2: 421 Misdirected Request


Constant HTTP_MOVED_PERM

constant Protocols.HTTP.HTTP_MOVED_PERM

Description

RFC 2616 section 10.3.2: 301 Moved Permanently


Constant HTTP_MULTIPLE

constant Protocols.HTTP.HTTP_MULTIPLE

Description

RFC 2616 section 10.3.1: 300 Multiple Choices


Constant HTTP_NET_AUTH_REQUIRED

constant Protocols.HTTP.HTTP_NET_AUTH_REQUIRED

Description

RFC 6585 section 6: 511 Network Authentication Required


Constant HTTP_NONAUTHORATIVE

constant Protocols.HTTP.HTTP_NONAUTHORATIVE

Description

RFC 2616 section 10.2.4: 203 Non-Authorative Information


Constant HTTP_NOT_ACCEPTABLE

constant Protocols.HTTP.HTTP_NOT_ACCEPTABLE

Description

RFC 2616 section 10.4.7: 406 Not Acceptable


Constant HTTP_NOT_EXTENDED

constant Protocols.HTTP.HTTP_NOT_EXTENDED

Description

RFC 2774 section 7: 510 Not Extended (obsolete)


Constant HTTP_NOT_FOUND

constant Protocols.HTTP.HTTP_NOT_FOUND

Description

RFC 2616 section 10.4.5: 404 Not Found


Constant HTTP_NOT_IMPL

constant Protocols.HTTP.HTTP_NOT_IMPL

Description

RFC 2616 section 10.5.2: 501 Not Implemented


Constant HTTP_NOT_MODIFIED

constant Protocols.HTTP.HTTP_NOT_MODIFIED

Description

RFC 2616 section 10.3.5: 304 Not Modified


Constant HTTP_NO_CONTENT

constant Protocols.HTTP.HTTP_NO_CONTENT

Description

RFC 2616 section 10.2.5: 204 No Content


Constant HTTP_OK

constant Protocols.HTTP.HTTP_OK

Description

RFC 2616 section 10.2.1: 200 OK


Constant HTTP_PARTIAL_CONTENT

constant Protocols.HTTP.HTTP_PARTIAL_CONTENT

Description

RFC 2616 section 10.2.7: 206 Partial Content


Constant HTTP_PAY

constant Protocols.HTTP.HTTP_PAY

Description

RFC 2616 section 10.4.3: 402 Payment Required


Constant HTTP_PERM_REDIRECT

constant Protocols.HTTP.HTTP_PERM_REDIRECT

Description

RFC 7538 section 3: 308 Permanent Redirect


Constant HTTP_PRECOND_FAILED

constant Protocols.HTTP.HTTP_PRECOND_FAILED

Description

RFC 2616 section 10.4.13: 412 Precondition Failed


Constant HTTP_PRECOND_REQUIRED

constant Protocols.HTTP.HTTP_PRECOND_REQUIRED

Description

RFC 6585 section 3: 428 Precondition required


Constant HTTP_PROXY_AUTH_REQ

constant Protocols.HTTP.HTTP_PROXY_AUTH_REQ

Description

RFC 2616 section 10.4.8: 407 Proxy Authentication Required


Constant HTTP_REQ_TOO_LARGE

constant Protocols.HTTP.HTTP_REQ_TOO_LARGE

Description

RFC 2616 section 10.4.14: 413 Request Entity Too Large


Constant HTTP_RESET_CONTENT

constant Protocols.HTTP.HTTP_RESET_CONTENT

Description

RFC 2616 section 10.2.6: 205 Reset Content


Constant HTTP_SEE_OTHER

constant Protocols.HTTP.HTTP_SEE_OTHER

Description

RFC 2616 section 10.3.4: 303 See Other


Constant HTTP_SWITCH_PROT

constant Protocols.HTTP.HTTP_SWITCH_PROT

Description

RFC 2616 section 10.1.2: 101 Switching protocols


Constant HTTP_TEMP_REDIRECT

constant Protocols.HTTP.HTTP_TEMP_REDIRECT

Description

RFC 2616 section 10.3.8: 307 Temporary Redirect


Constant HTTP_TIMEOUT

constant Protocols.HTTP.HTTP_TIMEOUT

Description

RFC 2616 section 10.4.9: 408 Request Timeout


Constant HTTP_TOO_MANY_REQUESTS

constant Protocols.HTTP.HTTP_TOO_MANY_REQUESTS

Description

RFC 6585 section 4: 429 Too Many Requests


Constant HTTP_UNAUTH

constant Protocols.HTTP.HTTP_UNAUTH

Description

RFC 2616 section 10.4.2: 401 Unauthorized


Constant HTTP_UNAVAIL

constant Protocols.HTTP.HTTP_UNAVAIL

Description

RFC 2616 section 10.5.4: 503 Service Unavailable


Constant HTTP_UNSUPP_MEDIA

constant Protocols.HTTP.HTTP_UNSUPP_MEDIA

Description

RFC 2616 section 10.4.16: 415 Unsupported Media Type


Constant HTTP_UNSUPP_VERSION

constant Protocols.HTTP.HTTP_UNSUPP_VERSION

Description

RFC 2616 section 10.5.6: 505 HTTP Version Not Supported


Constant HTTP_URI_TOO_LONG

constant Protocols.HTTP.HTTP_URI_TOO_LONG

Description

RFC 2616 section 10.4.15: 414 Request-URI Too Long


Constant HTTP_USE_PROXY

constant Protocols.HTTP.HTTP_USE_PROXY

Description

RFC 2616 section 10.3.6: 305 Use Proxy


Constant TCN_VARIANT_NEGOTIATES

constant Protocols.HTTP.TCN_VARIANT_NEGOTIATES

Description

RFC 2295 section 8.1: 506 Variant Also Negotiates


Constant TLS_TOO_EARLY

constant Protocols.HTTP.TLS_TOO_EARLY

Description

RFC 8470 section 5.2: 425 Too Early


Constant TLS_UPGRADE_REQUIRED

constant Protocols.HTTP.TLS_UPGRADE_REQUIRED

Description

RFC 2817 section 4.2: 426 Upgrade Required

Class Protocols.HTTP.Query

Description

Open and execute an HTTP query.

Example

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; }


Variable errno

int Protocols.HTTP.Query.errno

Description

Errno copied from the connection or simulated for async operations.

Note

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.


Variable headers

mapping Protocols.HTTP.Query.headers

Description

Headers as a mapping. All header names are in lower case, for convinience.


Variable host
Variable real_host
Variable port

string Protocols.HTTP.Query.host
string Protocols.HTTP.Query.real_host
int Protocols.HTTP.Query.port

Description

Connected host and port.

Used to detect whether keep-alive can be used.


Variable hostname_cache

mapping(string:array(string)) Protocols.HTTP.Query.hostname_cache

Description

Set this to a global mapping if you want to use a cache, prior of calling *request().


Variable timeout
Variable maxtime

int Protocols.HTTP.Query.timeout
int Protocols.HTTP.Query.maxtime

Description

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.

Note

These values only have effect in asynchroneous calls


Variable ok

int Protocols.HTTP.Query.ok

Description

Tells if the connection is successfull.


Variable protocol

string Protocols.HTTP.Query.protocol

Description

Protocol string, ie "HTTP/1.0".


Variable status
Variable status_desc

int Protocols.HTTP.Query.status
string Protocols.HTTP.Query.status_desc

Description

Status number and description (eg 200 and "ok").


Method `()

int res = Protocols.HTTP.Query()()

Description

Wait for connection to complete.

Returns

Returns 1 on successfull connection, 0 on failure.


Method async_fetch

void async_fetch(function(:void) callback, mixed ... extra)

Description

Fetch all data in background.

See also

timed_async_fetch(), async_request(), set_callbacks()


Method set_callbacks
Method async_request

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)

Description

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

Returns the called object


Method cast

(array)Protocols.HTTP.Query()

Returns
Array
mapping 0

Headers

string 1

Data

string 2

Protocol

int 3

Status

string 4

Status description


Method cast

(mapping)Protocols.HTTP.Query()

Returns

The header mapping ORed with the following mapping.

"protocol" : string

The protocol.

"status" : int

The status code.

"status_desc" : string

The status description.

"data" : string

The returned data.


Method cast

(string)Protocols.HTTP.Query()

Description

Gives back the answer as a string.


Method close

void close()

Description

Close all associated file descriptors.


Method data

string data(int|void max_length)

Description

Gives back the data as a string.


Method datafile

Protocols.HTTP.Query.PseudoFile datafile()

Description

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.

See also

file()


Method downloaded_bytes

int downloaded_bytes()

Description

Gives back the number of downloaded bytes.


Method file

Protocols.HTTP.Query.PseudoFile file()
Protocols.HTTP.Query.PseudoFile file(mapping newheaders, void|mapping removeheaders)

Description

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.

See also

datafile()


Method thread_request

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)

Description

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

Returns the called object.


Method timed_async_fetch

void timed_async_fetch(function(this_program, __unknown__ ... :void) ok_callback, function(this_program, __unknown__ ... :void) fail_callback, mixed ... extra)

Description

Like async_fetch(), except with a timeout and a corresponding fail callback function.

See also

async_fetch(), async_request(), set_callbacks()


Method total_bytes

int total_bytes()

Description

Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.


Method unicode_data

string unicode_data()

Description

Gives back data, but decoded according to the content-type character set.

See also

data

Class Protocols.HTTP.Query.PseudoFile

Description

Minimal simulation of a Stdio.File object.

Objects of this class are returned by file() and datafile().

Note

Do not attempt further queries using this Query object before having read all data.


Method close

void close()


Method read

string read(int n, bool|void not_all)

Class Protocols.HTTP.Session


Typedef URL

typedef string|Standards.URI|SessionURL Protocols.HTTP.Session.URL

Description

A URL which is either a string a Standards.URI or a SessionURL.


Variable default_headers

mapping Protocols.HTTP.Session.default_headers

Description

Default HTTP headers.


Variable follow_redirects

int Protocols.HTTP.Session.follow_redirects

Description

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.

Bugs

Loops will currently not be detected, only the limit works to stop loops.

See also

Request.follow_redirects


Variable hostname_cache

mapping Protocols.HTTP.Session.hostname_cache

Description

Cache of hostname to IP lookups. Given to and used by the Query objects.


Variable maximum_connection_reuse

int Protocols.HTTP.Session.maximum_connection_reuse

Description

Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.


Variable maximum_connections_per_server

int Protocols.HTTP.Session.maximum_connections_per_server

Description

Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.


Variable maximum_total_connections

int Protocols.HTTP.Session.maximum_total_connections

Description

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.


Variable time_to_keep_unused_connections

int|float Protocols.HTTP.Session.time_to_keep_unused_connections

Description

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.


Method async_get_url
Method async_put_url
Method async_delete_url
Method async_post_url

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)

Description

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.


Method encode_cookies
Method decode_cookies

string encode_cookies()
void decode_cookies(string data, void no_clear)

Description

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.


Method get_url
Method post_url
Method put_url
Method delete_url

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)

Description

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.


Method get_cookies

array(string) get_cookies(Standards.URI|SessionURL for_url, void|bool no_delete)

Description

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.


Method get_url_nice
Method get_url_data
Method post_url_nice
Method post_url_data

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)

Description

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.


Method give_me_connection

Query give_me_connection(Standards.URI url)

Description

Request a Query object suitable to use for the given URL. This may be a reused object from a keep-alive connection.


Method return_connection

void return_connection(Standards.URI url, Query query)

Description

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.


Method set_cookie

void set_cookie(Cookie cookie, Standards.URI|zero who)

Description

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.


Method set_http_cookie

void set_http_cookie(string cookie, Standards.URI at)

Description

Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.

Class Protocols.HTTP.Session.Request

Description

Request


Variable con

Query Protocols.HTTP.Session.Request.con

Description

Raw connection object


Variable cookie_encountered

function(string, Standards.URI:mixed|void) Protocols.HTTP.Session.Request.cookie_encountered

Description

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.


Variable follow_redirects

int Protocols.HTTP.Session.Request.follow_redirects

Description

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.

Bugs

Loops will currently not be detected, only the limit works to stop loops.


Variable url_requested

Standards.URI Protocols.HTTP.Session.Request.url_requested

Description

URL requested (set by prepare_method). This will update according to followed redirects.


Method _destruct

protected void _destruct()

Description

_destruct is called when an object is destructed.


Method destroy

void destroy()

Description

But since this clears the HTTP connection from the Request object, it can also be used to reuse a Request object.


Method do_async

Request do_async(array(string|int|mapping) args)

Description

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.

Returns

The called object.

See also

set_callbacks, prepare_method, do_sync, do_thread


Method do_sync

Request|zero do_sync(array(string|int|mapping) args)

Description

Perform a request synchronously. Get arguments from prepare_method.

Returns

0 upon failure, this object upon success

See also

prepare_method, do_async, do_thread


Method do_thread

Request do_thread(array(string|int|mapping) args)

Description

Start a request in the background, using a thread. Call wait to wait for the thread to finish. Get arguments from prepare_method.

Returns

The called object.

See also

prepare_method, do_sync, do_async, wait

Note

do_thread does not rerun redirections automatically


Method prepare_method

array(string|int|mapping) prepare_method(string method, URL url, void|mapping query_variables, void|mapping extra_headers, void|string data)

Description

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).


Method set_callbacks

void set_callbacks(function(mixed ... :mixed)|zero headers, function(mixed ... :mixed)|zero data, function(mixed ... :mixed)|zero fail, mixed ... callback_arguments)

Description

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.


Method wait

Request|zero wait()

Description

Wait for the request thread to finish.

Returns

0 upon failure, or the called object upon success.

See also

do_thread

Class Protocols.HTTP.Session.SessionURL

Description

Class to store URL+referer


Inherit URI

inherit Standards.URI : URI


Variable referer

URL Protocols.HTTP.Session.SessionURL.referer

Description

the referer to this URL


Method create

Protocols.HTTP.Session.SessionURL Protocols.HTTP.Session.SessionURL(URL uri, URL base_uri, URL _referer)

Description

instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables

Module Protocols.HTTP.Authentication

Description

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.

Example

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; }


Method make_authenticator

Client make_authenticator(string|array(string) hdrs, string user, string password, void|string realm)

Description

Create an authenticator for a server responding with the given HTTP authentication header. Currently only works for one realm.

Parameter hdrs

The WWW-Authenticate HTTP header or headers.

Parameter user

The username to use.

Parameter password

The plaintext password.

Parameter realm

Optionally the realm the user and password is valid in. If omitted, the authentication will happen in whatever realm the server is presenting.


Method split_header

mapping(string:string) split_header(string hdr)

Description

Split client generated Authorization header into its parts.

Class Protocols.HTTP.Authentication.BasicClient

Description

HTTP Basic authentication client.

Class Protocols.HTTP.Authentication.Client

Description

Abstract Client class.

Class Protocols.HTTP.Authentication.DigestClient

Description

Abstract HTTP Digest authentication client.


Inherit Digest

inherit Digest : Digest

Class Protocols.HTTP.Authentication.DigestMD5Client

Description

HTTP Digest authentication client using MD5.


Inherit DigestClient

inherit DigestClient : DigestClient


Inherit DigestMD5

inherit DigestMD5 : DigestMD5

Class Protocols.HTTP.Authentication.DigestMD5Server

Description

HTTP Digest server implementation using MD5.


Inherit DigestMD5

inherit DigestMD5 : DigestMD5


Inherit DigestServer

inherit DigestServer : DigestServer

Class Protocols.HTTP.Authentication.DigestMD5sessServer

Description

Implements the session version "MD5-sess" of the MD5 HTTP Digest authentication. Used identically to DigestMD5Server.


Inherit DigestMD5Server

inherit DigestMD5Server : DigestMD5Server

Class Protocols.HTTP.Authentication.DigestSHA256Client

Description

HTTP Digest authentication client using SHA256.


Inherit DigestClient

inherit DigestClient : DigestClient


Inherit DigestSHA256

inherit DigestSHA256 : DigestSHA256

Class Protocols.HTTP.Authentication.DigestSHA256Server

Description

HTTP Digest server implementation using SHA256.


Inherit DigestSHA256

inherit DigestSHA256 : DigestSHA256


Inherit DigestServer

inherit DigestServer : DigestServer

Class Protocols.HTTP.Authentication.DigestSHA256sessServer

Description

Implements the session version "SHA256-sess" of the SHA256 HTTP Digest authentication. Used identically to DigestSHA256Server.


Inherit DigestSHA256Server

inherit DigestSHA256Server : DigestSHA256Server

Class Protocols.HTTP.Authentication.DigestSHA512256Client

Description

HTTP Digest authentication client using SHA512/256.


Inherit DigestClient

inherit DigestClient : DigestClient


Inherit DigestSHA512256

inherit DigestSHA512256 : DigestSHA512256

Class Protocols.HTTP.Authentication.DigestSHA512256Server

Description

HTTP Digest server implementation using SHA512/256.


Inherit DigestSHA512256

inherit DigestSHA512256 : DigestSHA512256


Inherit DigestServer

inherit DigestServer : DigestServer

Class Protocols.HTTP.Authentication.DigestSHA512256sessServer

Description

Implements the session version "SHA-512-256-sess" of the SHA512/256 HTTP Digest authentication. Used identically to DigestSHA512256Server.


Inherit DigestSHA512256Server

inherit DigestSHA512256Server : DigestSHA512256Server

Class Protocols.HTTP.Authentication.DigestServer

Description

Abstract HTTP Digest implementation.


Inherit Digest

inherit Digest : Digest


Variable realm

string Protocols.HTTP.Authentication.DigestServer.realm

Description

The current realm of the authentication.


Method auth

Concurrent.Future auth(string hdr, string method, string path)

Description

Authenticate a request.

Parameter hdr

The value of the Authorization header. Zero is acceptable, but will produce an unconditional rejection.

Parameter method

This is the HTTP method used, typically "GET" or "POST".

Parameter path

This is the path of the request.


Method challenge

string(7bit) challenge()

Description

Creates a challenge header value for the WWW-Authenticate header in 401 responses.


Method create

Protocols.HTTP.Authentication.DigestServer Protocols.HTTP.Authentication.DigestServer(void|string(8bit) realm, void|string(8bit) key)

Parameter realm

The realm to be authenticated.

Parameter 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.


Method get_hashed_password

Concurrent.Future get_hashed_password(string user)

Description

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.


Method get_password

Concurrent.Future get_password(string user)

Description

Function intended to be overloaded that returns a future that will resolve to the given users password.

See also

get_hashed_password

Module Protocols.HTTP.Promise

Description

This HTTP client module utilises the Concurrent.Promise and Concurrent.Future classes and only does asynchronous calls.

Example
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);
});

Method get_url
Method post_url
Method put_url
Method delete_url

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)

Description

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


Method do_method

Concurrent.Future do_method(string http_method, Protocols.HTTP.Session.URL url, void|Arguments args)

Description

Fetch an URL with the http_method method.


Method set_timeout
Method set_maxtime

void set_timeout(int t)
void set_maxtime(int t)

Description

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.

See also

Arguments

Class Protocols.HTTP.Promise.Arguments

Description

Class representing the arguments to give to get_url(), post_url() put_url(), delete_url() and do_method().


Variable data

void|string|mapping Protocols.HTTP.Promise.Arguments.data

Description

POST data


Variable extra_args

array(mixed) Protocols.HTTP.Promise.Arguments.extra_args

Description

Extra arguments that will end up in the Result object


Variable follow_redirects

bool Protocols.HTTP.Promise.Arguments.follow_redirects

Description

Should redirects be followed. Default is true.


Variable headers

mapping(string:string) Protocols.HTTP.Promise.Arguments.headers

Description

Additional request headers


Variable maxtime

int Protocols.HTTP.Promise.Arguments.maxtime

Description

Request timeout


Variable timeout

int Protocols.HTTP.Promise.Arguments.timeout

Description

Data fetch timeout


Variable variables

mapping(string:mixed) Protocols.HTTP.Promise.Arguments.variables

Description

Query variables


Method create

Protocols.HTTP.Promise.Arguments Protocols.HTTP.Promise.Arguments(void|mapping(string:mixed) args)

Description

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.

Class Protocols.HTTP.Promise.Result

Description

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().


Variable charset

string|zero Protocols.HTTP.Promise.Result.charset

Description

Returns the charset of the requested document, if given by the response headers.

Note

Read only


Variable content_encoding

string Protocols.HTTP.Promise.Result.content_encoding

Description

Returns the content encoding of the response if set by the remote server.

Note

Read only


Variable content_type

string Protocols.HTTP.Promise.Result.content_type

Description

Returns the content type of the requested document

Note

Read only


Variable data

string Protocols.HTTP.Promise.Result.data

Description

Raw data body of the request

See also

get()


Variable extra_args

array(mixed) Protocols.HTTP.Promise.Result.extra_args

Description

Extra arguments set in the Arguments object.


Variable headers

mapping Protocols.HTTP.Promise.Result.headers

Description

The HTTP response headers


Variable host

string Protocols.HTTP.Promise.Result.host

Description

The host that was called in the request


Variable length

int Protocols.HTTP.Promise.Result.length

Description

Returns the value of the content-length header.

Note

Read only


Variable status

int Protocols.HTTP.Promise.Result.status

Description

The HTTP status of the response, e.g 200, 201, 404 and so on.


Variable status_description

string Protocols.HTTP.Promise.Result.status_description

Description

The textual representation of status.


Variable url

Standards.URI Protocols.HTTP.Promise.Result.url

Description

Returns the requested URL


Method get

string get()

Description

The response body, i.e the content of the requested URL

Class Protocols.HTTP.Promise.Session

Description

Internal class for the actual HTTP requests


Inherit parent

inherit Protocols.HTTP.Session : parent

Module Protocols.HTTP.Server


Constant HeaderParser

constant Protocols.HTTP.Server.HeaderParser

Description

Fast HTTP header parser.


Constant http_decode_string

constant Protocols.HTTP.Server.http_decode_string


Method extension_to_type

string extension_to_type(string extension)

Description

Looks up the file extension in a table to return a suitable MIME type.


Method filename_to_extension

string filename_to_extension(string filename)

Description

Determine the extension for a given filename.


Method filename_to_type

string filename_to_type(string filename)

Description

Looks up the file extension in a table to return a suitable MIME type.


Method http_date

string http_date(int time)

Description

Makes a time notification suitable for the HTTP protocol.

Parameter time

The time in seconds since the 00:00:00 UTC, January 1, 1970

Returns

The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT


Method http_decode_date

int http_decode_date(string data)

Description

Decode a HTTP date to seconds since 1970 (UTC)

Returns

zero (UNDEFINED) if the given string isn't a HTTP date


Method http_decode_urlencoded_query

mapping(string:string|array(string)) http_decode_urlencoded_query(string query, void|mapping dest)

Description

Decodes an URL-encoded query into a mapping.

Class Protocols.HTTP.Server.Port

Description

The simplest server possible. Binds a port and calls a callback with request_program objects.


Variable request_program

object|function(:void)|program Protocols.HTTP.Server.Port.request_program


Method close

void close()

Description

Closes the HTTP port.


Method create

Protocols.HTTP.Server.Port Protocols.HTTP.Server.Port(function(.Request:void) callback, void|int portno, void|string interface, void|int reuse_port)

Class Protocols.HTTP.Server.Request

Description

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

Variable body_raw

string Protocols.HTTP.Server.Request.body_raw

Description

raw unparsed body of the request (raw minus request line and headers)


Variable connection_timeout_delay

int Protocols.HTTP.Server.Request.connection_timeout_delay

Description

connection timeout, delay until connection is closed while waiting for the correct headers:


Variable cookies

mapping(string:string) Protocols.HTTP.Server.Request.cookies

Description

cookies set by client


Variable full_query

string Protocols.HTTP.Server.Request.full_query

Description

full resource requested, including attached GET query


Variable misc

mapping Protocols.HTTP.Server.Request.misc

Description

external use only


Variable my_fd

Stdio.NonblockingStream Protocols.HTTP.Server.Request.my_fd

Description

The socket that this request came in on.


Variable not_query

string Protocols.HTTP.Server.Request.not_query

Description

resource requested minus any attached query


Variable protocol

string Protocols.HTTP.Server.Request.protocol

Description

request protocol and version, eg. HTTP/1.0


Variable query

string Protocols.HTTP.Server.Request.query

Description

query portion of requested resource, starting after the first "?"


Variable raw

string Protocols.HTTP.Server.Request.raw

Description

raw unparsed full request (headers and body)


Variable request_headers

mapping(string:string|array(string)) Protocols.HTTP.Server.Request.request_headers

Description

all headers included as part of the HTTP request, ie content-type.


Variable request_raw

string Protocols.HTTP.Server.Request.request_raw

Description

full request line (request_type + full_query + protocol)


Variable request_type

string Protocols.HTTP.Server.Request.request_type

Description

HTTP request method, eg. POST, GET, etc.


Variable response

mapping Protocols.HTTP.Server.Request.response

Description

the response sent to the client (for use in the log_cb)


Variable send_timeout_delay

int Protocols.HTTP.Server.Request.send_timeout_delay

Description

send timeout (no activity for this period with data in send buffer) in seconds, default is 180


Variable variables

mapping(string:string|array(string)) Protocols.HTTP.Server.Request.variables

Description

all variables included as part of a GET or POST request.


Method finish

void finish(int clean)

Description

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.


Method get_ip

string|zero get_ip()

Description

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.


Method opportunistic_tls

void opportunistic_tls(string s)

Description

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.


Method response_and_finish

void response_and_finish(mapping m, function(:void)|void _log_cb)

Description

return a properly formatted response to the HTTP client

Parameter m

Contains elements for generating a response to the client.

"data" : string|array(string|object)

Data to be returned to the client. Can be an array of objects which are concatenated and sent to the client.

"file" : object

File object, the contents of which will be returned to the client.

"error" : int

HTTP error code

"size" : int

length of content returned. If file is provided, size bytes will be returned to client.

"modified" : string

contains optional modification date.

"type" : string

contains optional content-type

"extra_heads" : mapping

contains a mapping of additional headers to be returned to client.

"server" : string

contains the server identification header.


Method sent_data

int sent_data()

Description

Returns the amount of data sent.


Method set_mode

void set_mode(int mode)

Parameter mode

A number of integer flags bitwise ored together to determine the mode of operation. SHUFFLER: Use the Shuffler to send out the data.

Enum Protocols.HTTP.Server.Request.ChunkedState


Constant READ_SIZE
Constant READ_CHUNK
Constant READ_POSTNL
Constant READ_TRAILER
Constant FINISHED

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

Class Protocols.HTTP.Server.SSLPort

Description

A very simple SSL server. Binds a port and calls a callback with request_program objects.


Inherit Port

inherit SSL.Port : Port


Variable request_program

object|function(:void)|program Protocols.HTTP.Server.SSLPort.request_program


Method create

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)

Description

Create a HTTPS (HTTP over SSL) server.

Parameter callback

The function run when a request is received. takes one argument of type Request.

Parameter port

The port number to bind to, defaults to 443.

Parameter interface

The interface address to bind to.

Parameter key

An optional SSL secret key, provided in binary format, such as that created by Standards.PKCS.RSA.private_key().

Parameter certificate

An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.

Parameter reuse_port

If true, enable SO_REUSEPORT if the OS supports it. See Stdio.Port.bind for more information


Method new_connection

protected void new_connection()

Description

The port accept callback

13.2. TLS/SSL

Module SSL

Description

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.

See also

File, Port, Context, Constants.CertificatePair, Constants

Class SSL.Alert

Description

Alert packet.


Inherit Packet

inherit .Packet : Packet

Description

Based on the base Packet.


Method create

SSL.Alert SSL.Alert(int(1..2) level, int(8bit) description, ProtocolVersion version, string|void message)

Class SSL.Buffer

Description

String buffer with the possibility to read and write data as they would be formatted in structs.


Inherit Buffer

inherit Stdio.Buffer : Buffer


Method add_int_array

this_program add_int_array(array(int) data, int(8bit) item_size, int(0..) len)

Description

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.


Method add_string_array

this_program add_string_array(array(string(8bit)) data, int(0..) item_size, int(0..) len)

Description

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.


Method create

SSL.Buffer SSL.Buffer(void|string(8bit)|Stdio.Buffer s)

Description

Create a new buffer, optionally initialized with the value s.


Method read_int_array

array(int) read_int_array(int(8bit) item_size, int(0..) len)

Description

Reads an array of integers as written by add_int_array from the buffer.


Method read_string_array

array(string(8bit)) read_string_array(int(0..) item_size, int(0..) len)

Description

Reads an array of strings as written by add_string_array from the buffer.

Class SSL.ClientConnection

Description

Client-side connection state.


Inherit Connection

inherit Connection : Connection


Variable client_cert_types
Variable client_cert_distinguished_names

array(int)|zero SSL.ClientConnection.client_cert_types
array(string(8bit))|zero SSL.ClientConnection.client_cert_distinguished_names

Description

A few storage variables for client certificate handling on the client side.


Method create

SSL.ClientConnection SSL.ClientConnection(Context ctx, string(8bit)|void server_name, Session|void session)

Description

Initialize a new ClientConnection.

Parameter ctx

Context to use.

Parameter server_name

Optional host name of the server.

Parameter session

Optional Session to resume.


Method handle_handshake

int(-1..1) handle_handshake(int type, Buffer input, Stdio.Buffer raw)

Description

Do handshake processing.

Parameter type

One of HANDSHAKE_*.

Parameter input

The contents of the packet.

Parameter raw

The raw packet received (needed for supporting SSLv2 hello messages).

Returns

This function returns:

0

If handshaking is in progress.

1

If handshaking has completed.

-1

If a fatal error occurred.

It uses the send_packet() function to transmit packets.


Method send_renegotiate

void send_renegotiate()

Description

Renegotiate the connection (client initiated).

Sends a client_hello to force a new round of handshaking.

Class SSL.Connection

Description

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 States: 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.

Note

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().

See also

ClientConnection, ServerConnection, Context, Session, File, State


Constant window_size

private constant int SSL.Connection.window_size

Description

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.


Variable application_protocol

string(8bit)|zero SSL.Connection.application_protocol

Description

Selected ALPN (RFC 7301) protocol (if any).

Note

Note that this is a connection property, and needs to be renegotiated on session resumption.


Variable client_random
Variable server_random

string(8bit)|zero SSL.Connection.client_random
string(8bit)|zero SSL.Connection.server_random

Description

Random cookies, sent and received with the hello-messages.


Variable ke

.Cipher.KeyExchange|zero SSL.Connection.ke

Description

The active Cipher.KeyExchange (if any).


Variable sent

int|zero SSL.Connection.sent

Description

Number of application data bytes sent by us.


Variable sequence_mask

private int SSL.Connection.sequence_mask

Description

Bitmask representing sequence numbers for accepted received packets in the interval [next_seq_num-window_size..next_seq_num-2].

Note

The packet with seqence number next_seq_num-1 is implicitly known to have been received.


Variable state

ConnectionState SSL.Connection.state

Description

Bitfield with the current connection state.


Method create

SSL.Connection SSL.Connection(Context ctx)

Description

Initialize the connection state.

Parameter ctx

The context for the connection.


Method derive_master_secret

void derive_master_secret(string(8bit) premaster_secret)

Description

Derive the master secret from the premaster_secret and the random seeds, and configure the keys.


Method describe_state

string describe_state()

Description

Returns a string describing the current connection state.


Method got_data

string(8bit)|int(-1..1) got_data(string(8bit) data)

Description

Main receive handler.

Parameter data

String of data received from the peer.

Returns

Returns one of:

string(0)

Returns an empty string if there's neither application data nor errors (eg during the initial handshake).

string(8bit)

Returns a string of received application data.

int(1)

Returns 1 if the peer has closed the connection.

int(-1)

Returns -1 if an error has occurred.

These are the main cases of errors:

  • There was a low-level protocol communications failure (the data didn't look like an SSL packet), in which case the alert_callback will be called with the raw packet data. This can eg be used to detect HTTP clients connecting to an HTTPS server and similar.

  • The peer has sent an Alert packet, and handle_alert() for it has returned -1.

  • The peer has sent an unsupported/illegal sequence of packets, in which case a suitable Alert will have been generated and queued for sending to the peer.

This function is intended to be called from an i/o read callback.


Method handle_alert

int(-1..1) handle_alert(int level, int description)

Description

Handle an alert received from the peer.

Parameter level

Alert level; either ALERT_warning or ALERT_fatal.

Parameter description

Alert description code; one of indices(SSL.Constants.ALERT_descriptions).

Returns
-1

A Fatal error occurred and processing should stop.

0

Processing can continue.

1

Connection should close.


Method handle_handshake

int(-1..1) handle_handshake(int type, Buffer input, Stdio.Buffer raw)

Description

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.


Method mark_seq_num

void mark_seq_num(int num)

Description

Mark seqence number num as seen and accepted.

This will cause valid_seq_nump() to return 0 for it if it shows up again.


Method new_cipher_states

void new_cipher_states()

Description

Generate new pending cipher states.


Method query_write_queue_size

int query_write_queue_size()

Description

Returns the number of packets queued for writing.

Returns

Returns the number of times to_write() can be called before it stops returning non-empty strings.


Method recv_packet

protected Packet|zero recv_packet()

Description

Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.


Method send_close

void send_close()

Description

Initiate close.


Method send_packet

void send_packet(Packet packet, int|void priority)

Description

Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.


Method send_renegotiate

void send_renegotiate()

Description

Renegotiate the connection.


Method send_streaming_data

int send_streaming_data(string(8bit) data)

Description

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.


Method set_alert_callback

void set_alert_callback(function(object, int|object, string:void) callback)

Description

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.


Method shutdown

void shutdown()

Description

Remove cyclic references as best we can.


Method to_write

int(-1..2) to_write(Stdio.Buffer output)

Description

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.

See also

query_write_queue_size(), send_streaming_data().


Method valid_seq_nump

int valid_seq_nump(int num)

Description

Check whether num is a valid seqence number for a new packet.

Class SSL.Connection.HandshakeFragment


Variable mt
Variable len
Variable offset
Variable data

int SSL.Connection.HandshakeFragment.mt
int SSL.Connection.HandshakeFragment.len
int SSL.Connection.HandshakeFragment.offset
string(8bit) SSL.Connection.HandshakeFragment.data


Method __create__

protected local void __create__(int mt, int len, int offset, string(8bit) data)


Method create

SSL.Connection.HandshakeFragment SSL.Connection.HandshakeFragment(int mt, int len, int offset, string(8bit) data)

Class SSL.Context

Description

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.

See also

File, Port, Standards.X509


Variable advertised_protocols

array(string(8bit))|zero SSL.Context.advertised_protocols

Description

List of advertised protocols using using TLS application level protocol negotiation.


Variable auth_level

int SSL.Context.auth_level

Description

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.


Variable client_auth_methods

array(int) SSL.Context.client_auth_methods

Description

The possible client authentication methods. Used only if auth_level is AUTH_ask or AUTH_require. Generated by set_authorities.


Variable ecc_curves

array(int) SSL.Context.ecc_curves

Description

Supported elliptical curve cipher curves in order of preference. Defaults to all supported curves, ordered with the largest curves first.


Variable enable_renegotiation

bool SSL.Context.enable_renegotiation

Description

If set enable SSL/TLS protocol renegotiation.

Defaults to 1 (enabled).

Note

RFC 7540 section 9.2.1 requires this to be turned off after Protocols.HTTP2 communication has started.


Variable encrypt_then_mac

bool SSL.Context.encrypt_then_mac

Description

Attempt to enable encrypt-then-mac mode. Defaults to 1.

Deprecated

Replaced by extensions.


Variable extensions

multiset(int) SSL.Context.extensions

Description

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.

Constants.EXTENSION_renegotiation_info

Protection against renegotiation attack (RFC 5746).

Constants.EXTENSION_max_fragment_length

Allows negotiation of the maximum fragment size (RFC 6066 section 4).

Constants.EXTENSION_encrypt_then_mac

Attempts to address attacks against block ciphers (RFC 7366).

Constants.EXTENSION_application_layer_protocol_negotiation

Required to support more than one protocol on the same TLS port (RFC 7639).

Constants.EXTENSION_signature_algorithms

Required to select which out of several certificates to use (RFC 5246 section 7.4.1.4.1).

Constants.EXTENSION_ec_point_formats

Required for elliptic curve key exchange (RFC 4492 section 5.1.2).

Constants.EXTENSION_elliptic_curves

Required for elliptic curve key exchange (RFC 4492 section 5.1.1).

Constants.EXTENSION_server_name

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).

Constants.EXTENSION_session_ticket

Support session resumption without server-side state (RFC 4507 and RFC 5077).

Constants.EXTENSION_next_protocol_negotiation

Not supported by Pike. The server side will just check that the client packets are correctly formatted.

Constants.EXTENSION_signed_certificate_timestamp

Not supported by Pike. The server side will just check that the client packets are correctly formatted.

Constants.EXTENSION_early_data

Needed for TLS 1.3 0-RTT handshake. EXPERIMENTAL.

Constants.EXTENSION_padding

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.

Constants.EXTENSION_truncated_hmac

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).

Constants.EXTENSION_heartbeat

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 heartbleed_probe (RFC 6520).

Constants.EXTENSION_extended_master_secret

Binds the master secret to important session parameters to protect against man in the middle attacks (RFC 7627).

See also

RFC 6066


Variable ffdhe_groups

array(int) SSL.Context.ffdhe_groups

Description

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).


Variable heartbleed_probe

bool SSL.Context.heartbleed_probe

Description

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.


Variable max_sessions

int SSL.Context.max_sessions

Description

Maximum number of sessions to keep in the cache.


Variable min_version
Variable max_version

int SSL.Context.min_version
int SSL.Context.max_version

Description

The accepted range of versions for the client/server. List specific versions in supported_versions instead.

Deprecated

Replaced by supported_versions.


Variable packet_max_size

int SSL.Context.packet_max_size

Description

The maximum amount of data that is sent in each SSL packet by File. A value between 1 and Constants.PACKET_MAX_SIZE.


Variable preferred_compressors

array(int) SSL.Context.preferred_compressors

Description

Lists the supported compression algorithms in order of preference.

Defaults to ({ COMPRESSION_null }) due to SSL attacks that target compression.


Variable preferred_suites

array(int)|zero SSL.Context.preferred_suites

Description

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.


Variable private_ffdhe_groups

mapping(int(508..511):Crypto.DH.Parameters) SSL.Context.private_ffdhe_groups

Description

DHE parameter lookup for the FFDHE private range.

Add any custom FFDHE-groups here.

Defaults to the empty mapping.

Note

If you add any groups here, you will also need to update ffdhe_groups accordingly.


Variable random

function(int(0..):string(8bit)) SSL.Context.random

Description

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.


Variable require_trust

int SSL.Context.require_trust

Description

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.

Deprecated

Replaced by auth_level.


Variable session_lifetime

int SSL.Context.session_lifetime

Description

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.


Variable signature_algorithms

array(int) SSL.Context.signature_algorithms

Description

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.

Note

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.

See also

get_signature_algorithms()


Variable supported_versions

array(ProtocolVersion) SSL.Context.supported_versions

Description

List of supported versions, in order of preference. Defaults to PROTOCOL_TLS_1_2, PROTOCOL_TLS_1_1 and PROTOCOL_TLS_1_0.


Variable trusted_issuers_cache

mapping(string(8bit):array(Standards.X509.Verifier)) SSL.Context.trusted_issuers_cache

Description

Mapping from DER-encoded issuer to Standards.X509.Verifiers compatible with eg Standards.X509.verify_certificate() and Standards.X509.load_authorities().

See also

get_trusted_issuers(), set_trusted_issuers()


Variable use_cache

int SSL.Context.use_cache

Description

Non-zero to enable caching of sessions


Variable verifier_algorithms

mapping(Standards.ASN1.Types.Identifier:Crypto.Hash) SSL.Context.verifier_algorithms

Description

Mapping of supported verifier algorithms to hash implementation.

See also

Standards.X509.get_algorithms()


Variable verify_certificates

int SSL.Context.verify_certificates

Description

Determines whether certificates presented by the peer are verified, or just accepted as being valid.

Deprecated

Replaced by auth_level.


Method add_cert

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)

Description

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.

Parameter key

Private key matching the first certificate in certs.

Supported key types are currently:

Crypto.RSA.State

Rivest-Shamir-Adelman.

Crypto.DSA.State

Digital Signing Algorithm.

Crypto.ECC.Curve.ECDSA

Elliptic Curve Digital Signing Algorithm.

This key MUST match the public key in the first certificate in certs.

Parameter certs

A chain of X509.v1 or X509.v3 certificates, with the local certificate first and root-most certificate last.

Parameter 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.

Parameter cp

An alternative is to send an initialized CertificatePair.

Throws

The function performs various validations of the key and certs, and throws errors if the validation fails.

See also

find_cert()


Method alert_factory

Alert alert_factory(SSL.Connection con, int level, int description, ProtocolVersion version, string|void message, mixed|void trace)

Description

Alert factory.

This function may be overloaded to eg obtain logging of generated alerts.

Parameter con

Connection which caused the alert.

Parameter level

Level of alert.

Parameter description

Description code for the alert.

Parameter message

Optional log message for the alert.

Note

Not all alerts are fatal, and some (eg ALERT_close_notify) are used during normal operation.


Method configure_suite_b

void configure_suite_b(int(128..)|void min_keylength, int(0..)|void strictness_level)

Description

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.

Parameter min_keylength

Minimum supported key length in bits. Either 128 or 192.

Parameter strictness_level

Allow additional suites.

(2..)

Strict mode.

Allow only the Suite B suites from RFC 6460 and TLS 1.2.

1

Transitional mode.

Also allow the transitional suites from RFC 5430 for use with TLS 1.0 and 1.1.

0

Permissive mode (default).

Also allow other suites that conform to the minimum key length.

Note

This function is only present when Suite B compliant operation is possible (ie both elliptic curves and GCM are available).

Note

Note also that for Suite B server operation compliant certificates need to be added with add_cert().

See also

get_suites()


Method decode_ticket

Session|zero decode_ticket(string(8bit) ticket)

Description

Decode a session ticket and return the corresponding session if valid or zero if invalid.

Note

The default implementation just calls lookup_session().

Override this function (and encode_ticket()) to implement server-side state-less session resumption.

See also

encode_ticket(), lookup_session()


Method encode_ticket

array(string(8bit)|int)|zero encode_ticket(Session session)

Description

Generate a session ticket for a session.

Note

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.

Returns
Array
string(8bit) 0

Non-empty string with the ticket.

int 1

Lifetime hint for the ticket.

Note

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...

See also

decode_ticket(), record_session(), RFC 4507 section 3.3


Method filter_weak_suites

void filter_weak_suites(int min_keylength)

Description

Filter cipher suites from preferred_suites that don't have a key with an effective length of at least min_keylength bits.


Method find_cert_domain

array(CertificatePair)|zero find_cert_domain(string(8bit) domain)

Description

Look up a suitable set of certificates for the specified domain. UNDEFINED if no certificate was found. Called only by the Server.


Method find_cert_issuer

array(CertificatePair)|zero find_cert_issuer(array(string) ders)

Description

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.


Method get_authorities

array(string) get_authorities()

Description

Get the list of allowed authorities. See set_authorities.


Method get_certificates

array(CertificatePair) get_certificates()

Description

Returns a list of all server certificates added with add_cert.


Method get_export_rsa_key

Crypto.RSA get_export_rsa_key()

Description

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.


Method get_psk

optional string(8bit) get_psk(string(8bit) id)

Description

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.


Method get_psk_hint

optional string(8bit) get_psk_hint()

Description

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.


Method get_psk_id

optional string(8bit) get_psk_id(string(8bit) hint)

Description

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.


Method get_signature_algorithms

array(int) get_signature_algorithms(array(int)|void signature_algorithms)

Description

Get the (filtered) set of locally supported signature algorithms.

See also

signature_algorithms


Method get_suites

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)

Description

Get the prioritized list of supported cipher suites that satisfy the requirements.

Parameter min_keylength

Minimum supported effective keylength in bits. Defaults to 128. Specify -1 to enable null ciphers.

Parameter ke_mode

Level of protection for the key exchange.

0

Require forward secrecy (ephemeral keys).

1

Also allow certificate based key exchanges.

2

Also allow anonymous server key exchange. Note that this allows for man in the middle attacks.

Parameter 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.

Parameter blacklisted_kes

Multiset of key exchange methods that are NOT to be used.

Parameter blacklisted_hashes

Multiset of hash algoriths that are NOT to be used.

Parameter blacklisted_ciphermodes

Multiset of cipher modes that are NOT to be used.

Note

The list of suites is also filtered on the current settings of supported_versions.

Note

Note that the effective keylength may differ from the actual keylength for old ciphers where there are known attacks.


Method get_trusted_issuers

array(array(string(8bit))) get_trusted_issuers()

Description

Get the list of trusted issuers. See set_trusted_issuers.


Method get_versions

array(ProtocolVersion) get_versions(ProtocolVersion client)

Description

Returns a list of possible versions to use, given the version in the client hello header.


Method lookup_session

Session|zero lookup_session(string id)

Description

Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.


Method new_session

Session new_session()

Description

Create a new session.


Method offers_tickets

bool offers_tickets()

Description

Signals if the context will offer a session ticket via encode_ticket().


Method purge_session

void purge_session(Session s)

Description

Invalidate a session for resumption and remove it from the cache.


Method record_session

void record_session(Session s)

Description

Add a session to the cache (if caching is enabled).


Method set_authorities

void set_authorities(array(string) a)

Description

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.


Method set_trusted_issuers

void set_trusted_issuers(array(array(string(8bit))) issuers)

Description

Sets the list of trusted certificate issuers.

Parameter 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.


Method sort_suites

array(int) sort_suites(array(int) suites)

Description

Sort a set of cipher suites according to our preferences.

Returns

Returns the array sorted with the most preferrable (aka "best") cipher suite first.

Note

The original array (suites) is modified destructively, but is not the same array as the result.

Class SSL.File

Description

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.


Variable application_protocol

string SSL.File.application_protocol

Description

The application protocol chosen by the client during application layer protocol negotiation (ALPN).

Note

Read only


Variable fragment_max_size

protected int SSL.File.fragment_max_size

Description

The max amount of data to send in each packet. Initialized from the context when the object is created.


Method _destruct

protected void _destruct()

Description

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.

See also

close


Method accept

bool accept(string|void pending_data)

Description

Configure as server and set up the connection.

Parameter 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

Returns 0 on handshaking failure in blocking mode, and otherwise 1.

See also

connect()


Method backend_once

protected int(0)|float backend_once(int|void nonwaiting_mode)

Description

Run one pass of the backend.


Method close

int close(void|string how, void|int clean_close, void|int dont_throw)

Description

Close the connection. Both the read and write ends are always closed

Parameter how

This argument is only for Stdio.File compatibility and must be either "rw" or 0.

Parameter 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.

Parameter 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.

Note

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.

Note

I/O errors from both reading and writing might occur in blocking mode.

Note

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.

See also

shutdown


Method connect

SSL.Session|zero connect(string|void dest_addr, SSL.Session|void session)

Description

Configure as client and set up the connection.

Parameter dest_addr

Optional name of the server that we are connected to.

Parameter session

Session to resume (if any).

Returns

Returns 0 on handshaking failure in blocking mode, and otherwise the Session object for the connection.

Throws

Throws an error if a connection already has been established.

See also

accept()


Method create

SSL.File SSL.File(Stdio.File stream, SSL.Context ctx)

Description

Create an SSL connection over an open stream.

Parameter stream

Open socket or pipe to create the connection over.

Parameter 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.

Note

The operation mode defaults to nonblocking mode.

See also

accept(), connect()


Method errno

int errno()

Returns

Returns the current error number for the connection. Notable values are:

0

No error

System.EPIPE

Connection closed by other end.


Method get_peer_certificate_info

mapping get_peer_certificate_info()

Returns

Returns peer certificate information, if any.


Method get_peer_certificates

array get_peer_certificates()

Returns

Returns the peer certificate chain, if any.


Method get_server_name

mixed get_server_name()

Returns

Returns the server name indication value for the connection.


Method internal_poll

protected void internal_poll()

Description

Check whether any callbacks may need to be called.

Always run via the real_backend.

See also

schedule_poll()


Method is_open

int is_open()

Returns

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.

Note

In Pike 7.8 and earlier, this function returned zero in the case above where it now returns 2.


Method linger

bool linger(int(-1..65535)|void seconds)

Description

Set the linger time on close().


Method query_accept_callback

function(void|object, void|mixed:int)|zero query_accept_callback()

Returns

Returns the current accept callback.

See also

set_accept_callback


Method query_address

string query_address(int|void arg)

Returns

Returns the address and port of the connection.

See Stdio.File.query_address for details.

See also

Stdio.File.query_address


Method query_alert_callback

function(object, int|object, string:void)|zero query_alert_callback()

Returns

Returns the current alert callback.

See also

set_alert_callback


Method query_application_protocol

string(8bit) query_application_protocol()

Returns

Returns the negotiated application level protocol (ALPN) if any, and otherwise 0 (zero).

See also

Context.advertised_protocols


Method query_backend

Pike.Backend query_backend()

Description

Return the backend used for the file callbacks.

See also

set_backend


Method query_buffer_mode

array(Stdio.Buffer|int(0)) query_buffer_mode()

Description

Get the active input and output buffers that have been set with set_buffer_mode() (if any).

Returns

Returns an array with two elements:

Array
Stdio.Buffer 0

The current input buffer.

Stdio.Buffer 1

The current output buffer.

See also

set_buffer_mode()


Method query_callbacks

array(function(mixed, void|string:int)|zero) query_callbacks()

Returns

Returns the currently set callbacks in the same order as the arguments to set_callbacks.

See also

set_callbacks, set_nonblocking


Method query_close_callback

function(void|mixed:int)|zero query_close_callback()

Returns

Returns the current close callback.

See also

set_close_callback, set_nonblocking, query_callbacks


Method query_connection

.Connection query_connection()

Description

Return the SSL connection object.

This returns the low-level SSL.connection object.


Method query_context

SSL.Context query_context()

Description

Return the SSL context object.


Method query_fd

int query_fd()

Returns

Returns the file descriptor number associated with this object.


Method query_id

mixed query_id()

Returns

Returns the currently set id.

See also

set_id


Method query_read_callback

Stdio.read_callback_t|zero query_read_callback()

Returns

Returns the current read callback.

See also

set_read_callback, set_nonblocking, query_callbacks


Method query_stream

Stdio.File query_stream()

Description

Return the underlying stream.

Note

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.

See also

shutdown


Method query_suite

int query_suite()

Description

Return the currently active cipher suite.


Method query_timeout

int(0)|float query_timeout()

Description

Get the timeout for blocking operations.

See also

set_timeout()


Method query_version

ProtocolVersion query_version()

Description

Return the currently active SSL/TLS version.


Method query_write_callback

Stdio.write_callback_t|zero query_write_callback()

Returns

Returns the current write callback.

See also

set_write_callback, set_nonblocking, query_callbacks


Method read

string read(void|int length, void|bool not_all)

Description

Read some (decrypted) data from the connection. Works like Stdio.File.read.

Note

I/O errors from both reading and writing might occur in blocking mode.

See also

write


Method renegotiate

int renegotiate()

Description

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.

Note

The read buffer is not cleared - a read() afterwards will return data from both before and after the renegotiation.

Bugs

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.


Method schedule_poll

protected void schedule_poll()

Description

Schedule calling of any relevant callbacks the next time the real_backend is run.

See also

internal_poll()


Method set_accept_callback

void set_accept_callback(function(void|object, void|mixed:int)|zero accept)

Description

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).

Note

Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.

See also

set_nonblocking, set_callbacks, query_accept_callback, query_callbacks


Method set_alert_callback

void set_alert_callback(function(object, int|object, string:void)|zero alert)

Description

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().

Note

This object is part of a cyclic reference whenever this is set, just like setting any other callback.

Note

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.

See also

query_alert_callback


Method set_backend

void set_backend(Pike.Backend backend)

Description

Set the backend used for the file callbacks.

See also

query_backend


Method set_blocking

void set_blocking()

Description

Set the stream in blocking mode. All but the alert callback are zapped.

Note

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.

Note

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.

Note

Prior to version 7.5.12, this function didn't clear the accept callback.

See also

set_nonblocking, set_blocking_keep_callbacks, set_nonblocking_keep_callbacks


Method set_blocking_keep_callbacks

void set_blocking_keep_callbacks()

Description

Set blocking mode like set_blocking, but don't alter any callbacks.

See also

set_blocking, set_nonblocking


Method set_buffer_mode

void set_buffer_mode(Stdio.Buffer|int(0) in, Stdio.Buffer|int(0) out)

Description

Toggle the file to Buffer mode.

In this mode reading and writing will be done via Buffer objects, in the directions you included buffers.

Parameter in

Input buffer. If this buffer is non-empty, its contents will be returned after any already received data.

Parameter out

Output buffer. If this buffer is non-empty, its contents will be sent after any data already queued for sending.

See also

query_buffer_mode()


Method set_callbacks

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)

Description

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.

Bugs

read_oob and write_oob are currently ignored.

See also

set_read_callback, set_write_callback, set_close_callback, set_accept_callback, query_callbacks


Method set_close_callback

void set_close_callback(function(void|mixed:int)|zero close)

Description

Install a function to be called when the connection is closed, either normally or due to an error (use errno to retrieve it).

See also

query_close_callback, set_nonblocking, query_callbacks


Method set_id

void set_id(mixed id)

Description

Set the value to be sent as the first argument to the callbacks installed by set_callbacks.

See also

query_id


Method set_nodelay

bool set_nodelay(bool|void state)

Description

Controle Nagle's Algorithm (RFC 896).


Method set_nonblocking

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)

Description

Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.

Note

Prior to version 7.5.12, this function didn't set the accept callback.

Bugs

read_oob and write_oob are currently ignored.

See also

set_callbacks, query_callbacks, set_nonblocking_keep_callbacks, set_blocking


Method set_nonblocking_keep_callbacks

void set_nonblocking_keep_callbacks()

Description

Set nonblocking mode like set_nonblocking, but don't alter any callbacks.

See also

set_nonblocking, set_blocking, set_blocking_keep_callbacks


Method set_read_callback

void set_read_callback(Stdio.read_callback_t|zero read)

Description

Install a function to be called when data is available.

See also

query_read_callback, set_nonblocking, query_callbacks


Method set_timeout

void set_timeout(int(0)|float seconds)

Description

Set timeout for blocking operations.

Parameter seconds

Time in seconds allowed for blocking operations before triggering a timeout. Set to 0 (zero) to disable.

By default there is no timeout.

See also

query_timeout()


Method set_write_callback

void set_write_callback(Stdio.write_callback_t|zero write)

Description

Install a function to be called when data can be written.

See also

query_write_callback, set_nonblocking, query_callbacks


Method shutdown

Stdio.File shutdown()

Description

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.

See also

close, set_alert_callback


Method write

int write(string|array(string) data, mixed ... args)

Description

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.

Note

This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.

Note

I/O errors from both reading and writing might occur in blocking mode.

See also

read

Enum SSL.File.CloseState


Constant ABRUPT_CLOSE
Constant STREAM_OPEN
Constant STREAM_UNINITIALIZED
Constant NORMAL_CLOSE
Constant CLEAN_CLOSE

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

Class SSL.Packet

Description

SSL Record Layer. Handle formatting and parsing of packets.


Variable marginal_size

protected int SSL.Packet.marginal_size

Description

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.


Method create

SSL.Packet SSL.Packet(ProtocolVersion version, void|int extra)

Parameter version

The version sent packets will be created for.

Parameter extra

Additional fragment size, over the 2^14 bytes for a plaintext TLS fragment.


Method recv

int(-1..1) recv(Stdio.Buffer data)

Description

Receive data read from the network.

Parameter data

Raw data from the network.

Returns

Returns a 1 data if packet is complete, otherwise 0.

If there's an error, an alert object is returned.


Method send

void send(Stdio.Buffer output)

Description

Serialize the packet for sending.

Class SSL.Port

Description

Interface similar to Stdio.Port.


Inherit socket

inherit Stdio.Port : socket


Variable accept_callback

function(mixed|void:void) SSL.Port.accept_callback


Variable accept_queue

protected ADT.Queue SSL.Port.accept_queue

Description

Queue of new SSL.Files that have been negotiated.


Variable ctx

Context SSL.Port.ctx

Description

Context to use for the connections.

Note

The Context is created (by calling context_factory()) on first access to the variable.

Note

Read only


Method accept

File accept()

Description

Get the next pending File from the accept_queue.

Returns

Returns the next pending File if any, and 0 (zero) if there are none.


Method bind

int bind(int port, function(mixed|void:int)|void callback, string|void ip, int|void reuse_port)

Description

Bind an SSL port.

Parameter port

Port number to bind.

Parameter 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().

Parameter ip

Optional IP-number to bind.

Parameter reuse_port

If true, enable SO_REUSEPORT if the OS supports it.

Returns

Returns 1 if binding of the port succeeded, and 0 (zero) on failure.

See also

Stdio.Port()->bind(), File()->set_accept_callback(), listen_fd()


Method context_factory

Context context_factory()

Description

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

Returns the Context to be used with this Port.


Method create

SSL.Port SSL.Port(Context|void ctx)

Description

Create a new port for accepting SSL connections.

Parameter ctx

Context to be used with this Port.

If left out, it will be created on demand on first access by calling context_factory().

See also

bind(), listen_fd()


Method finished_callback

void finished_callback(SSL.File f, mixed|void id)

Description

SSL connection accept callback.

Parameter 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 Files on the accept queue.

If there's no accept_callback, then the File will have to be retrieved from the queue by calling accept().


Method listen_fd

int listen_fd(int fd, function(mixed|void:int)|void callback)

Description

Set up listening for SSL connections on an already opened fd.

Parameter fd

File descriptor to listen on.

Parameter 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 Files will be enqueued for later retrieval with accept().

Returns

Returns 1 if listening on the fd succeeded, and 0 (zero) on failure.

See also

Stdio.Port()->listen_fd(), File()->set_accept_callback(), bind()


Method set_accept_callback

void set_accept_callback(function(:void)|void accept_callback)

Description

Set the accept callback.


Method socket_accept

Stdio.File socket_accept()

Description

Low-level accept.

See also

Stdio.Port()->accept()


Method ssl_callback

void ssl_callback(mixed id)

Description

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.

Note

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().

See also

bind(), finished_callback(), set_accept_callback()

Class SSL.ServerConnection

Description

Server-side connection state.


Inherit Connection

inherit Connection : Connection


Method handle_handshake

int(-1..1) handle_handshake(int type, Buffer input, Stdio.Buffer raw)

Description

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.

Note

On entry the handshake header has been removed from input.


Method send_renegotiate

void send_renegotiate()

Description

Renegotiate the connection (server initiated).

Sends a hello_request to force a new round of handshaking.


Method server_derive_master_secret

protected bool server_derive_master_secret(Buffer data)

Description

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.


Method server_key_exchange_packet

protected Packet|zero server_key_exchange_packet()

Description

Initialize the KeyExchange ke, and generate a HANDSHAKE_server_key_exchange packet if the key exchange needs one.

Class SSL.Session

Description

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.


Variable cert_data

mapping|zero SSL.Session.cert_data

Description

Information about the certificate in use by the peer, such as issuing authority, and verification status.


Variable certificate_chain

array(string(8bit))|zero SSL.Session.certificate_chain

Description

Our certificate chain


Variable cipher_spec

Cipher.CipherSpec|zero SSL.Session.cipher_spec

Description

Information about the encryption method derived from the cipher_suite.


Variable cipher_suite

int SSL.Session.cipher_suite

Description

Constant defining a choice of keyexchange, encryption and mac algorithm.


Variable compression_algorithm

int|zero SSL.Session.compression_algorithm

Description

Always COMPRESSION_null.


Variable curve

Crypto.ECC.Curve|zero SSL.Session.curve

Description

The ECC curve selected by the key exchange.

KE_ecdh_ecdsa

The curve from the server certificate.

KE_ecdh_rsa
KE_ecdhe_ecdsa

The curve selected for the ECDHE key exchange (typically the largest curve supported by both the client and the server).

KE_ecdhe_rsa
KE_ecdh_anon

Variable ecc_curves

array(int) SSL.Session.ecc_curves

Description

Supported elliptical curve cipher curves in order of preference.


Variable ecc_point_format

int SSL.Session.ecc_point_format

Description

The selected elliptical curve point format.

Note

May be -1 to indicate that there's no supported overlap between the server and client.


Variable encrypt_then_mac

int SSL.Session.encrypt_then_mac

Description

Negotiated encrypt-then-mac mode.


Variable extended_master_secret

bool SSL.Session.extended_master_secret

Description

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.


Variable ffdhe_groups

array(int)|zero SSL.Session.ffdhe_groups

Description

Supported finite field diffie-hellman groups in order of preference.

int(0)

Zero indicates that none have been specified.

array(zero)

The empty array indicates that none are supported.

array(int)

List of supported groups, with the most preferred first.


Variable heartbeat_mode

HeartBeatModeType SSL.Session.heartbeat_mode

Description

Heartbeat mode.


Variable identity

string(8bit)|zero SSL.Session.identity

Description

Identifies the session to the server


Variable last_activity

int SSL.Session.last_activity

Description

When this session object was used last.


Variable master_secret

string(8bit)|zero SSL.Session.master_secret

Description

48 byte secret shared between the client and the server. Used for deriving the actual keys.


Variable max_packet_size

int SSL.Session.max_packet_size

Description

The max fragment size requested by the client.


Variable peer_certificate_chain

array(string(8bit))|zero SSL.Session.peer_certificate_chain

Description

The peer certificate chain


Variable peer_public_key

Crypto.Sign.State|zero SSL.Session.peer_public_key

Description

The peer's public key (from the certificate).


Variable private_key

Crypto.Sign.State|zero SSL.Session.private_key

Description

Our private key.


Variable server_name

string(8bit)|zero SSL.Session.server_name

Description

RFC 6066 section 3.1 (SNI)


Variable signature_algorithms

array(int) SSL.Session.signature_algorithms

Description

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.


Variable ticket

string(8bit)|zero SSL.Session.ticket

Description

Alternative identification of the session to the server.

See also

RFC 4507, RFC 5077


Variable ticket_expiry_time

int|zero SSL.Session.ticket_expiry_time

Description

Expiry time for ticket.


Variable truncated_hmac

bool SSL.Session.truncated_hmac

Description

Indicates that the packet HMACs should be truncated to the first 10 bytes (80 bits). Cf RFC 3546 section 3.5.


Variable version

ProtocolVersion|zero SSL.Session.version

Description

Negotiated protocol version.


Method generate_keys

array(string(8bit)) generate_keys(string(8bit) client_random, string(8bit) server_random, ProtocolVersion version)

Description

Generates keys appropriate for the SSL version given in version, based on the client_random and server_random.

Returns
Array
string 0

Client write MAC secret

string 1

Server write MAC secret

string 2

Client write key

string 3

Server write key

string 4

Client write IV

string 5

Server write IV


Method has_required_certificates

bool has_required_certificates()

Description

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.


Method is_supported_cert

protected bool is_supported_cert(CertificatePair cp, int ke_mask, int h_max, ProtocolVersion version, array(int) ecc_curves)

Description

Used to filter certificates not supported by the peer.

Parameter cp

Candidate CertificatePair.

Parameter version

Negotiated version of SSL.

Parameter ecc_curves

The set of ecc_curves supported by the peer.


Method is_supported_suite

bool is_supported_suite(int suite, int ke_mask, ProtocolVersion version)

Description

Used to filter the set of cipher suites suggested by the peer based on our available certificates.

Parameter suite

Candidate cipher suite.

Parameter ke_mask

The bit mask of the key exchange algorithms supported by the set of available certificates.

Parameter version

The negotiated version of SSL/TLS.


Method new_client_states

array(State) new_client_states(.Connection con, string(8bit) client_random, string(8bit) server_random, ProtocolVersion version)

Description

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

Returns
Array
SSL.State read_state

Read state

SSL.State write_state

Write state


Method new_server_states

array(State) new_server_states(.Connection con, string(8bit) client_random, string(8bit) server_random, ProtocolVersion version)

Description

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

Returns
Array
SSL.State read_state

Read state

SSL.State write_state

Write state


Method reusable_as

bool reusable_as(Session other)

Description

Returns true if this session object can be used in place of the session object other.


Method select_cipher_suite

int select_cipher_suite(array(CertificatePair) certs, array(int) cipher_suites, ProtocolVersion version)

Description

Selects an apropriate certificate, authentication method and cipher suite for the parameters provided by the client.

Parameter certs

The list of CertificatePairs that are applicable to the server_name of this session.

Parameter cipher_suites

The set of cipher suites that the client and server have in common.

Parameter 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.


Method set_cipher_suite

int set_cipher_suite(int suite, ProtocolVersion version, array(int)|zero signature_algorithms, int max_hash_size)

Description

Sets the proper authentication method and cipher specification for the given parameters.

Parameter suite

The cipher suite to use, selected from the set that the client claims to support.

Parameter version

The SSL protocol version to use.

Parameter signature_algorithms

The set of signature algorithms tuples that the client claims to support.

Parameter max_hash_size

Method set_compression_method

void set_compression_method(int compr)

Description

Sets the compression method. Currently only COMPRESSION_null and COMPRESSION_deflate are supported.


Method validate_rsa_key

bool validate_rsa_key(Crypto.RSA.State rsa)

Description

Validate that KE RSA key is more than 512 bits or exportable.

Class SSL.State

Description

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.


Variable crypt

Cipher.CipherAlgorithm SSL.State.crypt

Description

Encryption or decryption object.


Variable mac

Cipher.MACAlgorithm SSL.State.mac

Description

Message Authentication Code


Variable next_seq_num

int SSL.State.next_seq_num

Description

64-bit sequence number.


Variable salt

string SSL.State.salt

Description

TLS 1.2 IV salt. This is used as a prefix for the IV for the AEAD cipher algorithms.


Variable session

Session SSL.State.session

Description

Information about the used algorithms.


Variable tls_iv

int SSL.State.tls_iv

Description

TLS IV prefix length.


Method decrypt_packet

Alert|Packet decrypt_packet(Packet packet)

Description

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.


Method encrypt_packet

Alert|Packet encrypt_packet(Packet packet, Context ctx)

Description

Encrypts a packet (including deflating and MAC-generation).

Class SSL.https

Description

Dummy HTTPS server/client

Class SSL.https.Conn


Variable sslfile

SSL.File SSL.https.Conn.sslfile


Method __create__

protected local void __create__(SSL.File sslfile)

Module SSL.Cipher

Description

Encryption and MAC algorithms used in SSL.


Method P_hash

protected string(8bit) P_hash(Crypto.Hash hashfn, string(8bit) secret, string(8bit) seed, int len)

Description

Hashfn is either a Crypto.MD5, Crypto.SHA or Crypto.SHA256.


Method lookup

CipherSpec|zero lookup(int suite, ProtocolVersion|int version, array(int)|zero signature_algorithms, int max_hash_size)

Description

Lookup the crypto parameters for a cipher suite.

Parameter suite

Cipher suite to lookup.

Parameter version

Version of the SSL/TLS protocol to support.

Parameter signature_algorithms

The set of SignatureScheme values that are supported by the other end.

Parameter max_hash_size

The maximum hash size supported for the signature algorithm.

Returns

Returns 0 (zero) for unsupported combinations, otherwise returns an initialized CipherSpec for the suite.


Method prf_sha384

string(8bit) prf_sha384(string(8bit) secret, string(8bit) label, string(8bit) seed, int len)

Description

This Pseudo Random Function is used to derive secret keys for some ciphers suites defined after TLS 1.2.


Method prf_sha512

string(8bit) prf_sha512(string(8bit) secret, string(8bit) label, string(8bit) seed, int len)

Description

This Pseudo Random Function could be used to derive secret keys for some ciphers suites defined after TLS 1.2.


Method prf_ssl_3_0

string(8bit) prf_ssl_3_0(string(8bit) secret, string(8bit) label, string(8bit) seed, int len)

Description

This Pseudo Random Function is used to derive secret keys in SSL 3.0.

Note

The argument label is ignored.


Method prf_tls_1_0

string(8bit) prf_tls_1_0(string(8bit) secret, string(8bit) label, string(8bit) seed, int len)

Description

This Pseudo Random Function is used to derive secret keys in TLS 1.0 and 1.1.


Method prf_tls_1_2

string(8bit) prf_tls_1_2(string(8bit) secret, string(8bit) label, string(8bit) seed, int len)

Description

This Pseudo Random Function is used to derive secret keys in TLS 1.2.

Class SSL.Cipher.CipherAlgorithm

Description

Cipher algorithm interface.


Method block_size

int(0..) block_size()

Description

Return the block size for this crypto.


Method set_encrypt_key
Method set_decrypt_key

this_program set_encrypt_key(string)
this_program set_decrypt_key(string)

Description

Set the key used for encryption/decryption, and enter encryption mode.

Class SSL.Cipher.CipherSpec

Description

Cipher specification.


Variable bulk_cipher_algorithm

program SSL.Cipher.CipherSpec.bulk_cipher_algorithm

Description

The algorithm to use for the bulk of the transfered data.


Variable explicit_iv_size

int SSL.Cipher.CipherSpec.explicit_iv_size

Description

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.


Variable hash

Crypto.Hash SSL.Cipher.CipherSpec.hash

Description

The hash algorithm for signing the handshake.

Usually the same hash as is the base for the prf.

Note

Only used in TLS 1.2 and later.


Variable hash_size

int SSL.Cipher.CipherSpec.hash_size

Description

The number of bytes in the MAC hashes.


Variable is_exportable

int SSL.Cipher.CipherSpec.is_exportable

Description

Indication whether the combination uses strong or weak (aka exportable) crypto.


Variable iv_size

int SSL.Cipher.CipherSpec.iv_size

Description

The number of bytes of random data needed for initialization vectors.


Variable ke_factory

program SSL.Cipher.CipherSpec.ke_factory

Description

Key exchange factory.


Variable key_bits

int SSL.Cipher.CipherSpec.key_bits

Description

The effective number of bits in key_material.

This is typically key_material * 8, but for eg DES this is key_material * 7.


Variable key_material

int SSL.Cipher.CipherSpec.key_material

Description

The number of bytes of key material used on initialization.


Variable mac_algorithm

program SSL.Cipher.CipherSpec.mac_algorithm

Description

The Message Authentication Code to use for the packets.


Variable max_bytes

int SSL.Cipher.CipherSpec.max_bytes

Description

The number of bytes that is safe to send before we must renegotiate the keys.


Variable prf

function(string(8bit), string(8bit), string(8bit), int:string(8bit)) SSL.Cipher.CipherSpec.prf

Description

The Pseudo Random Function to use.

See also

prf_ssl_3_0(), prf_tls_1_0(), prf_tls_1_2()


Variable signature_alg

SignatureAlgorithm SSL.Cipher.CipherSpec.signature_alg

Description

The signature algorithm used for key exchange signatures.


Variable signature_hash

HashAlgorithm SSL.Cipher.CipherSpec.signature_hash

Description

The hash algorithm used for key exchange signatures.


Method sign

Stdio.Buffer sign(object session, string(8bit) cookie, Stdio.Buffer struct)

Description

The function used to sign packets.


Method verify

bool verify(object session, string data, Stdio.Buffer input)

Description

The function used to verify the signature for packets.

Class SSL.Cipher.DES


Inherit State

inherit Crypto.DES.CBC.Buffer.State : State

Class SSL.Cipher.DES3


Inherit State

inherit Crypto.DES3.CBC.Buffer.State : State

Class SSL.Cipher.KeyExchange

Description

KeyExchange method base class.


Variable anonymous

int SSL.Cipher.KeyExchange.anonymous

Description

Indicates whether a certificate isn't required.


Variable context
Variable session
Variable connection
Variable client_version

object SSL.Cipher.KeyExchange.context
object SSL.Cipher.KeyExchange.session
object SSL.Cipher.KeyExchange.connection
ProtocolVersion SSL.Cipher.KeyExchange.client_version


Variable message_was_bad

int SSL.Cipher.KeyExchange.message_was_bad

Description

Indicates whether the key exchange has failed due to bad MACs.


Method __create__

protected local void __create__(object context, object session, object connection, ProtocolVersion client_version)


Method client_key_exchange_packet

string(8bit) client_key_exchange_packet(Stdio.Buffer packet_data, ProtocolVersion version)

Returns

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.


Method create

SSL.Cipher.KeyExchange SSL.Cipher.KeyExchange(object context, object session, object connection, ProtocolVersion client_version)


Method got_client_key_exchange

string(8bit)|int(8bit) got_client_key_exchange(Stdio.Buffer data, ProtocolVersion version)

Parameter data

Payload from a HANDSHAKE_client_key_exchange.

Returns

Premaster secret or alert number.

Note

May set message_was_bad and return a fake premaster secret.


Method got_server_key_exchange

int got_server_key_exchange(Stdio.Buffer input, string client_random, string server_random)

Parameter 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
0

Returns zero on success.

-1

Returns negative on verification failure.


Method init_client

bool init_client()

Description

Initialize for client side use.

Returns

Returns 1 on success, and 0 (zero) on failure.


Method init_server

bool init_server()

Description

Initialize for server side use.

Returns

Returns 1 on success, and 0 (zero) on failure.


Method make_key_share_offer

optional void make_key_share_offer(Stdio.Buffer offer)

Description

TLS 1.3 and later.

Generate a key share offer for the configured named group (currently only implemented in KeyShareECDHE and KeyShareDHE).


Method parse_server_key_exchange

Stdio.Buffer parse_server_key_exchange(Stdio.Buffer input)

Parameter input

Stdio.Buffer with the content of a HANDSHAKE_server_key_exchange.

Returns

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.


Method receive_key_share_offer

optional string(8bit) receive_key_share_offer(string(8bit) offer)

Description

TLS 1.3 and later.

Receive a key share offer key exchange for the configured group (currently only implemented in KeyShareECDHE and KeyShareDHE).

Note

Clears the secret state.

Returns

Returns the shared pre-master key.


Method server_key_exchange_packet

string(8bit)|zero server_key_exchange_packet(string client_random, string server_random)

Description

The default implementation calls server_key_params() to generate the base payload.

Returns

Returns the signed payload for a HANDSHAKE_server_key_exchange.


Method server_key_params

Stdio.Buffer server_key_params()

Returns

Returns an Stdio.Buffer with the HANDSHAKE_server_key_exchange payload.


Method set_group

optional void set_group(int group)

Description

TLS 1.3 and later.

Set the group or curve to be used.

Class SSL.Cipher.KeyExchangeDH

Description

Key exchange for KE_dh_dss and KE_dh_dss.

KeyExchange that uses Diffie-Hellman with a key from a DSS certificate.


Inherit KeyExchangeDHE

inherit KeyExchangeDHE : KeyExchangeDHE

Class SSL.Cipher.KeyExchangeDHE

Description

KeyExchange for KE_dhe_rsa, KE_dhe_dss and KE_dh_anon.

KeyExchange that uses Diffie-Hellman to generate an Ephemeral key.


Inherit KeyExchange

inherit KeyExchange : KeyExchange


Variable parameters

Crypto.DH.Parameters SSL.Cipher.KeyExchangeDHE.parameters

Description

Finite field Diffie-Hellman parameters.


Method got_client_key_exchange

string(8bit)|int(8bit) got_client_key_exchange(Stdio.Buffer input, ProtocolVersion version)

Returns

Premaster secret or alert number.


Method set_other

protected bool set_other(Gmp.smpz o)

Description

Set the value received from the peer.

Returns

Returns 1 if o is valid for the set parameters.

Otherwise returns UNDEFINED.

Class SSL.Cipher.KeyExchangeDHEPSK

Description

Key exchange for KE_dhe_psk.


Inherit DHE

inherit KeyExchangeDHE : DHE


Inherit PSK

inherit KeyExchangePSK : PSK

Class SSL.Cipher.KeyExchangeECDH

Description

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.

Note

Deprecated in RFC 8422 section 5.5.


Inherit KeyExchangeECDHE

inherit KeyExchangeECDHE : KeyExchangeECDHE

Class SSL.Cipher.KeyExchangeECDHE

Description

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

inherit KeyExchange : KeyExchange


Method got_client_key_exchange

string(8bit)|int(8bit) got_client_key_exchange(Stdio.Buffer data, ProtocolVersion version)

Returns

Premaster secret or alert number.

Class SSL.Cipher.KeyExchangeECDHEPSK

Description

Key exchange for KE_ecdhe_psk.


Inherit ECDHE

inherit KeyExchangeECDHE : ECDHE


Inherit PSK

inherit KeyExchangePSK : PSK

Class SSL.Cipher.KeyExchangeExportRSA

Description

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

inherit KeyExchangeRSA : KeyExchangeRSA

Class SSL.Cipher.KeyExchangeKRB

Description

Key exchange for KE_krb.

KeyExchange that uses Kerberos (RFC 2712).


Inherit KeyExchange

inherit KeyExchange : KeyExchange


Method got_client_key_exchange

string(8bit)|int got_client_key_exchange(Stdio.Buffer input, ProtocolVersion version)

Returns

Premaster secret or alert number.

Class SSL.Cipher.KeyExchangeNULL

Description

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

inherit KeyExchange : KeyExchange


Method got_client_key_exchange

string(8bit) got_client_key_exchange(Stdio.Buffer data, ProtocolVersion version)

Returns

Premaster secret or alert number.

Class SSL.Cipher.KeyExchangePSK

Description

Key exchange for KE_psk, pre shared keys.


Inherit KeyExchange

inherit KeyExchange : KeyExchange

Class SSL.Cipher.KeyExchangeRSA

Description

Key exchange for KE_rsa.

KeyExchange that uses the Rivest Shamir Adelman algorithm.


Inherit KeyExchange

inherit KeyExchange : KeyExchange


Method got_client_key_exchange

string(8bit)|int(8bit) got_client_key_exchange(Stdio.Buffer input, ProtocolVersion version)

Returns

Premaster secret or alert number.

Class SSL.Cipher.KeyExchangeRSAPSK

Description

Key exchange for KE_rsa_psk.


Inherit KeyExchangePSK

inherit KeyExchangePSK : KeyExchangePSK

Class SSL.Cipher.MACAlgorithm

Description

Message Authentication Code interface.


Constant hash_header_size

constant int SSL.Cipher.MACAlgorithm.hash_header_size

Description

The length of the header prefixed by hash().


Method block_size

int block_size()

Description

The block size of the underlying hash algorithm.


Method hash

string hash(string data)

Description

Creates a HMAC hash of the data with the underlying hash algorithm.


Method hash_packet

string hash_packet(object packet, int|void adjust_len)

Description

Generates a header and creates a HMAC hash for the given packet.

Parameter packet

Packet to generate a MAC hash for.

Parameter adjust_len

Added to sizeof(packet) to get the packet length.

Returns

Returns the MAC hash for the packet.


Method hash_raw

string hash_raw(string data)

Description

Creates a normal hash of the data using the underlying hash algorithm.

Class SSL.Cipher.MAChmac_md5

Description

HMAC using MD5.

This is the MAC algorithm used by TLS 1.0 and later.


Inherit MAChmac_sha

inherit MAChmac_sha : MAChmac_sha

Class SSL.Cipher.MAChmac_sha

Description

HMAC using SHA.

This is the MAC algorithm used by TLS 1.0 and later.


Inherit MACAlgorithm

inherit MACAlgorithm : MACAlgorithm


Method create

SSL.Cipher.MAChmac_sha SSL.Cipher.MAChmac_sha(string|void s)

Class SSL.Cipher.MAChmac_sha256

Description

HMAC using SHA256.

This is the MAC algorithm used by some cipher suites in TLS 1.2 and later.


Inherit MAChmac_sha

inherit MAChmac_sha : MAChmac_sha

Class SSL.Cipher.MAChmac_sha384

Description

HMAC using SHA384.

This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.


Inherit MAChmac_sha

inherit MAChmac_sha : MAChmac_sha

Class SSL.Cipher.MAChmac_sha512

Description

HMAC using SHA512.

This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.


Inherit MAChmac_sha

inherit MAChmac_sha : MAChmac_sha

Class SSL.Cipher.MACmd5

Description

MAC using MD5.

Note

Note: This uses the algorithm from the SSL 3.0 draft.


Inherit MACsha

inherit MACsha : MACsha

Class SSL.Cipher.MACsha

Description

MAC using SHA.

Note

Note: This uses the algorithm from the SSL 3.0 draft.


Inherit MACAlgorithm

inherit MACAlgorithm : MACAlgorithm

Class SSL.Cipher.RC2


Inherit State

inherit Crypto.Arctwo.CBC.Buffer.State : State

Module SSL.Constants

Description

Protocol constants


Constant AUTHLEVEL_ask

constant int SSL.Constants.AUTHLEVEL_ask

Description

As a server, request a certificate, but don't require a response. This AUTHLEVEL is not relevant for clients.


Constant AUTHLEVEL_none

constant int SSL.Constants.AUTHLEVEL_none

Description

Don't request nor check any certificate.


Constant AUTHLEVEL_require

constant int SSL.Constants.AUTHLEVEL_require

Description

Require other party to send a valid certificate.


Constant AUTHLEVEL_verify

constant int SSL.Constants.AUTHLEVEL_verify

Description

Don't request, but verify any certificate.


Constant CIPHER_SUITES

constant SSL.Constants.CIPHER_SUITES

Description

A mapping from cipher suite identifier to an array defining the algorithms to be used in that suite.

Array
KeyExchangeType 0

The key exchange algorithm to be used for this suite, or 0. E.g. KE_rsa.

int 1

The cipher algorithm to be used for this suite, or 0. E.g. CIPHER_aes.

HashAlgorithm 2

The hash algorithm to be used for this suite, or 0. E.g. HASH_sha1.

CipherModes 3

Optionally for TLS 1.2 and later cipher suites the mode of operation. E.g. MODE_cbc.


Constant CIPHER_effective_keylengths

constant SSL.Constants.CIPHER_effective_keylengths

Description

Mapping from cipher algorithm to effective key length.


Constant ECC_NAME_TO_CURVE

constant SSL.Constants.ECC_NAME_TO_CURVE

Description

Lookup for Pike ECC name to NamedGroup.


Constant HASH_lookup

constant SSL.Constants.HASH_lookup

Description

Lookup from HashAlgorithm to corresponding Crypto.Hash.


Constant KE_Anonymous

constant SSL.Constants.KE_Anonymous

Description

Lists KeyExchangeType that doesn't require certificates.


Constant PROTOCOL_TLS_MAX

constant SSL.Constants.PROTOCOL_TLS_MAX

Description

Max supported TLS version.


Method fmt_cipher_suite

string fmt_cipher_suite(int suite)

Description

Return a descriptive name for a cipher suite.

Parameter suite

Cipher suite to format.


Method fmt_cipher_suites

string fmt_cipher_suites(array(int) s)

Description

Pretty-print an array of cipher suites.

Parameter s

Array of cipher suites to format.


Method fmt_constant

string fmt_constant(int c, string prefix)

Description

Return a descriptive name for a constant value.

Parameter c

Value to format.

Parameter prefix

Constant name prefix. Eg "CONNECTION".


Method fmt_signature_pairs

string fmt_signature_pairs(array(int) pairs)

Description

Pretty-print an array of SignatureSchemes.

Parameter pairs

Array of signature pairs to format.


Method fmt_version

string fmt_version(ProtocolVersion version)

Description

Pretty-print a ProtocolVersion.

Parameter version

ProtocolVersion to format.

Enum SSL.Constants.ALPNProtocol

Description

Application Level Protocol Negotiation protocol identifiers.

See also

EXTENSION_application_layer_protocol_negotiation


Constant ALPN_http_1_1
Constant ALPN_spdy_1
Constant ALPN_spdy_2
Constant ALPN_spdy_3
Constant ALPN_turn
Constant ALPN_stun
Constant ALPN_http_2
Constant ALPN_http_2_reserved

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

Enum SSL.Constants.AuthzDataFormat


Constant ADF_x509_attr_cert
Constant ADF_saml_assertion
Constant ADF_x509_attr_cert_url
Constant ADF_saml_assertion_url

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

Enum SSL.Constants.CertificateType

Description

Certificate format types as per RFC 6091 and RFC 7250.


Constant CERTTYPE_x509
Constant CERTTYPE_openpgp
Constant CERTTYPE_raw_public_key

constant SSL.Constants.CERTTYPE_x509
constant SSL.Constants.CERTTYPE_openpgp
constant SSL.Constants.CERTTYPE_raw_public_key

Enum SSL.Constants.CipherModes

Description

Cipher operation modes.


Constant MODE_cbc

constant SSL.Constants.MODE_cbc

Description

CBC - Cipher Block Chaining mode.


Constant MODE_ccm

constant SSL.Constants.MODE_ccm

Description

CCM - Counter with CBC-MAC mode.


Constant MODE_ccm_8

constant SSL.Constants.MODE_ccm_8

Description

CCM - Counter with 8 bit CBC-MAC mode.


Constant MODE_gcm

constant SSL.Constants.MODE_gcm

Description

GCM - Galois Cipher Mode.


Constant MODE_poly1305

constant SSL.Constants.MODE_poly1305

Description

Poly1305 - Used only with ChaCha20.

Enum SSL.Constants.CipherSuite


Constant SSL_invalid_suite
Constant SSL_null_with_null_null
Constant SSL_rsa_with_null_md5
Constant SSL_rsa_with_null_sha
Constant SSL_rsa_export_with_rc4_40_md5
Constant SSL_rsa_with_rc4_128_md5
Constant SSL_rsa_with_rc4_128_sha
Constant SSL_rsa_export_with_rc2_cbc_40_md5
Constant SSL_rsa_with_idea_cbc_sha
Constant TLS_rsa_with_idea_cbc_sha
Constant SSL_rsa_export_with_des40_cbc_sha
Constant SSL_rsa_with_des_cbc_sha
Constant TLS_rsa_with_des_cbc_sha
Constant SSL_rsa_with_3des_ede_cbc_sha
Constant SSL_dh_dss_export_with_des40_cbc_sha
Constant SSL_dh_dss_with_des_cbc_sha
Constant TLS_dh_dss_with_des_cbc_sha
Constant SSL_dh_dss_with_3des_ede_cbc_sha
Constant SSL_dh_rsa_export_with_des40_cbc_sha
Constant SSL_dh_rsa_with_des_cbc_sha
Constant TLS_dh_rsa_with_des_cbc_sha
Constant SSL_dh_rsa_with_3des_ede_cbc_sha
Constant SSL_dhe_dss_export_with_des40_cbc_sha
Constant SSL_dhe_dss_with_des_cbc_sha
Constant TLS_dhe_dss_with_des_cbc_sha
Constant SSL_dhe_dss_with_3des_ede_cbc_sha
Constant SSL_dhe_rsa_export_with_des40_cbc_sha
Constant SSL_dhe_rsa_with_des_cbc_sha
Constant TLS_dhe_rsa_with_des_cbc_sha
Constant SSL_dhe_rsa_with_3des_ede_cbc_sha
Constant SSL_dh_anon_export_with_rc4_40_md5
Constant SSL_dh_anon_with_rc4_128_md5
Constant SSL_dh_anon_export_with_des40_cbc_sha
Constant SSL_dh_anon_with_des_cbc_sha
Constant TLS_dh_anon_with_des_cbc_sha
Constant SSL_dh_anon_with_3des_ede_cbc_sha

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_rsa_fips_with_des_cbc_sha
Constant SSL_rsa_fips_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_rsa_oldfips_with_des_cbc_sha
Constant SSL_rsa_oldfips_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_rsa_with_rc2_cbc_md5
Constant SSL_rsa_with_idea_cbc_md5
Constant SSL_rsa_with_des_cbc_md5
Constant SSL_rsa_with_3des_ede_cbc_md5

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 TLS_aes_128_gcm_sha256
Constant TLS_aes_256_gcm_sha384
Constant TLS_chacha20_poly1305_sha256
Constant TLS_aes_128_ccm_sha256
Constant TLS_aes_128_ccm_8_sha256

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 TLS_krb5_with_des_cbc_sha
Constant TLS_krb5_with_3des_ede_cbc_sha
Constant TLS_krb5_with_rc4_128_sha
Constant TLS_krb5_with_idea_cbc_sha
Constant TLS_krb5_with_des_cbc_md5
Constant TLS_krb5_with_3des_ede_cbc_md5
Constant TLS_krb5_with_rc4_128_md5
Constant TLS_krb5_with_idea_cbc_md5
Constant TLS_krb5_export_with_des_cbc_40_sha
Constant TLS_krb5_export_with_rc2_cbc_40_sha
Constant TLS_krb5_export_with_rc4_40_sha
Constant TLS_krb5_export_with_des_cbc_40_md5
Constant TLS_krb5_export_with_rc2_cbc_40_md5
Constant TLS_krb5_export_with_rc4_40_md5
Constant TLS_psk_with_null_sha
Constant TLS_dhe_psk_with_null_sha
Constant TLS_rsa_psk_with_null_sha
Constant TLS_rsa_with_aes_128_cbc_sha
Constant TLS_dh_dss_with_aes_128_cbc_sha
Constant TLS_dh_rsa_with_aes_128_cbc_sha
Constant TLS_dhe_dss_with_aes_128_cbc_sha
Constant TLS_dhe_rsa_with_aes_128_cbc_sha
Constant TLS_dh_anon_with_aes_128_cbc_sha
Constant TLS_rsa_with_aes_256_cbc_sha
Constant TLS_dh_dss_with_aes_256_cbc_sha
Constant TLS_dh_rsa_with_aes_256_cbc_sha
Constant TLS_dhe_dss_with_aes_256_cbc_sha
Constant TLS_dhe_rsa_with_aes_256_cbc_sha
Constant TLS_dh_anon_with_aes_256_cbc_sha
Constant TLS_rsa_with_null_sha256
Constant TLS_rsa_with_aes_128_cbc_sha256
Constant TLS_rsa_with_aes_256_cbc_sha256
Constant TLS_dh_dss_with_aes_128_cbc_sha256
Constant TLS_dh_rsa_with_aes_128_cbc_sha256
Constant TLS_dhe_dss_with_aes_128_cbc_sha256
Constant TLS_rsa_with_camellia_128_cbc_sha
Constant TLS_dh_dss_with_camellia_128_cbc_sha
Constant TLS_dh_rsa_with_camellia_128_cbc_sha
Constant TLS_dhe_dss_with_camellia_128_cbc_sha
Constant TLS_dhe_rsa_with_camellia_128_cbc_sha
Constant TLS_dh_anon_with_camellia_128_cbc_sha

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 TLS_dhe_rsa_with_aes_128_cbc_sha256
Constant TLS_dh_dss_with_aes_256_cbc_sha256
Constant TLS_dh_rsa_with_aes_256_cbc_sha256
Constant TLS_dhe_dss_with_aes_256_cbc_sha256
Constant TLS_dhe_rsa_with_aes_256_cbc_sha256
Constant TLS_dh_anon_with_aes_128_cbc_sha256
Constant TLS_dh_anon_with_aes_256_cbc_sha256

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 TLS_rsa_with_camellia_256_cbc_sha
Constant TLS_dh_dss_with_camellia_256_cbc_sha
Constant TLS_dh_rsa_with_camellia_256_cbc_sha
Constant TLS_dhe_dss_with_camellia_256_cbc_sha
Constant TLS_dhe_rsa_with_camellia_256_cbc_sha
Constant TLS_dh_anon_with_camellia_256_cbc_sha
Constant TLS_psk_with_rc4_128_sha
Constant TLS_psk_with_3des_ede_cbc_sha
Constant TLS_psk_with_aes_128_cbc_sha
Constant TLS_psk_with_aes_256_cbc_sha
Constant TLS_dhe_psk_with_rc4_128_sha
Constant TLS_dhe_psk_with_3des_ede_cbc_sha
Constant TLS_dhe_psk_with_aes_128_cbc_sha
Constant TLS_dhe_psk_with_aes_256_cbc_sha
Constant TLS_rsa_psk_with_rc4_128_sha
Constant TLS_rsa_psk_with_3des_ede_cbc_sha
Constant TLS_rsa_psk_with_aes_128_cbc_sha
Constant TLS_rsa_psk_with_aes_256_cbc_sha
Constant TLS_rsa_with_seed_cbc_sha
Constant TLS_dh_dss_with_seed_cbc_sha
Constant TLS_dh_rsa_with_seed_cbc_sha
Constant TLS_dhe_dss_with_seed_cbc_sha
Constant TLS_dhe_rsa_with_seed_cbc_sha
Constant TLS_dh_anon_with_seed_cbc_sha
Constant TLS_rsa_with_aes_128_gcm_sha256
Constant TLS_rsa_with_aes_256_gcm_sha384
Constant TLS_dhe_rsa_with_aes_128_gcm_sha256
Constant TLS_dhe_rsa_with_aes_256_gcm_sha384
Constant TLS_dh_rsa_with_aes_128_gcm_sha256
Constant TLS_dh_rsa_with_aes_256_gcm_sha384
Constant TLS_dhe_dss_with_aes_128_gcm_sha256
Constant TLS_dhe_dss_with_aes_256_gcm_sha384
Constant TLS_dh_dss_with_aes_128_gcm_sha256
Constant TLS_dh_dss_with_aes_256_gcm_sha384
Constant TLS_dh_anon_with_aes_128_gcm_sha256
Constant TLS_dh_anon_with_aes_256_gcm_sha384
Constant TLS_psk_with_aes_128_gcm_sha256
Constant TLS_psk_with_aes_256_gcm_sha384
Constant TLS_dhe_psk_with_aes_128_gcm_sha256
Constant TLS_dhe_psk_with_aes_256_gcm_sha384
Constant TLS_rsa_psk_with_aes_128_gcm_sha256
Constant TLS_rsa_psk_with_aes_256_gcm_sha384
Constant TLS_psk_with_aes_128_cbc_sha256
Constant TLS_psk_with_aes_256_cbc_sha384
Constant TLS_psk_with_null_sha256
Constant TLS_psk_with_null_sha384
Constant TLS_dhe_psk_with_aes_128_cbc_sha256
Constant TLS_dhe_psk_with_aes_256_cbc_sha384
Constant TLS_dhe_psk_with_null_sha256
Constant TLS_dhe_psk_with_null_sha384
Constant TLS_rsa_psk_with_aes_128_cbc_sha256
Constant TLS_rsa_psk_with_aes_256_cbc_sha384
Constant TLS_rsa_psk_with_null_sha256
Constant TLS_rsa_psk_with_null_sha384
Constant TLS_rsa_with_camellia_128_cbc_sha256
Constant TLS_dh_dss_with_camellia_128_cbc_sha256
Constant TLS_dh_rsa_with_camellia_128_cbc_sha256
Constant TLS_dhe_dss_with_camellia_128_cbc_sha256
Constant TLS_dhe_rsa_with_camellia_128_cbc_sha256
Constant TLS_dh_anon_with_camellia_128_cbc_sha256
Constant TLS_rsa_with_camellia_256_cbc_sha256
Constant TLS_dh_dss_with_camellia_256_cbc_sha256
Constant TLS_dh_rsa_with_camellia_256_cbc_sha256
Constant TLS_dhe_dss_with_camellia_256_cbc_sha256
Constant TLS_dhe_rsa_with_camellia_256_cbc_sha256
Constant TLS_dh_anon_with_camellia_256_cbc_sha256
Constant TLS_sm4_gcm_sm3
Constant TLS_sm4_ccm_sm3

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 TLS_ecdh_ecdsa_with_null_sha
Constant TLS_ecdh_ecdsa_with_rc4_128_sha
Constant TLS_ecdh_ecdsa_with_3des_ede_cbc_sha
Constant TLS_ecdh_ecdsa_with_aes_128_cbc_sha
Constant TLS_ecdh_ecdsa_with_aes_256_cbc_sha
Constant TLS_ecdhe_ecdsa_with_null_sha
Constant TLS_ecdhe_ecdsa_with_rc4_128_sha
Constant TLS_ecdhe_ecdsa_with_3des_ede_cbc_sha
Constant TLS_ecdhe_ecdsa_with_aes_128_cbc_sha
Constant TLS_ecdhe_ecdsa_with_aes_256_cbc_sha
Constant TLS_ecdh_rsa_with_null_sha
Constant TLS_ecdh_rsa_with_rc4_128_sha
Constant TLS_ecdh_rsa_with_3des_ede_cbc_sha
Constant TLS_ecdh_rsa_with_aes_128_cbc_sha
Constant TLS_ecdh_rsa_with_aes_256_cbc_sha
Constant TLS_ecdhe_rsa_with_null_sha
Constant TLS_ecdhe_rsa_with_rc4_128_sha
Constant TLS_ecdhe_rsa_with_3des_ede_cbc_sha
Constant TLS_ecdhe_rsa_with_aes_128_cbc_sha
Constant TLS_ecdhe_rsa_with_aes_256_cbc_sha
Constant TLS_ecdh_anon_with_null_sha
Constant TLS_ecdh_anon_with_rc4_128_sha
Constant TLS_ecdh_anon_with_3des_ede_cbc_sha
Constant TLS_ecdh_anon_with_aes_128_cbc_sha
Constant TLS_ecdh_anon_with_aes_256_cbc_sha
Constant TLS_srp_sha_with_3des_ede_cbc_sha
Constant TLS_srp_sha_rsa_with_3des_ede_cbc_sha
Constant TLS_srp_sha_dss_with_3des_ede_cbc_sha
Constant TLS_srp_sha_with_aes_128_cbc_sha
Constant TLS_srp_sha_rsa_with_aes_128_cbc_sha
Constant TLS_srp_sha_dss_with_aes_128_cbc_sha
Constant TLS_srp_sha_with_aes_256_cbc_sha
Constant TLS_srp_sha_rsa_with_aes_256_cbc_sha
Constant TLS_srp_sha_dss_with_aes_256_cbc_sha
Constant TLS_ecdhe_ecdsa_with_aes_128_cbc_sha256
Constant TLS_ecdhe_ecdsa_with_aes_256_cbc_sha384
Constant TLS_ecdh_ecdsa_with_aes_128_cbc_sha256
Constant TLS_ecdh_ecdsa_with_aes_256_cbc_sha384
Constant TLS_ecdhe_rsa_with_aes_128_cbc_sha256
Constant TLS_ecdhe_rsa_with_aes_256_cbc_sha384
Constant TLS_ecdh_rsa_with_aes_128_cbc_sha256
Constant TLS_ecdh_rsa_with_aes_256_cbc_sha384
Constant TLS_ecdhe_ecdsa_with_aes_128_gcm_sha256
Constant TLS_ecdhe_ecdsa_with_aes_256_gcm_sha384
Constant TLS_ecdh_ecdsa_with_aes_128_gcm_sha256
Constant TLS_ecdh_ecdsa_with_aes_256_gcm_sha384
Constant TLS_ecdhe_rsa_with_aes_128_gcm_sha256
Constant TLS_ecdhe_rsa_with_aes_256_gcm_sha384
Constant TLS_ecdh_rsa_with_aes_128_gcm_sha256
Constant TLS_ecdh_rsa_with_aes_256_gcm_sha384
Constant TLS_ecdhe_psk_with_rc4_128_sha
Constant TLS_ecdhe_psk_with_3des_ede_cbc_sha
Constant TLS_ecdhe_psk_with_aes_128_cbc_sha
Constant TLS_ecdhe_psk_with_aes_256_cbc_sha
Constant TLS_ecdhe_psk_with_aes_128_cbc_sha256
Constant TLS_ecdhe_psk_with_aes_256_cbc_sha384
Constant TLS_ecdhe_psk_with_null_sha
Constant TLS_ecdhe_psk_with_null_sha256
Constant TLS_ecdhe_psk_with_null_sha384
Constant TLS_rsa_with_aria_128_cbc_sha256
Constant TLS_rsa_with_aria_256_cbc_sha384
Constant TLS_dh_dss_with_aria_128_cbc_sha256
Constant TLS_dh_dss_with_aria_256_cbc_sha384
Constant TLS_dh_rsa_with_aria_128_cbc_sha256
Constant TLS_dh_rsa_with_aria_256_cbc_sha384
Constant TLS_dhe_dss_with_aria_128_cbc_sha256
Constant TLS_dhe_dss_with_aria_256_cbc_sha384
Constant TLS_dhe_rsa_with_aria_128_cbc_sha256
Constant TLS_dhe_rsa_with_aria_256_cbc_sha384
Constant TLS_dh_anon_with_aria_128_cbc_sha256
Constant TLS_dh_anon_with_aria_256_cbc_sha384
Constant TLS_ecdhe_ecdsa_with_aria_128_cbc_sha256
Constant TLS_ecdhe_ecdsa_with_aria_256_cbc_sha384
Constant TLS_ecdh_ecdsa_with_aria_128_cbc_sha256
Constant TLS_ecdh_ecdsa_with_aria_256_cbc_sha384
Constant TLS_ecdhe_rsa_with_aria_128_cbc_sha256
Constant TLS_ecdhe_rsa_with_aria_256_cbc_sha384
Constant TLS_ecdh_rsa_with_aria_128_cbc_sha256
Constant TLS_ecdh_rsa_with_aria_256_cbc_sha384
Constant TLS_rsa_with_aria_128_gcm_sha256
Constant TLS_rsa_with_aria_256_gcm_sha384
Constant TLS_dhe_rsa_with_aria_128_gcm_sha256
Constant TLS_dhe_rsa_with_aria_256_gcm_sha384
Constant TLS_dh_rsa_with_aria_128_gcm_sha256
Constant TLS_dh_rsa_with_aria_256_gcm_sha384
Constant TLS_dhe_dss_with_aria_128_gcm_sha256
Constant TLS_dhe_dss_with_aria_256_gcm_sha384
Constant TLS_dh_dss_with_aria_128_gcm_sha256
Constant TLS_dh_dss_with_aria_256_gcm_sha384
Constant TLS_dh_anon_with_aria_128_gcm_sha256
Constant TLS_dh_anon_with_aria_256_gcm_sha384
Constant TLS_ecdhe_ecdsa_with_aria_128_gcm_sha256
Constant TLS_ecdhe_ecdsa_with_aria_256_gcm_sha384
Constant TLS_ecdh_ecdsa_with_aria_128_gcm_sha256
Constant TLS_ecdh_ecdsa_with_aria_256_gcm_sha384
Constant TLS_ecdhe_rsa_with_aria_128_gcm_sha256
Constant TLS_ecdhe_rsa_with_aria_256_gcm_sha384
Constant TLS_ecdh_rsa_with_aria_128_gcm_sha256
Constant TLS_ecdh_rsa_with_aria_256_gcm_sha384
Constant TLS_psk_with_aria_128_cbc_sha256
Constant TLS_psk_with_aria_256_cbc_sha384
Constant TLS_dhe_psk_with_aria_128_cbc_sha256
Constant TLS_dhe_psk_with_aria_256_cbc_sha384
Constant TLS_rsa_psk_with_aria_128_cbc_sha256
Constant TLS_rsa_psk_with_aria_256_cbc_sha384
Constant TLS_psk_with_aria_128_gcm_sha256
Constant TLS_psk_with_aria_256_gcm_sha384
Constant TLS_dhe_psk_with_aria_128_gcm_sha256
Constant TLS_dhe_psk_with_aria_256_gcm_sha384
Constant TLS_rsa_psk_with_aria_128_gcm_sha256
Constant TLS_rsa_psk_with_aria_256_gcm_sha384
Constant TLS_ecdhe_psk_with_aria_128_cbc_sha256
Constant TLS_ecdhe_psk_with_aria_256_cbc_sha384
Constant TLS_ecdhe_ecdsa_with_camellia_128_cbc_sha256
Constant TLS_ecdhe_ecdsa_with_camellia_256_cbc_sha384
Constant TLS_ecdh_ecdsa_with_camellia_128_cbc_sha256
Constant TLS_ecdh_ecdsa_with_camellia_256_cbc_sha384
Constant TLS_ecdhe_rsa_with_camellia_128_cbc_sha256
Constant TLS_ecdhe_rsa_with_camellia_256_cbc_sha384
Constant TLS_ecdh_rsa_with_camellia_128_cbc_sha256
Constant TLS_ecdh_rsa_with_camellia_256_cbc_sha384
Constant TLS_rsa_with_camellia_128_gcm_sha256
Constant TLS_rsa_with_camellia_256_gcm_sha384
Constant TLS_dhe_rsa_with_camellia_128_gcm_sha256
Constant TLS_dhe_rsa_with_camellia_256_gcm_sha384
Constant TLS_dh_rsa_with_camellia_128_gcm_sha256
Constant TLS_dh_rsa_with_camellia_256_gcm_sha384
Constant TLS_dhe_dss_with_camellia_128_gcm_sha256
Constant TLS_dhe_dss_with_camellia_256_gcm_sha384
Constant TLS_dh_dss_with_camellia_128_gcm_sha256
Constant TLS_dh_dss_with_camellia_256_gcm_sha384
Constant TLS_dh_anon_with_camellia_128_gcm_sha256
Constant TLS_dh_anon_with_camellia_256_gcm_sha384
Constant TLS_ecdhe_ecdsa_with_camellia_128_gcm_sha256
Constant TLS_ecdhe_ecdsa_with_camellia_256_gcm_sha384
Constant TLS_ecdh_ecdsa_with_camellia_128_gcm_sha256
Constant TLS_ecdh_ecdsa_with_camellia_256_gcm_sha384
Constant TLS_ecdhe_rsa_with_camellia_128_gcm_sha256
Constant TLS_ecdhe_rsa_with_camellia_256_gcm_sha384
Constant TLS_ecdh_rsa_with_camellia_128_gcm_sha256
Constant TLS_ecdh_rsa_with_camellia_256_gcm_sha384
Constant TLS_psk_with_camellia_128_gcm_sha256
Constant TLS_psk_with_camellia_256_gcm_sha384
Constant TLS_dhe_psk_with_camellia_128_gcm_sha256
Constant TLS_dhe_psk_with_camellia_256_gcm_sha384
Constant TLS_rsa_psk_with_camellia_128_gcm_sha256
Constant TLS_rsa_psk_with_camellia_256_gcm_sha384
Constant TLS_psk_with_camellia_128_cbc_sha256
Constant TLS_psk_with_camellia_256_cbc_sha384
Constant TLS_dhe_psk_with_camellia_128_cbc_sha256
Constant TLS_dhe_psk_with_camellia_256_cbc_sha384
Constant TLS_rsa_psk_with_camellia_128_cbc_sha256
Constant TLS_rsa_psk_with_camellia_256_cbc_sha384
Constant TLS_ecdhe_psk_with_camellia_128_cbc_sha256
Constant TLS_ecdhe_psk_with_camellia_256_cbc_sha384
Constant TLS_rsa_with_aes_128_ccm
Constant TLS_rsa_with_aes_256_ccm
Constant TLS_dhe_rsa_with_aes_128_ccm
Constant TLS_dhe_rsa_with_aes_256_ccm
Constant TLS_rsa_with_aes_128_ccm_8
Constant TLS_rsa_with_aes_256_ccm_8
Constant TLS_dhe_rsa_with_aes_128_ccm_8
Constant TLS_dhe_rsa_with_aes_256_ccm_8
Constant TLS_psk_with_aes_128_ccm
Constant TLS_psk_with_aes_256_ccm
Constant TLS_dhe_psk_with_aes_128_ccm
Constant TLS_dhe_psk_with_aes_256_ccm
Constant TLS_psk_with_aes_128_ccm_8
Constant TLS_psk_with_aes_256_ccm_8
Constant TLS_psk_dhe_with_aes_128_ccm_8
Constant TLS_psk_dhe_with_aes_256_ccm_8
Constant TLS_ecdhe_ecdsa_with_aes_128_ccm
Constant TLS_ecdhe_ecdsa_with_aes_256_ccm
Constant TLS_ecdhe_ecdsa_with_aes_128_ccm_8
Constant TLS_ecdhe_ecdsa_with_aes_256_ccm_8
Constant TLS_eccpwd_with_aes_128_gcm_sha256
Constant TLS_eccpwd_with_aes_256_gcm_sha384
Constant TLS_eccpwd_with_aes_128_ccm_sha256
Constant TLS_eccpwd_with_aes_256_ccm_sha384

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 TLS_rsa_export1024_with_rc4_56_md5
Constant TLS_rsa_export1024_with_rc2_cbc_56_md5
Constant TLS_rsa_export1024_with_des_cbc_sha
Constant TLS_dhe_dss_export1024_with_des_cbc_sha
Constant TLS_rsa_export1024_with_rc4_56_sha
Constant TLS_dhe_dss_export1024_with_rc4_56_sha
Constant TLS_dhe_dss_with_rc4_128_sha

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 TLS_ecdhe_rsa_with_chacha20_poly1305_sha256
Constant TLS_ecdhe_ecdsa_with_chacha20_poly1305_sha256
Constant TLS_dhe_rsa_with_chacha20_poly1305_sha256
Constant TLS_psk_with_chacha20_poly1305_sha256
Constant TLS_ecdhe_psk_with_chacha20_poly1305_sha256
Constant TLS_dhe_psk_with_chacha20_poly1305_sha256
Constant TLS_rsa_psk_with_chacha20_poly1305_sha256

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 TLS_ecdhe_rsa_with_oldchacha20_poly1305_sha256
Constant TLS_ecdhe_ecdsa_with_oldchacha20_poly1305_sha256
Constant TLS_dhe_rsa_with_oldchacha20_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 TLS_ecdhe_psk_with_aes_128_gcm_sha256
Constant TLS_ecdhe_psk_with_aes_256_gcm_sha384
Constant TLS_ecdhe_psk_with_aes_128_ccm_8_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 TLS_ecdhe_psk_with_aes_128_ccm_sha256

constant SSL.Constants.TLS_ecdhe_psk_with_aes_128_ccm_sha256


Constant TLS_empty_renegotiation_info_scsv

constant SSL.Constants.TLS_empty_renegotiation_info_scsv


Constant TLS_fallback_scsv

constant SSL.Constants.TLS_fallback_scsv

Enum SSL.Constants.CipherSuite_2_0


Constant SSL2_ck_rc4_128_with_md5
Constant SSL2_ck_rc4_128_export40_with_md5
Constant SSL2_ck_rc2_128_cbc_with_md5
Constant SSL2_ck_rc2_128_cbc_export40_with_md5
Constant SSL2_ck_idea_128_cbc_with_md5
Constant SSL2_ck_des_64_cbc_with_md5
Constant SSL2_ck_des_192_ede3_cbc_with_md5

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

Enum SSL.Constants.CompressionType

Description

Compression methods.


Constant COMPRESSION_deflate

constant SSL.Constants.COMPRESSION_deflate

Description

Deflate compression. RFC 3749


Constant COMPRESSION_lzs

constant SSL.Constants.COMPRESSION_lzs

Description

LZS compression. RFC 3943


Constant COMPRESSION_null

constant SSL.Constants.COMPRESSION_null

Description

No compression.

Enum SSL.Constants.ConnectionState

Description

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 CONNECTION_closed

constant SSL.Constants.CONNECTION_closed

Description

Closed at both ends.


Constant CONNECTION_closing

constant SSL.Constants.CONNECTION_closing

Description

Connection closing mask.


Constant CONNECTION_failing

constant SSL.Constants.CONNECTION_failing

Description

Connection failing mask.


Constant CONNECTION_handshaking

constant SSL.Constants.CONNECTION_handshaking

Description

Handshaking not done.


Constant CONNECTION_local_closed

constant SSL.Constants.CONNECTION_local_closed

Description

Local close packet sent.


Constant CONNECTION_local_closing

constant SSL.Constants.CONNECTION_local_closing

Description

Local close packet pending.


Constant CONNECTION_local_down

constant SSL.Constants.CONNECTION_local_down

Description

Local mask.


Constant CONNECTION_local_failing

constant SSL.Constants.CONNECTION_local_failing

Description

Fatal alert pending.


Constant CONNECTION_local_fatal

constant SSL.Constants.CONNECTION_local_fatal

Description

Fatal alert sent.


Constant CONNECTION_peer_closed

constant SSL.Constants.CONNECTION_peer_closed

Description

Peer has closed the connection.


Constant CONNECTION_peer_down

constant SSL.Constants.CONNECTION_peer_down

Description

Peer mask.


Constant CONNECTION_peer_fatal

constant SSL.Constants.CONNECTION_peer_fatal

Description

Peer has issued a fatal alert.


Constant CONNECTION_ready

constant SSL.Constants.CONNECTION_ready

Description

Connection is ready for use.

Enum SSL.Constants.CurveType

Description

ECC curve types from RFC 4492 section 5.4 (ECCurveType).


Constant CURVETYPE_explicit_char2

constant SSL.Constants.CURVETYPE_explicit_char2

Description

Deprecated RFC 8422 section 5.4


Constant CURVETYPE_explicit_prime

constant SSL.Constants.CURVETYPE_explicit_prime

Description

Deprecated RFC 8422 section 5.4


Constant CURVETYPE_named_curve

constant SSL.Constants.CURVETYPE_named_curve

Description

Curve or group from NamedGroup.

Enum SSL.Constants.ECBasisType


Constant ECBASIS_trinomial
Constant ECBASIS_pentanomial

constant SSL.Constants.ECBASIS_trinomial
constant SSL.Constants.ECBASIS_pentanomial

Enum SSL.Constants.Extension

Description

Client Hello extensions.


Constant EXTENSION_server_name
Constant EXTENSION_max_fragment_length
Constant EXTENSION_client_certificate_url
Constant EXTENSION_trusted_ca_keys
Constant EXTENSION_truncated_hmac
Constant EXTENSION_status_request
Constant EXTENSION_user_mapping
Constant EXTENSION_client_authz
Constant EXTENSION_server_authz
Constant EXTENSION_cert_type
Constant EXTENSION_elliptic_curves
Constant EXTENSION_ec_point_formats
Constant EXTENSION_srp
Constant EXTENSION_signature_algorithms
Constant EXTENSION_use_srtp
Constant EXTENSION_heartbeat
Constant EXTENSION_application_layer_protocol_negotiation
Constant EXTENSION_status_request_v2
Constant EXTENSION_signed_certificate_timestamp
Constant EXTENSION_client_certificate_type
Constant EXTENSION_server_certificate_type
Constant EXTENSION_padding
Constant EXTENSION_encrypt_then_mac
Constant EXTENSION_extended_master_secret
Constant EXTENSION_session_ticket
Constant EXTENSION_key_share
Constant EXTENSION_pre_shared_key
Constant EXTENSION_early_data
Constant EXTENSION_supported_versions
Constant EXTENSION_cookie
Constant EXTENSION_psk_key_exchange_modes
Constant EXTENSION_certificate_authorities
Constant EXTENSION_oid_filters
Constant EXTENSION_post_handshake_auth
Constant EXTENSION_next_protocol_negotiation
Constant EXTENSION_origin_bound_certificates
Constant EXTENSION_encrypted_client_certificates
Constant EXTENSION_channel_id
Constant EXTENSION_channel_id_new
Constant EXTENSION_old_padding
Constant EXTENSION_renegotiation_info
Constant EXTENSION_draft_version

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

Enum SSL.Constants.FragmentLength

Description

Fragment lengths for EXTENSION_max_fragment_length.


Constant FRAGMENT_512
Constant FRAGMENT_1024
Constant FRAGMENT_2048
Constant FRAGMENT_4096

constant SSL.Constants.FRAGMENT_512
constant SSL.Constants.FRAGMENT_1024
constant SSL.Constants.FRAGMENT_2048
constant SSL.Constants.FRAGMENT_4096

Enum SSL.Constants.HashAlgorithm

Description

Hash algorithms as per RFC 5246 section 7.4.1.4.1.


Constant HASH_MASK

constant SSL.Constants.HASH_MASK


Constant HASH_none
Constant HASH_md5
Constant HASH_sha1
Constant HASH_sha224
Constant HASH_sha256
Constant HASH_sha384
Constant HASH_sha512
Constant HASH_intrinsic

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

Enum SSL.Constants.HeartBeatMessageType


Constant HEARTBEAT_MESSAGE_request
Constant HEARTBEAT_MESSAGE_response

constant SSL.Constants.HEARTBEAT_MESSAGE_request
constant SSL.Constants.HEARTBEAT_MESSAGE_response

Enum SSL.Constants.HeartBeatModeType


Constant HEARTBEAT_MODE_disabled
Constant HEARTBEAT_MODE_peer_allowed_to_send
Constant HEARTBEAT_MODE_peer_not_allowed_to_send

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

Enum SSL.Constants.KeyExchangeType

Description

Key exchange methods.


Constant KE_dh_anon

constant SSL.Constants.KE_dh_anon

Description

Diffie-Hellman Anonymous


Constant KE_dh_dss

constant SSL.Constants.KE_dh_dss

Description

Diffie-Hellman cert signed with DSS


Constant KE_dh_rsa

constant SSL.Constants.KE_dh_rsa

Description

Diffie-Hellman cert signed with RSA


Constant KE_dhe_dss

constant SSL.Constants.KE_dhe_dss

Description

Diffie-Hellman Ephemeral DSS


Constant KE_dhe_psk

constant SSL.Constants.KE_dhe_psk

Description

Pre-shared Key with DHE


Constant KE_dhe_rsa

constant SSL.Constants.KE_dhe_rsa

Description

Diffie-Hellman Ephemeral RSA


Constant KE_dms
Constant KE_fortezza

constant SSL.Constants.KE_dms
constant SSL.Constants.KE_fortezza


Constant KE_ecdh_anon

constant SSL.Constants.KE_ecdh_anon

Description

Elliptic Curve DH Anonymous


Constant KE_ecdh_ecdsa

constant SSL.Constants.KE_ecdh_ecdsa

Description

Elliptic Curve DH cert signed with ECDSA


Constant KE_ecdh_rsa

constant SSL.Constants.KE_ecdh_rsa

Description

Elliptic Curve DH cert signed with RSA


Constant KE_ecdhe_ecdsa

constant SSL.Constants.KE_ecdhe_ecdsa

Description

Elliptic Curve DH Ephemeral with ECDSA


Constant KE_ecdhe_psk

constant SSL.Constants.KE_ecdhe_psk

Description

Pre-shared Key with ECDHE


Constant KE_ecdhe_rsa

constant SSL.Constants.KE_ecdhe_rsa

Description

Elliptic Curve DH Ephemeral with RSA


Constant KE_null

constant SSL.Constants.KE_null

Description

None.


Constant KE_psk

constant SSL.Constants.KE_psk

Description

Pre-shared Key


Constant KE_rsa

constant SSL.Constants.KE_rsa

Description

Rivest-Shamir-Adelman


Constant KE_rsa_export

constant SSL.Constants.KE_rsa_export

Description

Rivest-Shamir-Adelman (EXPORT)


Constant KE_rsa_fips

constant SSL.Constants.KE_rsa_fips

Description

Rivest-Shamir-Adelman with FIPS keys.


Constant KE_rsa_psk

constant SSL.Constants.KE_rsa_psk

Description

Pre-shared Key signed with RSA


Constant KE_srp_sha

constant SSL.Constants.KE_srp_sha

Description

Secure Remote Password (SRP)


Constant KE_srp_sha_dss

constant SSL.Constants.KE_srp_sha_dss

Description

SRP signed with DSS


Constant KE_srp_sha_rsa

constant SSL.Constants.KE_srp_sha_rsa

Description

SRP signed with RSA

Enum SSL.Constants.NamedGroup

Description

Groups used for elliptic curves DHE (ECDHE) and finite field DH (FFDHE).

See also

RFC 4492 section 5.1.1 (NamedCurve) / TLS 1.3 7.4.2.5.2. */


Constant GROUP_arbitrary_explicit_char2_curves

constant SSL.Constants.GROUP_arbitrary_explicit_char2_curves

Description

Deprecated RFC 8422 section 5.1.1


Constant GROUP_arbitrary_explicit_prime_curves

constant SSL.Constants.GROUP_arbitrary_explicit_prime_curves

Description

Deprecated RFC 8422 section 5.1.1


Constant GROUP_brainpoolP256r1

constant SSL.Constants.GROUP_brainpoolP256r1

Description

RFC 7027


Constant GROUP_brainpoolP384r1

constant SSL.Constants.GROUP_brainpoolP384r1

Description

RFC 7027


Constant GROUP_brainpoolP512r1

constant SSL.Constants.GROUP_brainpoolP512r1

Description

RFC 7027


Constant GROUP_ffdhe2048

constant SSL.Constants.GROUP_ffdhe2048

Description

RFC 7919


Constant GROUP_ffdhe3072

constant SSL.Constants.GROUP_ffdhe3072

Description

RFC 7919


Constant GROUP_ffdhe4096

constant SSL.Constants.GROUP_ffdhe4096

Description

RFC 7919


Constant GROUP_ffdhe6144

constant SSL.Constants.GROUP_ffdhe6144

Description

RFC 7919


Constant GROUP_ffdhe8192

constant SSL.Constants.GROUP_ffdhe8192

Description

RFC 7919


Constant GROUP_ffdhe_private0

constant SSL.Constants.GROUP_ffdhe_private0

Description

RFC 7919


Constant GROUP_ffdhe_private1

constant SSL.Constants.GROUP_ffdhe_private1

Description

RFC 7919


Constant GROUP_ffdhe_private2

constant SSL.Constants.GROUP_ffdhe_private2

Description

RFC 7919


Constant GROUP_ffdhe_private3

constant SSL.Constants.GROUP_ffdhe_private3

Description

RFC 7919


Constant GROUP_secp160k1

constant SSL.Constants.GROUP_secp160k1

Description

RFC 4492


Constant GROUP_secp160r1

constant SSL.Constants.GROUP_secp160r1

Description

RFC 4492


Constant GROUP_secp160r2

constant SSL.Constants.GROUP_secp160r2

Description

RFC 4492


Constant GROUP_secp192k1

constant SSL.Constants.GROUP_secp192k1

Description

RFC 4492


Constant GROUP_secp192r1

constant SSL.Constants.GROUP_secp192r1

Description

RFC 4492


Constant GROUP_secp224k1

constant SSL.Constants.GROUP_secp224k1

Description

RFC 4492


Constant GROUP_secp224r1

constant SSL.Constants.GROUP_secp224r1

Description

RFC 4492


Constant GROUP_secp256k1

constant SSL.Constants.GROUP_secp256k1

Description

RFC 4492


Constant GROUP_secp256r1

constant SSL.Constants.GROUP_secp256r1

Description

RFC 4492


Constant GROUP_secp384r1

constant SSL.Constants.GROUP_secp384r1

Description

RFC 4492


Constant GROUP_secp521r1

constant SSL.Constants.GROUP_secp521r1

Description

RFC 4492


Constant GROUP_sect163k1

constant SSL.Constants.GROUP_sect163k1

Description

RFC 4492


Constant GROUP_sect163r1

constant SSL.Constants.GROUP_sect163r1

Description

RFC 4492


Constant GROUP_sect163r2

constant SSL.Constants.GROUP_sect163r2

Description

RFC 4492


Constant GROUP_sect193r1

constant SSL.Constants.GROUP_sect193r1

Description

RFC 4492


Constant GROUP_sect193r2

constant SSL.Constants.GROUP_sect193r2

Description

RFC 4492


Constant GROUP_sect233k1

constant SSL.Constants.GROUP_sect233k1

Description

RFC 4492


Constant GROUP_sect233r1

constant SSL.Constants.GROUP_sect233r1

Description

RFC 4492


Constant GROUP_sect239k1

constant SSL.Constants.GROUP_sect239k1

Description

RFC 4492


Constant GROUP_sect283k1

constant SSL.Constants.GROUP_sect283k1

Description

RFC 4492


Constant GROUP_sect283r1

constant SSL.Constants.GROUP_sect283r1

Description

RFC 4492


Constant GROUP_sect409k1

constant SSL.Constants.GROUP_sect409k1

Description

RFC 4492


Constant GROUP_sect409r1

constant SSL.Constants.GROUP_sect409r1

Description

RFC 4492


Constant GROUP_sect571k1

constant SSL.Constants.GROUP_sect571k1

Description

RFC 4492


Constant GROUP_sect571r1

constant SSL.Constants.GROUP_sect571r1

Description

RFC 4492


Constant GROUP_x25519

constant SSL.Constants.GROUP_x25519

Description

RFC 8422


Constant GROUP_x448

constant SSL.Constants.GROUP_x448

Description

RFC 8422

Enum SSL.Constants.PointFormat


Constant POINT_uncompressed
Constant POINT_ansiX962_compressed_prime
Constant POINT_ansiX962_compressed_char2

constant SSL.Constants.POINT_uncompressed
constant SSL.Constants.POINT_ansiX962_compressed_prime
constant SSL.Constants.POINT_ansiX962_compressed_char2

Enum SSL.Constants.ProtocolVersion

Description

Constants for specifying the versions of SSL/TLS to use.

See also

Context


Constant PROTOCOL_DTLS_1_0

constant SSL.Constants.PROTOCOL_DTLS_1_0

Description

DTLS 1.0 - The RFC 4347 version of DTLS. This is essentially TLS 1.1 over UDP.


Constant PROTOCOL_DTLS_1_2

constant SSL.Constants.PROTOCOL_DTLS_1_2

Description

DTLS 1.2 - The RFC 6347 version of DTLS. This is essentially TLS 1.2 over UDP.


Constant PROTOCOL_IN_EXTENSION

constant SSL.Constants.PROTOCOL_IN_EXTENSION

Description

Pike internal marker


Constant PROTOCOL_SSL_3_0

constant SSL.Constants.PROTOCOL_SSL_3_0

Description

SSL 3.0 - The original SSL3 draft version.


Constant PROTOCOL_TLS_1_0

constant SSL.Constants.PROTOCOL_TLS_1_0

Description

TLS 1.0 - The RFC 2246 version of TLS.


Constant PROTOCOL_TLS_1_1

constant SSL.Constants.PROTOCOL_TLS_1_1

Description

TLS 1.1 - The RFC 4346 version of TLS.


Constant PROTOCOL_TLS_1_2

constant SSL.Constants.PROTOCOL_TLS_1_2

Description

TLS 1.2 - The RFC 5246 version of TLS.


Constant PROTOCOL_TLS_1_3

constant SSL.Constants.PROTOCOL_TLS_1_3

Description

TLS 1.3 - The RFC 8446 version of TLS.

Enum SSL.Constants.SignatureAlgorithm

Description

Signature algorithms from TLS 1.2.


Constant SIGNATURE_MASK

constant SSL.Constants.SIGNATURE_MASK


Constant SIGNATURE_anonymous

constant SSL.Constants.SIGNATURE_anonymous

Description

No signature.


Constant SIGNATURE_dsa

constant SSL.Constants.SIGNATURE_dsa

Description

DSS signature.


Constant SIGNATURE_ecdsa

constant SSL.Constants.SIGNATURE_ecdsa

Description

ECDSA signature.


Constant SIGNATURE_ed25519

constant SSL.Constants.SIGNATURE_ed25519

Description

EdDSA 25519 signature.


Constant SIGNATURE_ed448

constant SSL.Constants.SIGNATURE_ed448

Description

EdDSA 448 signature.


Constant SIGNATURE_rsa

constant SSL.Constants.SIGNATURE_rsa

Description

RSASSA PKCS1 v1.5 signature.


Constant SIGNATURE_rsa_pss_256

constant SSL.Constants.SIGNATURE_rsa_pss_256

Description

RSA PSS signature with 256 bit hash.


Constant SIGNATURE_rsa_pss_384

constant SSL.Constants.SIGNATURE_rsa_pss_384

Description

RSA PSS signature with 384 bit hash.


Constant SIGNATURE_rsa_pss_512

constant SSL.Constants.SIGNATURE_rsa_pss_512

Description

RSA PSS signature with 512 bit hash.

Enum SSL.Constants.SignatureScheme

Description

Signature algorithms from TLS 1.3


Constant SIGNATURE_ecdsa_secp256r1_sha256
Constant SIGNATURE_ecdsa_secp384r1_sha384
Constant SIGNATURE_ecdsa_secp521r1_sha512

constant SSL.Constants.SIGNATURE_ecdsa_secp256r1_sha256
constant SSL.Constants.SIGNATURE_ecdsa_secp384r1_sha384
constant SSL.Constants.SIGNATURE_ecdsa_secp521r1_sha512


Constant SIGNATURE_rsa_pkcs1_sha1
Constant SIGNATURE_ecdsa_sha1

constant SSL.Constants.SIGNATURE_rsa_pkcs1_sha1
constant SSL.Constants.SIGNATURE_ecdsa_sha1


Constant SIGNATURE_ed25519_intrinsic
Constant SIGNATURE_ed448_intrinsic

constant SSL.Constants.SIGNATURE_ed25519_intrinsic
constant SSL.Constants.SIGNATURE_ed448_intrinsic


Constant SIGNATURE_rsa_pkcs1_sha256
Constant SIGNATURE_rsa_pkcs1_sha384
Constant SIGNATURE_rsa_pkcs1_sha512

constant SSL.Constants.SIGNATURE_rsa_pkcs1_sha256
constant SSL.Constants.SIGNATURE_rsa_pkcs1_sha384
constant SSL.Constants.SIGNATURE_rsa_pkcs1_sha512


Constant SIGNATURE_rsa_pss_sha256
Constant SIGNATURE_rsa_pss_sha384
Constant SIGNATURE_rsa_pss_sha512

constant SSL.Constants.SIGNATURE_rsa_pss_sha256
constant SSL.Constants.SIGNATURE_rsa_pss_sha384
constant SSL.Constants.SIGNATURE_rsa_pss_sha512

Enum SSL.Constants.SupplementalDataType

Description

Values used for supp_data_type in SupplementalDataEntry (cf RFC 4681 section 3).


Constant SDT_user_mapping_data

constant SSL.Constants.SDT_user_mapping_data

Enum SSL.Constants.UserMappingType

Description

RFC 4681 section 6.


Constant UMT_upn_domain_hint

constant SSL.Constants.UMT_upn_domain_hint

Class SSL.Constants.CertificatePair

Description

A chain of X509 certificates with corresponding private key.

It also contains some derived metadata.


Variable cert_type

int SSL.Constants.CertificatePair.cert_type

Description

Cerificate type for the leaf cert.

One of the AUTH_* constants.


Variable certs

array(string(8bit)) SSL.Constants.CertificatePair.certs

Description

Chain of certificates, root cert last.


Variable globs

array(string(8bit)) SSL.Constants.CertificatePair.globs

Description

Array of commonName globs from the first certificate in certs.


Variable issuers

array(string(8bit)) SSL.Constants.CertificatePair.issuers

Description

Array of DER for the issuers matching certs.


Variable ke_mask

int(0..) SSL.Constants.CertificatePair.ke_mask

Description

Bitmask of the key exchange algorithms supported by the main certificate. This is used for TLS 1.1 and earlier.

See also

ke_mask_invariant


Variable ke_mask_invariant

int(0..) SSL.Constants.CertificatePair.ke_mask_invariant

Description

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.


Variable key

Crypto.Sign.State SSL.Constants.CertificatePair.key

Description

Private key.


Variable sign_algs

array(SignatureScheme) SSL.Constants.CertificatePair.sign_algs

Description

TLS 1.2-style hash and signature pairs matching the certs.


Method create

SSL.Constants.CertificatePair SSL.Constants.CertificatePair(Crypto.Sign.State key, array(string(8bit)) certs, array(string(8bit))|void extra_name_globs)

Description

Initializa a new CertificatePair.

Parameter key

Private key.

Parameter certs

Chain of certificates, root cert last.

Parameter extra_globs

The set of globs from the first certificate is optionally extended with these.

Note

Performs various validation checks.

13.3. DNS

Module Protocols.DNS

Description

Support for the Domain Name System protocol.

Implements RFC 1034, RFC 1035 and RFC 2308.


Constant FORMERR

final constant int Protocols.DNS.FORMERR

Description

The name server was unable to interpret the request due to a format error.


Constant NOERROR

final constant int Protocols.DNS.NOERROR

Description

No error condition.


Constant NOTAUTH

final constant int Protocols.DNS.NOTAUTH

Description

Server not authoritative for zone.


Constant NOTIMP
Constant NOTIMPL

final constant int Protocols.DNS.NOTIMP
final constant int Protocols.DNS.NOTIMPL

Description

The name server does not support the specified Opcode.


Constant NOTZONE

final constant int Protocols.DNS.NOTZONE

Description

Name not contained in zone.


Constant NXDOMAIN

final constant int Protocols.DNS.NXDOMAIN

Description

Some name that ought to exist, does not exist.


Constant NXRRSET

final constant int Protocols.DNS.NXRRSET

Description

Some RRset that ought to exist, does not exist.


Constant REFUSED

final constant int Protocols.DNS.REFUSED

Description

The name server refuses to perform the specified operation for policy or security reasons.


Constant SERVFAIL

final constant int Protocols.DNS.SERVFAIL

Description

The name server encountered an internal failure while processing this request, for example an operating system error or a forwarding timeout.


Constant YXDOMAIN

final constant int Protocols.DNS.YXDOMAIN

Description

Name that should not exist, does exist.


Constant YXRRSET

final constant int Protocols.DNS.YXRRSET

Description

RRset that should not exist, does exist.


Method async_get_mx

client.Request async_get_mx(string host, function(:void) cb, mixed ... cba)
Concurrent.Future async_get_mx(string host)

Description

Calls get_mx in a global async_client created on demand.

See also

async_client.get_mx()


Method async_get_mx_all

client.Request async_get_mx_all(string host, function(:void) cb, mixed ... cba)
Concurrent.Future async_get_mx_all(string host)

Description

Calls get_mx_all in a global async_client created on demand.

See also

async_client.get_mx_all()


Method async_host_to_ip

client.Request async_host_to_ip(string host, function(:void) cb, mixed ... cba)
Concurrent.Future async_host_to_ip(string host)

Description

Calls host_to_ip in a global async_client created on demand.

See also

async_client.host_to_ip()


Method async_host_to_ips

client.Request async_host_to_ips(string host, function(:void) cb, mixed ... cba)
Concurrent.Future async_host_to_ips(string host)

Description

Calls host_to_ips in a global async_client created on demand.

See also

async_client.host_to_ips()


Method async_ip_to_host

client.Request async_ip_to_host(string ip, function(:void) cb, mixed ... cba)
Concurrent.Future async_ip_to_host(string ip)

Description

Calls ip_to_host in a global async_client created on demand.

See also

async_client.ip_to_host()


Method get_mx

string get_mx(string host)


Method get_primary_mx

string get_primary_mx(string host)


Method gethostbyaddr

array gethostbyaddr(string host)


Method gethostbyname

array gethostbyname(string host)

Enum Protocols.DNS.DNSKEY_Flags

Description

Flag bits used in T_DNSKEY RRs.


Constant F_SECUREENTRYPOINT

constant Protocols.DNS.F_SECUREENTRYPOINT

Description

Secure Entry Point.


Constant F_ZONEKEY

constant Protocols.DNS.F_ZONEKEY

Description

Zone Key.

Enum Protocols.DNS.DNSSEC_Digests

Description

DNSSEC Digest types.


Constant DNSSEC_SHA1

constant Protocols.DNS.DNSSEC_SHA1

Description

SHA1 digest RFC 4035 appendix A.2.

Enum Protocols.DNS.DNSSEC_Protocol

Description

DNSSEC Protocol types.

Note

RFC 4034 obsoleted all but DNSSEC_DNSSEC.


Constant DNSSEC_ALL

constant Protocols.DNS.DNSSEC_ALL

Description

Any use. Discouraged.


Constant DNSSEC_DNSSEC

constant Protocols.DNS.DNSSEC_DNSSEC

Description

Key for use by DNSSEC. RFC 4034 section 2.1.2.


Constant DNSSEC_EMAIL

constant Protocols.DNS.DNSSEC_EMAIL

Description

Reserved for use by SMTP et al.


Constant DNSSEC_IPSEC

constant Protocols.DNS.DNSSEC_IPSEC

Description

Reserved for use by IPSEC.


Constant DNSSEC_TLS

constant Protocols.DNS.DNSSEC_TLS

Description

Reserved for use by TLS.

Enum Protocols.DNS.DNSSES_Algorithm

Description

DNSSEC Algorithm types.


Constant DNSSEC_DH

constant Protocols.DNS.DNSSEC_DH

Description

Diffie-Hellman RFC 2539.


Constant DNSSEC_DSA

constant Protocols.DNS.DNSSEC_DSA

Description

DSA/SHA1 RFC 2536.


Constant DNSSEC_ECC
Constant DNSSEC_RSASHA1

constant Protocols.DNS.DNSSEC_ECC
constant Protocols.DNS.DNSSEC_RSASHA1

Description

RSA/SHA1 RFC 3110.


Constant DNSSEC_INDIRECT
Constant DNSSEC_PRIVATEDNS

constant Protocols.DNS.DNSSEC_INDIRECT
constant Protocols.DNS.DNSSEC_PRIVATEDNS

Description

Private algorithm DNS-based RFC 4035 appendix A.1.1.


Constant DNSSEC_PRIVATEOID

constant Protocols.DNS.DNSSEC_PRIVATEOID

Description

Private algorithm OID-based RFC 4035 appendix A.1.1.


Constant DNSSEC_RSAMD5

constant Protocols.DNS.DNSSEC_RSAMD5

Description

RSA/MD5 RFC 2537.

Enum Protocols.DNS.EntryType

Description

Entry types


Constant T_A

constant Protocols.DNS.T_A

Description

Type - host address


Constant T_A6

constant Protocols.DNS.T_A6

Description

Type - IPv6 address record (RFC 2874 and Obsolete RFC 6563)


Constant T_AAAA

constant Protocols.DNS.T_AAAA

Description

Type - IPv6 address record (RFC 1886)


Constant T_AFSDB

constant Protocols.DNS.T_AFSDB

Description

Type - AFC database record (RFC 1183)


Constant T_ANY

constant Protocols.DNS.T_ANY

Description

Type - ANY - A request for all records


Constant T_APL

constant Protocols.DNS.T_APL

Description

Type - Address Prefix List (RFC 3123)


Constant T_ATMA

constant Protocols.DNS.T_ATMA

Description

Type - ATM End System Address (af-saa-0069.000)


Constant T_AXFR

constant Protocols.DNS.T_AXFR

Description

Type - Authoritative Zone Transfer (RFC 1035)


Constant T_CAA

constant Protocols.DNS.T_CAA

Description

Type - Certificate Authority Authorization (RFC 6844)


Constant T_CERT

constant Protocols.DNS.T_CERT

Description

Type - Certificate Record (RFC 4398)


Constant T_CNAME

constant Protocols.DNS.T_CNAME

Description

Type - canonical name for an alias


Constant T_DHCID

constant Protocols.DNS.T_DHCID

Description

Type - DHCP identifier (RFC 4701)


Constant T_DLV

constant Protocols.DNS.T_DLV

Description

Type - DNSSEC Lookaside Validation Record (RFC 4431)


Constant T_DNAME

constant Protocols.DNS.T_DNAME

Description

Type - Delegation Name (RFC 2672)


Constant T_DNSKEY

constant Protocols.DNS.T_DNSKEY

Description

Type - DNS Key record (RFC 4034)


Constant T_DS

constant Protocols.DNS.T_DS

Description

Type - Delegation Signer (RFC 4034)


Constant T_EID

constant Protocols.DNS.T_EID

Description

Type - Nimrod Endpoint IDentifier (draft)


Constant T_UINFO
Constant T_UID
Constant T_GID
Constant T_UNSPEC

constant Protocols.DNS.T_UINFO
constant Protocols.DNS.T_UID
constant Protocols.DNS.T_GID
constant Protocols.DNS.T_UNSPEC


Constant T_GPOS

constant Protocols.DNS.T_GPOS

Description

Type - Global Position (RFC 1712 Obsolete use LOC).


Constant T_HINFO

constant Protocols.DNS.T_HINFO

Description

Type - host information


Constant T_HIP

constant Protocols.DNS.T_HIP

Description

Type - Host Identity Protocol (RFC 5205)


Constant T_IPSECKEY

constant Protocols.DNS.T_IPSECKEY

Description

Type - IPsec Key (RFC 4025)


Constant T_ISDN

constant Protocols.DNS.T_ISDN

Description

Type - ISDN address (RFC 1183)


Constant T_IXFR

constant Protocols.DNS.T_IXFR

Description

Type - Incremental Zone Transfer (RFC 1996)


Constant T_KEY

constant Protocols.DNS.T_KEY

Description

Type - Key record (RFC 2535 and RFC 2930)


Constant T_KX

constant Protocols.DNS.T_KX

Description

Type - Key eXchanger record (RFC 2230)


Constant T_LOC

constant Protocols.DNS.T_LOC

Description

Type - Location Record (RFC 1876)


Constant T_MAILA

constant Protocols.DNS.T_MAILA

Description

Type - Mail Agent (both MD and MF) (Obsolete - use MX)


Constant T_MAILB

constant Protocols.DNS.T_MAILB

Description

Type - Mail Box (MB, MG or MR) (Obsolete - use MX)


Constant T_MB

constant Protocols.DNS.T_MB

Description

Type - mailbox domain name (Obsolete)


Constant T_MD

constant Protocols.DNS.T_MD

Description

Type - mail destination (Obsolete - use MX)


Constant T_MF

constant Protocols.DNS.T_MF

Description

Type - mail forwarder (Obsolete - use MX)


Constant T_MG

constant Protocols.DNS.T_MG

Description

Type - mail group member (Obsolete)


Constant T_MINFO

constant Protocols.DNS.T_MINFO

Description

Type - mailbox or mail list information (Obsolete)


Constant T_MR

constant Protocols.DNS.T_MR

Description

Type - mail rename domain name (Obsolete)


Constant T_MX

constant Protocols.DNS.T_MX

Description

Type - mail exchange


Constant T_NAPTR

constant Protocols.DNS.T_NAPTR

Description

Type - NAPTR (RFC 3403)


Constant T_NIMLOC

constant Protocols.DNS.T_NIMLOC

Description

Type - Nimrod Locator (draft)


Constant T_NS

constant Protocols.DNS.T_NS

Description

Type - authoritative name server


Constant T_NSAP

constant Protocols.DNS.T_NSAP

Description

Type - OSI Network Service Access Protocol (RFC 1348, RFC 1637 and RFC 1706)


Constant T_NSAP_PTR

constant Protocols.DNS.T_NSAP_PTR

Description

Type - OSI NSAP Pointer (RFC 1348 and Obsolete RFC 1637)


Constant T_NSEC

constant Protocols.DNS.T_NSEC

Description

Type - Next-Secure record (RFC 4034)


Constant T_NSEC3

constant Protocols.DNS.T_NSEC3

Description

Type - NSEC record version 3 (RFC 5155)


Constant T_NSEC3PARAM

constant Protocols.DNS.T_NSEC3PARAM

Description

Type - NSEC3 parameters (RFC 5155)


Constant T_NULL

constant Protocols.DNS.T_NULL

Description

Type - null RR (Obsolete RFC 1035)


Constant T_NXT

constant Protocols.DNS.T_NXT

Description

Type - Next (RFC 2065 and Obsolete RFC 3755)


Constant T_OPT

constant Protocols.DNS.T_OPT

Description

Type - Option (RFC 2671)


Constant T_PTR

constant Protocols.DNS.T_PTR

Description

Type - domain name pointer


Constant T_PX

constant Protocols.DNS.T_PX

Description

Type - Pointer to X.400 mapping information (RFC 1664)


Constant T_RP

constant Protocols.DNS.T_RP

Description

Type - Responsible Person


Constant T_RRSIG

constant Protocols.DNS.T_RRSIG

Description

Type - DNSSEC signature (RFC 4034)


Constant T_RT

constant Protocols.DNS.T_RT

Description

Type - Route Through (RFC 1183)


Constant T_SIG

constant Protocols.DNS.T_SIG

Description

Type - Signature (RFC 2535)


Constant T_SINK

constant Protocols.DNS.T_SINK

Description

Type - Kitchen Sink (draft)


Constant T_SOA

constant Protocols.DNS.T_SOA

Description

Type - start of a zone of authority


Constant T_SPF

constant Protocols.DNS.T_SPF

Description

Type - SPF - Sender Policy Framework (RFC 4408)


Constant T_SRV

constant Protocols.DNS.T_SRV

Description

Type - Service location record (RFC 2782)


Constant T_SSHFP

constant Protocols.DNS.T_SSHFP

Description

Type - SSH Public Key Fingerprint (RFC 4255)


Constant T_TA

constant Protocols.DNS.T_TA

Description

Type - DNSSEC Trust Authorities (draft)


Constant T_TKEY

constant Protocols.DNS.T_TKEY

Description

Type - Secret key record (RFC 2930)


Constant T_TLSA

constant Protocols.DNS.T_TLSA

Description

Type - TLSA certificate association (RFC 6698)


Constant T_TSIG

constant Protocols.DNS.T_TSIG

Description

Type - Transaction Signature (RFC 2845)


Constant T_TXT

constant Protocols.DNS.T_TXT

Description

Type - text strings


Constant T_WKS

constant Protocols.DNS.T_WKS

Description

Type - well known service description (Obsolete RFC 1123 and RFC 1127)


Constant T_X25

constant Protocols.DNS.T_X25

Description

Type - X25 PSDN address (RFC 1183)

Enum Protocols.DNS.ResourceClass

Description

Resource classes


Constant C_ANY

constant Protocols.DNS.C_ANY

Description

Class ANY


Constant C_CH

constant Protocols.DNS.C_CH

Description

Class CHAOS


Constant C_CS

constant Protocols.DNS.C_CS

Description

Class CSNET (Obsolete)


Constant C_HS

constant Protocols.DNS.C_HS

Description

Class Hesiod


Constant C_IN

constant Protocols.DNS.C_IN

Description

Class Internet

Class Protocols.DNS.async_client

Description

Asynchronous DNS client.


Inherit client

inherit client : client


Inherit udp

inherit Stdio.UDP : udp


Method close

void close()

Description

Close the client.

Note

All active requests are aborted.


Method create

Protocols.DNS.async_client Protocols.DNS.async_client(void|string|array(string) server, void|string|array(string) domain)


Method do_query

Request do_query(string domain, int cl, int type, function(string, mapping, __unknown__ ... :void) callback, mixed ... args)

Description

Enqueue a new raw DNS request.

Returns

Returns a Request object.

Note

Pike versions prior to 8.0 did not return the Request object.


Method generic_query

void generic_query(string type, string domain, function(array(string)|zero, __unknown__ ... :void) callback, mixed ... restargs)

Description

Asynchronous DNS query with multiple results and a distinction between failure and empty results.

Parameter type

DNS query type. Currenlty supported:

"A"

Return just IPv4 records.

"AAAA"

Return both IPv6 and IPv4 records.

"PTR"

Reverse lookup for IP addresses, it expects normal IP addresses for domain.

"TXT"

Return TXT records.

"MX"

Return MX records sorted by preference, lowest numbers first.

"MXIP"

Like querying for MX, except it returns IP addresses instead of the MX records themselves.

Parameter domain

The domain name we are querying. Add a trailing dot to prohibit domain-postfix searching.

Parameter 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.

Parameter restargs

They are passed unaltered to the callback function.

Note

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).

Note

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)).

Note

All queries sort automatically by preference (lowest numbers first).


Method get_mx

Request get_mx(string host, function(array(string), __unknown__ ... :void) callback, mixed ... args)

Description

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

Returns a Request object where progress can be observed from the retries variable and the request can be cancelled using the cancel method.


Method get_mx

variant Concurrent.Future get_mx(string host)

Description

Looks up the mx pointers for a host. Returns a Concurrent.Future object that resolves into an array of strings.


Method get_mx_all

Request get_mx_all(string host, function(string, array(mapping(string:string|int)), __unknown__ ... :void) callback, mixed ... args)

Description

Looks up the mx pointers for a host, and when done calls the function callback with the results as an array of mappings.

Returns

Returns a Request object where progress can be observed from the retries variable and the request can be cancelled using the cancel method.


Method get_mx_all

variant Concurrent.Future get_mx_all(string host)

Description

Looks up the mx pointers for a host. Returns a Concurrent.Future object that resolves into an array of mappings.


Method host_to_ip

Request host_to_ip(string host, function(string, string, __unknown__ ... :void) callback, mixed ... args)

Description

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

Returns a Request object where progress can be observed from the retries variable and the request can be cancelled using the cancel method.

See also

host_to_ips


Method host_to_ip

variant Concurrent.Future host_to_ip(string host)

Description

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.

See also

host_to_ips


Method host_to_ips

Request host_to_ips(string host, function(string, array, __unknown__ ... :void) callback, mixed ... args)

Description

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

Returns a Request object where progress can be observed from the retries variable and the request can be cancelled using the cancel method.


Method host_to_ips

variant Concurrent.Future host_to_ips(string host)

Description

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.


Method ip_to_host

Request ip_to_host(string ip, function(string, string, __unknown__ ... :void) callback, mixed ... args)

Description

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

Returns a Request object where progress can be observed from the retries variable and the request can be cancelled using the cancel method.


Method ip_to_host

variant Concurrent.Future ip_to_host(string ip)

Description

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.


Method low_generic_query

private void low_generic_query(int restrictsearch, string type, string domain, function(array(string)|zero, __unknown__ ... :void) callback, mixed ... restargs)

Parameter restrictsearch
0

Try /etc/hosts first, then try all configured domain-postfixes when querying the DNS servers (default).

1

Try /etc/hosts first, then try an unaltered query on the DNS servers.

2

Just try an unaltered query on the DNS servers.

Class Protocols.DNS.async_dual_client

Description

Both an async_client and an async_tcp_client.


Inherit TCP

inherit async_tcp_client : TCP


Inherit UDP

inherit async_client : UDP


Method do_query

Request do_query(string domain, int cl, int type, function(string, mapping, __unknown__ ... :void) callback, mixed ... args)

Class Protocols.DNS.async_tcp_client

Description

Asynchronous DNS client using TCP


Inherit async_client

inherit async_client : async_client


Method do_query

Request do_query(string domain, int cl, int type, function(string, mapping, __unknown__ ... :void) callback, mixed ... args)

Class Protocols.DNS.async_tcp_client.Request


Inherit this_program

inherit ::this_program : this_program

Class Protocols.DNS.client

Description

Synchronous DNS client.


Inherit protocol

inherit protocol : protocol


Method create

Protocols.DNS.client Protocols.DNS.client()
Protocols.DNS.client Protocols.DNS.client(void|string|array server, void|int|array domain)


Method do_sync_query

mapping|zero do_sync_query(string s)

Description

Perform a synchronous DNS query.

Parameter s

Result of Protocols.DNS.protocol.mkquery

Returns

mapping containing query result or 0 on failure/timeout

Example
// 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));

Method get_mx

array(string)|zero get_mx(string host)


Method get_primary_mx

string get_primary_mx(string hostname)

Description

Queries the primary mx for the host.

Returns

Returns the hostname of the primary mail exchanger.


Method gethostbyaddr

array gethostbyaddr(string hostip)

Description

Queries the host name or ip from the default or given DNS server. The result is an array with three elements,

Returns

The requested data about the specified host.

Array
string hostip

The host IP.

array(string) ip

IP number(s).

array(string) aliases

DNS name(s).


Method gethostbyname

array gethostbyname(string hostname)

Description

Queries the host name from the default or given DNS server. The result is an array with three elements,

Returns

An array with the requested information about the specified host.

Array
string hostname

Hostname.

array(string) ip

IP number(s).

array(string) aliases

DNS name(s).

Note

Prior to Pike 7.7 this function only returned IPv4 addresses.


Method getsrvbyname

array getsrvbyname(string service, string protocol, string|void name)

Description

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:

Returns

An array with the requested information about the specified service.

Array
int priority

Priority

int weight

Weight in event of multiple records with same priority.

int port

port number

string target

target dns name


Method match_etc_hosts

array(string)|zero match_etc_hosts(string host)

Description

Return /etc/hosts records

Class Protocols.DNS.client.Request


Variable domain
Variable req
Variable callback
Variable args

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


Method __create__

protected local void __create__(string domain, string req, function(string, mapping|zero, __unknown__ ... :void)|zero callback, array(mixed) args)


Syntax

void cancel()mixed Protocols.DNS.client.Request.retry_co

Description

Cancel the current request.


Method create

Protocols.DNS.client.Request Protocols.DNS.client.Request(string domain, string req, function(string, mapping|zero, __unknown__ ... :void)|zero callback, array(mixed) args)

Class Protocols.DNS.dual_client

Description

Both a client and a tcp_client.


Inherit TCP

inherit tcp_client : TCP


Inherit UDP

inherit client : UDP


Method do_sync_query

mapping do_sync_query(string s)

Class Protocols.DNS.dual_server

Description

This is both a server and tcp_server.


Inherit TCP

inherit tcp_server : TCP


Inherit UDP

inherit server : UDP

Class Protocols.DNS.protocol

Description

Low level DNS protocol


Method decode_entries

array decode_entries(string s, int num, array(int) next)

Description

Decode a set of entries from an answer.

Parameter s

Encoded entries.

Parameter num

Number of entires in s.

Parameter next

Array with a single element containing the start position in s on entry and the continuation position on return.

Returns

Returns an array of mappings describing the decoded entires:

Array
mapping 0..

Mapping describing a single entry:

"name" : string

Name the entry concerns.

"type" : EntryType

Type of entry.

"cl" : ResourceClass

Resource class. Typically C_IN.

"ttl" : int

Time to live for the entry in seconds.

"len" : int

Length in bytes of the encoded data section.

Depending on the type of entry the mapping may contain different additional fields:

T_CNAME
"cname" : string
T_PTR
"ptr" : string
T_NS
"ns" : string
T_MX
"preference" : int
"mx" : string
T_HINFO
"cpu" : string
"os" : string
T_SRV

RFC 2052 and RFC 2782.

"priority" : int
"weight" : int
"port" : int
"target" : string
"service" : string
"proto" : string
"name" : string
T_A
"a" : string

IPv4-address in dotted-decimal format.

T_AAAA
"aaaa" : string

IPv6-address in colon-separated hexadecimal format.

T_LOC
"version" : int

Version, currently only version 0 (zero) is supported.

"size" : float 
"h_perc" : float 
"v_perc" : float 
"lat" : float 
"long" : float 
"alt" : float 
T_SOA
"mname" : string 
"rname" : string 
"serial" : int 
"refresh" : int 
"retry" : int 
"expire" : int 
"minimum" : int

Note: For historical reasons this entry is named "minimum", but it contains the TTL for negative answers (RFC 2308).

T_NAPTR
"order" : int
"preference" : int
"flags" : string
"service" : string
"regexp" : string
"replacement" : string
T_TXT
"txt" : string

Note: For historical reasons, when receiving decoded DNS entries from a client, this will be the first string in the TXT record only.

"txta" : string

When receiving decoded DNS data from a client, txta is the array of all strings in the record. When sending multiple strings in a TXT record in a server, please supply an array as "txt" containing the strings, txta will be ignored.

T_SPF
"spf" : string
T_CAA
"critical" : int

Sets the critical bit of the flag field.

"flags" : int 
"tag" : string

Cannot be empty.

"value" : string 

Method mkquery

string mkquery(string|mapping dnameorquery, int|void cl, int|void type)

Description

create a DNS query PDU

Parameter dnameorquery
Parameter cl

record class such as Protocols.DNS.C_IN

Parameter type

query type such Protocols.DNS.T_A

Returns

data suitable for use with Protocols.DNS.client.do_sync_query

Example

// 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);

Class Protocols.DNS.server

Description

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().

See also

dual_server


Inherit server_base

inherit server_base : server_base


Method create

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)

Description

Open one or more new DNS server ports.

Parameter ip

The IP to bind to. Defaults to "::" or 0 (ie ANY) depending on whether IPv6 support is present or not.

Parameter port

The port number to bind to. Defaults to 53.

Parameter more

Optional further DNS server ports to open. Must be a set of ip, port argument pairs.

Class Protocols.DNS.server_base

Description

Base class for server, tcp_server.


Inherit protocol

inherit protocol : protocol


Method handle_decode_error

protected void handle_decode_error(mapping err, mapping m, Stdio.UDP|object udp)

Description

Respond to a query that cannot be decoded.

This method exists so that servers can override the default behaviour.


Method handle_query

protected void handle_query(mapping q, mapping m, Stdio.UDP|object udp)

Description

Handle a query.

This function calls reply_query(), and dispatches the result to send_reply().


Method handle_response

protected void handle_response(mapping r, mapping m, Stdio.UDP|object udp)

Description

Handle a query response (stub).

Overload this function to handle responses to possible recursive queries.


Method rec_data

protected void rec_data(mapping m, Stdio.UDP|object udp)

Description

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().


Method reply_query

protected mapping|zero reply_query(mapping query, mapping udp_data, function(mapping:void) cb)

Description

Reply to a query (stub).

Parameter query

Parsed query.

Parameter 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.

Parameter 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.

Note

To indicate the default failure cb must be called with an argument of 0 (zero), and 0 (zero) be returned.

Returns

Returns 0 (zero) when the cb callback will be used, or a result mapping if not:

"rcode" : int

0 (or omit) for success, otherwise one of the Protocols.DNS.* constants

"an" : array(mapping(string:string|int))|void

Answer section:

Array
mapping(string:string|int) entry
"name" : string|array(string)
"type" : int
"cl" : int
"qd" : array|void

Question section, same format as an; omit to return the original question

"ns" : array|void

Authority section (usually NS records), same format as an

"ar" : array|void

Additional section, same format as an

"aa" : int

Set to 1 to include the Authoritative Answer bit in the response

"tc" : int

Set to 1 to include the TrunCated bit in the response

"rd" : int

Set to 1 to include the Recursion Desired bit in the response

"ra" : int

Set to 1 to include the Recursion Available bit in the response

"cd" : int

Set to 1 to include the Checking Disabled bit in the response

"ad" : int

Set to 1 to include the Authenticated Data bit in the response


Method report_decode_error

protected void report_decode_error(mixed err, mapping m, Stdio.UDP|object udp)

Description

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.

Class Protocols.DNS.tcp_client

Description

Synchronous DNS client using TCP Can handle larger responses than client can.


Inherit client

inherit client : client


Method do_sync_query

mapping|zero do_sync_query(string s)

Description

Perform a synchronous DNS query.

Parameter s

Result of Protocols.DNS.protocol.mkquery

Returns

mapping containing query result or 0 on failure/timeout

Example
// 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));

Class Protocols.DNS.tcp_server

Description

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

inherit server_base : server_base


Method create

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)

Description

Open one or more new DNS server ports.

Parameter ip

The IP to bind to. Defaults to "::" or 0 (ie ANY) depending on whether IPv6 support is present or not.

Parameter port

The port number to bind to. Defaults to 53.

Parameter more

Optional further DNS server ports to open. Must be a set of ip, port argument pairs.

13.4. LysKOM

Module Protocols.LysKOM

Class Protocols.LysKOM.Connection

Description

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.


Variable protocol_level
Variable session_software
Variable software_version

int Protocols.LysKOM.Connection.protocol_level
string Protocols.LysKOM.Connection.session_software
string Protocols.LysKOM.Connection.software_version

Description

Description of the connected server.


Method XXX
Method async_XXX
Method async_cb_XXX

mixed XXX(mixed ... args)
object async_XXX(mixed ... args)
object async_cb_XXX(function(:void) callback, mixed ... args)

Description

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.


Method create

Protocols.LysKOM.Connection Protocols.LysKOM.Connection(string server)
Protocols.LysKOM.Connection Protocols.LysKOM.Connection(string server, mapping options)

Description

The options argument is a mapping with the following members:

"login" : int|string

login as this person number (get number from name).

"password" : string

send this login password.

"invisible" : bool

if set, login invisible.

"port" : int(16bit)

server port (default is 4894).

"whoami" : string

present as this user (default is from uid/getpwent and hostname).

Class Protocols.LysKOM.Session


Variable user

object Protocols.LysKOM.Session.user

Description

This variable contains the Protocols.LysKOM.Session.Person that is logged in.


Method conference

Conference conference(int no)

Description

Returns conference number no.


Method create

Protocols.LysKOM.Session Protocols.LysKOM.Session(string server)
Protocols.LysKOM.Session Protocols.LysKOM.Session(string server, mapping options)

Description

Initializes the session object, and opens a connection to that server.

options is a mapping of options:

"login" : int|string

login as this person number (get number from name).

"create" : string

create a new person and login with it.

"password" : string

send this login password.

"invisible" : bool

if set, login invisible.

"port" : int(16bit)

server port (default is 4894).

"whoami" : string

present as this user (default is from uid/getpwent and hostname).

See also

Connection


Method create_person

object create_person(string name, string password)

Description

Create a person, which will be logged in. returns the new person object


Method create_text

object create_text(string subject, string body, mapping options)
object create_text(string subject, string body, mapping options, function(:void) callback, mixed ... extra)

Description

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:

"recpt" : Conference|array(Conference)

recipient conferences.

"cc" : Conference|array(Conference)

cc-recipient conferences.

"bcc" : Conference|array(Conference)

bcc-recipient conferences*.

"comm_to" : Text|array(Text)

The text(s) to be commented.

"foot_to" : Text|array(Text)

The text(s) to be footnoted.

"anonymous" : bool

send text anonymously.

"aux_items" : array(AuxItemInput)

AuxItems you want to set for the text*.

Note

The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.

See also

Conference.create_text(), Text.comment(), Text.footnote()


Method login

object login(int user_no, string password)
object login(int user_no, string password, int invisible)

Description

Performs a login. Throws a lyskom error if unsuccessful.

Returns

The session object logged in.


Method logout

this_program logout()

Description

Logouts from the server. returns the called object


Method person

Person person(int no)

Description

Returns the Person no.


Method register_async_message_callback

void register_async_message_callback(function(int, int, string:void) cb)


Method send_message

object|void send_message(string textstring, mapping options)

Description

Sends a message.

options is a mapping that may contain:

"recpt" : Conference

recipient conference.


Method text

Text text(int no)

Description

Returns the text no.


Method try_complete_person

array(ProtocolTypes.ConfZInfo) try_complete_person(string orig)

Description

Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.

Class Protocols.LysKOM.Session.AuxItemInput

FIXME

Undocumented


Inherit AuxItemInput

inherit ProtocolTypes.AuxItemInput : AuxItemInput

Class Protocols.LysKOM.Session.AuxItems

FIXME

Undocumented

Class Protocols.LysKOM.Session.Conference


Variable prefetch_stat
Variable no
Variable error
Variable msg_of_day
Variable supervisor
Variable permitted_submitters
Variable super_conf
Variable creator
Variable aux_items
Variable name
Variable type
Variable creation_time
Variable last_written
Variable nice
Variable no_of_members
Variable first_local_no
Variable no_of_texts
Variable presentation

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

FIXME

Undocumented


Method create

Protocols.LysKOM.Session.Conference Protocols.LysKOM.Session.Conference(int no)

Class Protocols.LysKOM.Session.Membership

Description

All variables in this class is read only.


Variable added_at

object Protocols.LysKOM.Session.Membership.added_at


Variable conf

object Protocols.LysKOM.Session.Membership.conf


Variable last_text_read

int Protocols.LysKOM.Session.Membership.last_text_read


Variable last_time_read

object Protocols.LysKOM.Session.Membership.last_time_read


Variable position

int Protocols.LysKOM.Session.Membership.position


Variable priority

int(8bit) Protocols.LysKOM.Session.Membership.priority


Variable read_texts

array(int) Protocols.LysKOM.Session.Membership.read_texts


Variable type

multiset(string) Protocols.LysKOM.Session.Membership.type


Method number_unread

int number_unread()


Method query_read_texts

void query_read_texts()


Method unread_texts

array(object) unread_texts()

Class Protocols.LysKOM.Session.Person


Variable error
Variable user_area
Variable username
Variable privileges
Variable flags
Variable last_login
Variable total_time_present
Variable sessions
Variable created_lines
Variable created_bytes
Variable read_texts
Variable no_of_text_fetches
Variable created_persons
Variable created_confs
Variable first_created_local_no
Variable no_of_created_texts
Variable no_of_marks
Variable no_of_confs
Variable unread
Variable clear_membership
Variable membership

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

FIXME

Undocumented


Variable no

int Protocols.LysKOM.Session.Person.no


Variable prefetch_stat
Variable prefetch_conf
Variable prefetch_membership

mixed Protocols.LysKOM.Session.Person.prefetch_stat
mixed Protocols.LysKOM.Session.Person.prefetch_conf
mixed Protocols.LysKOM.Session.Person.prefetch_membership

FIXME

Undocumented


Method create

Protocols.LysKOM.Session.Person Protocols.LysKOM.Session.Person(int no)

Class Protocols.LysKOM.Session.Text

Description

All variables in this class is read only.

FIXME

Undocumented


Variable author

string Protocols.LysKOM.Session.Text.author

Description

The author of the text.


Variable prefetch_text
Variable prefetch_stat
Variable lines
Variable characters
Variable clear_stat
Variable aux_items

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

FIXME

Undocumented


Variable creation_time

mixed Protocols.LysKOM.Session.Text.creation_time

Description

The time the text was created on the server.


Variable err

object Protocols.LysKOM.Session.Text.err

Description

Undocumented


Variable marks

int Protocols.LysKOM.Session.Text.marks

Description

The number of marks on this text.


Variable misc

mixed Protocols.LysKOM.Session.Text.misc

Description

Misc info, including what conferences the message is posted to.

FIXME

Needs a more complete description.


Variable no

int Protocols.LysKOM.Session.Text.no

Description

The text number, as spicified to create.


Variable subject

string Protocols.LysKOM.Session.Text.subject

Description

The message subject.


Variable text

string Protocols.LysKOM.Session.Text.text

Description

The actual text (or body if you wish).


Method create

Protocols.LysKOM.Session.Text Protocols.LysKOM.Session.Text(string textnumber)

Description

Initializes a Text object.


Method mark_as_read

void mark_as_read()

FIXME

Undocumented.

Module Protocols.LysKOM.ProtocolTypes

Description

Data types as defined by the LysKOM protocol specification.

Module Protocols.LysKOM.Request

Description

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.

Class Protocols.LysKOM.Request._Request

Description

This is the base class for lyskom requests. All lyskom request classes inherit this class.


Variable error

object Protocols.LysKOM.Request._Request.error

Description

How the call failed. The call has completed if (ok||error).


Variable ok

bool Protocols.LysKOM.Request._Request.ok

Description

Tells if the call has executed ok


Method _async
Method _sync

void _async(int call, mixed_data)
mixed _sync(int call, mixed_data)

Description

Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.


Method _reply
Method reply

mixed _reply(object|array what)
mixed reply(object|array what)

Description

_reply() is called as callback to evaluate the result, and calls reply() in itself to do the real work.


Method `()

mixed res = Protocols.LysKOM.Request._Request()()

Description

Wait for the call to finish.


Method async
Method sync

void async(mixed ... args)
mixed sync(mixed ... args)

Description

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.

13.5. Other protocols

Module Protocols

Module Protocols.Bittorrent

Class Protocols.Bittorrent.DHT

Description

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


Variable MAX_PEERS_PER_HASH

int Protocols.Bittorrent.DHT.MAX_PEERS_PER_HASH

Description

Maximum number of peers per hash that we store.


Variable PEER_TABLE_MAX_SIZE

int Protocols.Bittorrent.DHT.PEER_TABLE_MAX_SIZE

Description

Maximum number hashes we store data for in this node.


Variable callbacks_by_txid
Variable request_timeouts

mapping(string:mixed) Protocols.Bittorrent.DHT.callbacks_by_txid
mapping(string:mixed) Protocols.Bittorrent.DHT.request_timeouts

Description

Keep track of callbacks by transaction id


Variable command_handlers

mapping(string:function(:void)) Protocols.Bittorrent.DHT.command_handlers

Description

Mapping of query names to handlers. Allows for extensions to be implemented.


Variable is_running

int Protocols.Bittorrent.DHT.is_running

Description

Indicates if the DHT instance is up and running or not.


Variable my_node_id

protected string|zero Protocols.Bittorrent.DHT.my_node_id

Description

Our global ID for this DHT router, expressed as a 20 byte hash.


Variable peers_by_hash

mapping(string:mapping) Protocols.Bittorrent.DHT.peers_by_hash

Description

Peers we know of.


Variable port

Stdio.UDP|zero Protocols.Bittorrent.DHT.port

Description

The UDP port on which we listen for messages.


Method add_node

DHTNode add_node(string|DHTNode n, void|string ip, void|int port)

Description

Gateway into the routing table for now. This is in preparation for BEP045.


Method add_peer_for_hash

void add_peer_for_hash(Peer n, string hash, string ip, int port)

Description

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.


Method announce

void announce(string hash, int port)

Description

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.


Method announce_to

protected void announce_to(string peer_ip, int peer_port, string token, string info_hash, int announced_port, void|int implied_port)

Description

This is the internal announce callback - it is called for each node that we should send an announcement to.


Method create

Protocols.Bittorrent.DHT Protocols.Bittorrent.DHT(void|string my_node_id)

Description

Create a new DHT instance with an optional predefined node id.


Method distance

string distance(string h1, string h2)

Description

Calculate the distance between two hashes using XOR. Fails unless both h1 and h2 are strings of the same length.


Method distance_exp

int distance_exp(string h1, string h2)

Description

Calculate the order of magnitude of the distance. Basically count leading zeros...


Method generate_node_id

string generate_node_id()

Description

Generate a 160 bit node id.


Method generate_token_for

Token generate_token_for(string ip, int port, void|int dont_sha1)

Description

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.


Method generate_txid

string generate_txid()

Description

Generates suitable transaction ids making sure to not collide with existing ones.


Method get_node_id

string get_node_id()

Description

Allows outsiders to examine the node id of this instance.


Method handle_announce_peer

void handle_announce_peer(mapping data, string ip, int port)

Description

Handles other peers announcing to us for safekeeping.


Method handle_find_node

void handle_find_node(mapping data, string ip, int req_port)

Description

Handles request for nodes closer to a hash.


Method handle_get_peers

void handle_get_peers(mapping data, string ip, int port)

Description

Returns peers to the requestor or our closest nodes if we don't know of any peers.


Method handle_ping

void handle_ping(mapping data, string ip, int port)

Description

Handles PONG responses to incoming PINGs.


Method handle_unknown_method

void handle_unknown_method(mapping data, string ip, int port)

Description

Responds to unknown methods. Currently does nothing at all.


Method info

mapping info()

Description

Returns some basic information about this DHT instance.


Method read_callback

protected void read_callback(mapping(string:int|string) datagram, mixed ... extra)

Description

Called when we recieve a datagram on the UDP port we are listening to.


Method read_timeout

protected void read_timeout(string txid)

Description

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.


Method send_dht_query

string send_dht_query(string to, int dstport, mapping data, void|function(:void) response_callback, mixed ... args)

Description

Sends a DHT query and calls the callback when a response is recieved or when a timeout occurs.


Method send_dht_request

int send_dht_request(string to, int dstport, mapping data)

Description

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.


Method send_ping

string send_ping(string ip, int port, function(mapping, string, int:void) cb)

Description

Sends a PING to a remote port and calls the callback cb if we get a response.


Method set_node_id

void set_node_id(string my_node_id)

Description

Sets the node id of this instance. This has implications for the routing table, so we need to reinitialize it if this happens...


Method start

void start(int port, void|string bind_address)

Description

Start up the DHT instance.


Method stop

void stop()

Description

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.


Method token_by_endpoint

Token token_by_endpoint(string ip, int port)

Description

Returns a token object for the given ip/port if one exists.

Enum Protocols.Bittorrent.DHT.DHT_ERROR


Constant DHT_GENERIC_ERROR
Constant DHT_SERVER_ERROR
Constant DHT_PROTOCOL_ERROR
Constant DHT_UNKNOWN_METHOD
Constant DHT_QUERY_TIMEOUT

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

Class Protocols.Bittorrent.DHT.DHTNode

Description

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

inherit Node : Node


Variable age

int Protocols.Bittorrent.DHT.DHTNode.age

Description

Time since last response seen from this node

Note

Read only


Method activity

void activity()

Description

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.


Method cancel_check_node

void cancel_check_node()

Description

Removes any outstanding callouts to check the node.


Method compact_node_info

string compact_node_info()

Description

Returns the compact node info for this node.


Method node_info

mapping node_info()

Description

Extend the Node::node_info() method to include info relevant to a DHTNode.


Method node_info_human

mapping node_info_human()

Description

Human readable output version of the node_info method.


Method node_state

string node_state()

Description

Returns the node state as a string.


Method ping

void ping()

Description

Ping the node to see if it is still responding.


Method ping_timeout

protected void ping_timeout(string txid)

Description

Called when a ping request to this peer times out. We set the state to DHT_BAD and leave it at that.


Method remove_txid

protected void remove_txid(string txid)

Description

Removes an outstanding ping TXID from the pings_inflight mapping.

Enum Protocols.Bittorrent.DHT.DHTNode.DHT_NODE_STATE


Constant DHT_UNKNOWN
Constant DHT_BAD
Constant DHT_ACTIVE

constant Protocols.Bittorrent.DHT.DHTNode.DHT_UNKNOWN
constant Protocols.Bittorrent.DHT.DHTNode.DHT_BAD
constant Protocols.Bittorrent.DHT.DHTNode.DHT_ACTIVE

Class Protocols.Bittorrent.DHT.DHTOperation

Description

Base class for operations that need to iterate over the DHT in some way like get_peers and find_node.


Variable desired_results

int Protocols.Bittorrent.DHT.DHTOperation.desired_results

Description

Desired number of results before the op considers itself done


Variable target_hash
Variable done_cb
Variable done_cb_args

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


Variable max_no_requests

int Protocols.Bittorrent.DHT.DHTOperation.max_no_requests

Description

Maximum number of requests that may be generated before bailing out.


Variable max_outstanding_requests

int(0..) Protocols.Bittorrent.DHT.DHTOperation.max_outstanding_requests

Description

Maximum number of concurrent requests allowed


Variable query_timeout_period

float|int Protocols.Bittorrent.DHT.DHTOperation.query_timeout_period

Description

Timeout for the query


Variable reqs

int Protocols.Bittorrent.DHT.DHTOperation.reqs

Description

Number of requests generated by this query


Variable result

array Protocols.Bittorrent.DHT.DHTOperation.result

Description

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


Variable result_count

int Protocols.Bittorrent.DHT.DHTOperation.result_count

Description

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.


Method __create__

protected local void __create__(string target_hash, function(:void)|zero done_cb, mixed ... done_cb_args)


Method add_node_to_query

void add_node_to_query(Node n)

Description

Add a node to the list of nodes to query.


Method create

Protocols.Bittorrent.DHT.DHTOperation Protocols.Bittorrent.DHT.DHTOperation(string target_hash, function(:void)|zero done_cb, mixed ... done_cb_args)


Method do_query_peer

private void do_query_peer(Node peer)

Description

Create a request to the peer info given. The peer info array is expected to contain peer hash, peer ip, peer port.


Method done

protected void done()

Description

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.


Method execute

this_program execute()

Description

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!


Method generate_query

protected mapping generate_query()

Description

This method should be overridden by the actual handlers for the operation.


Method got_response_cb

private void got_response_cb(mapping resp)

Description

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.


Method is_done

int is_done()

Description

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.


Method query_timeout

private void query_timeout(string txid)

Description

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.


Method run

private void run()

Description

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.


Method want_more_results

int want_more_results()

Description

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.

Class Protocols.Bittorrent.DHT.FindNode

Description

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

inherit DHTOperation : DHTOperation


Variable desired_results

int Protocols.Bittorrent.DHT.FindNode.desired_results

Description

Override the default number of desired results


Method execute

this_program execute()

Description

Execute method that also checks if we have the targets in our routing table.


Method generate_query

protected mapping generate_query()

Description

Callback called by parent to generate the query for this operation

Class Protocols.Bittorrent.DHT.GetPeers

Description

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

inherit DHTOperation : DHTOperation


Variable closest_nodes

array Protocols.Bittorrent.DHT.GetPeers.closest_nodes

Description

Sorted array of the closest K nodes we've seen in the query.


Variable desired_results

int Protocols.Bittorrent.DHT.GetPeers.desired_results

Description

Override the default number of desired results


Method done

void done()

Description

Add the closest nodes we know of and call the callback.


Method generate_query

protected mapping generate_query()

Description

Implementation of DHTNode:generate_query that returns a get_peers query.

Class Protocols.Bittorrent.DHT.Node

Description

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.


Method endpoint

string endpoint()

Description

Returns the node endpoint as plain text


Method endpoint_compact

string endpoint_compact()

Description

Returns just the IP and port as an 8-bit string.


Method node_info

mapping(string:mixed) node_info()

Description

Return basic info about the node as a mapping. All values are human readable.


Method node_info_human

mapping(string:mixed) node_info_human()

Description

Like node_info but encodes node id and token as hex-strings.

Class Protocols.Bittorrent.DHT.Peer

Description

Information about the peeer for a hash


Inherit Node

inherit Node : Node

Class Protocols.Bittorrent.DHT.Routingtable

Description

Abstraction for the routing table.


Variable allow_node_in_routing_table

function(DHTNode:int) Protocols.Bittorrent.DHT.Routingtable.allow_node_in_routing_table

Description

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.


Variable bucket_by_uuid
Variable buckets

mapping(string:Bucket) Protocols.Bittorrent.DHT.Routingtable.bucket_by_uuid
array(Bucket) Protocols.Bittorrent.DHT.Routingtable.buckets

Description

Buckets in our routing table


Variable my_node_id

protected string|zero Protocols.Bittorrent.DHT.Routingtable.my_node_id

Description

Node ID that this routing table belongs to


Variable nodes_by_hash
Variable nodes_by_endpoint

mapping(string:DHTNode) Protocols.Bittorrent.DHT.Routingtable.nodes_by_hash
mapping(string:DHTNode) Protocols.Bittorrent.DHT.Routingtable.nodes_by_endpoint

Description

Lookup table for nodess so we can quickly find out if any given hash is already in our table somewhere.


Method add_node

DHTNode add_node(string|DHTNode n, void|string ip, void|int port)

Description

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.


Method bucket_for

Bucket bucket_for(string|DHTNode n)

Description

Calculate and return the bucket in which DHTNode n should belong to.


Method copy_from

void copy_from(this_program rt)

Description

Iterate over the given routingtable, copying the nodes as we go along.


Method deserialize

void deserialize(array(mapping) nodes)

Description

Deserialize an array created by serialize.


Method serialize

array serialize()

Description

Serialize the routing table into basic types so that it may be encoded for storage


Method split_bucket

int split_bucket(Bucket b, void|int dont_promote)

Description

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.

Class Protocols.Bittorrent.DHT.Routingtable.Bucket


Method add_node

int add_node(DHTNode n, void|int dont_notify)

Description

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.


Method details

mapping details()

Description

Returns a mapping with details about the bucket, including a complete list of live and candidate nodes.


Method evict_bad_nodes

void evict_bad_nodes()

Description

Used to evict bad nodes from the bucket. Used by add_node() before attempting to add nodes the bucket.


Method info

mapping info()

Description

returns a mapping with overall information about the bucket.


Method is_full

bool is_full()

Description

Returns 1 if the bucket is full of live nodes.


Method low_add_candidate

protected int low_add_candidate(DHTNode n, void|int dont_notify)

Description

Adds a node to the bucket as a candidate with the option of suppressing notifications. Returns 0 on success.


Method low_add_node

int low_add_node(DHTNode n, void|int dont_notify)

Description

Adds a node to the bucket as a live node with the option to surpress notifications. Returns 0 on success.


Method promote_nodes

void promote_nodes()

Description

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.


Method remove_node

int remove_node(DHTNode n, void|int dont_notify)

Description

Remove a node from this bucket and optionally surpress notification of the event. Returns 0 if the node was successfully removed.

Class Protocols.Bittorrent.DHT.Token


Method create

Protocols.Bittorrent.DHT.Token Protocols.Bittorrent.DHT.Token(string ip, int port, void|int dont_sha1)

Description

Generate a new token for the given IP/port. Optionally don't apply SHA1 to the token for debugging purposes.


Method invalidate

Token invalidate()

Description

Invalidates a token if it exists,


Method refresh

this_program refresh()

Description

Refreshes a token's lifetime to the configured token_lifetime value. Note: If called on an old token, this will violate recommendations in BEP005.


Method valid_for

int valid_for(string ip, int port)

Description

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.

Class Protocols.Bittorrent.Generator

Description

Generate a .torrent binary string from files in the filesystem

Example

// 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

inherit .Torrent : Torrent


Method add

this_program add(string path, void|string base)

Description

Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.


Method add_announce

this_program add_announce(string|array(string) announce_url)

Description

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.


Method add_directory_tree

this_program add_directory_tree(string path, void|string dirbase)

Description

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.


Method add_file

this_program add_file(string path, void|string filename)

Description

Add a file to the torrent. The second argument is what the file will be called in the torrent.


Method build_sha1s

void build_sha1s(void|function(int, int:void) progress_callback)

Description

Build the SHA hashes from the files.


Method create

Protocols.Bittorrent.Generator Protocols.Bittorrent.Generator(void|string base, void|int piece_size)

Description

Create a generator.

Parameter base

The base filename/path in the torrent.

Parameter piece_size

The size of the pieces that the SHA hashes are calculated on. Default 262144 and this value should probably be 2^n.


Method digest

string digest(void|function(int, int:void) progress_callback)

Description

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.

Class Protocols.Bittorrent.Peer


Method connect

void connect()

Description

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).


Method disconnect

void disconnect()

Description

Disconnect a peer. Does nothing if we aren't online. status/mode will change to "disconnected",1 if we were online.


Method downloading_pieces

multiset(int) downloading_pieces()

Description

Returns as multiset what this peer is downloading.


Method is_activated

int is_activated()

Description

Returns true if this peer is activated, as in we're downloading from it.


Method is_available

int is_available()

Description

Returns true if this peer is available, as in we can use it to download stuff.


Method is_choked

int is_choked()

Description

Returns true if this peer is choking, as in doesn't send more data to us.


Method is_completed

int is_completed()

Description

Returns true if this peer is completed, as in has downloaded everything already - and we shouldn't need to upload to get stuff.


Method is_connectable

int is_connectable()

Description

Returns true if we can connect to this peer, when new or disconnected but not fatally.


Method is_online

int is_online()

Description

Returns true if this peer is online and connected.


Method is_strangled

int is_strangled()

Description

Returns true if this peer is strangled; as in we don't want to upload more, because we're not getting any back.


Method request

void request(int piece, int offset, int bytes, function(int, int, string, object:void|mixed) callback)

Description

Called to request a chunk from this peer.


Method send_have

void send_have(int n)

Description

Send a have message to tell I now have piece n. Ignored if not online.


Method status

void status(string type, void|int|string data)

Description

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.

Class Protocols.Bittorrent.Port


Method create

Protocols.Bittorrent.Port Protocols.Bittorrent.Port(.Torrent _parent)

Description

Bind a port for this Torrent.

Class Protocols.Bittorrent.Torrent

Description

Bittorrent peer - download and share. Read more about bittorrent at http://bitconjurer.org/BitTorrent/introduction.html

Example

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;
  }

Variable do_we_strangle

function(.Peer, int, int:bool) Protocols.Bittorrent.Torrent.do_we_strangle

Description

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.


Variable download_completed_callback

function(:void) Protocols.Bittorrent.Torrent.download_completed_callback

Description

If set, called when download is completed.


Variable downloads_update_status

function(:void) Protocols.Bittorrent.Torrent.downloads_update_status

Description

If set, called when we start to download another piece (no args).


Variable peer_update_status

function(:void) Protocols.Bittorrent.Torrent.peer_update_status

Description

If set, called when peer status changes.


Variable pieces_update_status

function(:void) Protocols.Bittorrent.Torrent.pieces_update_status

Description

If set, called when we got another piece downloaded (no args).


Variable warning

function(string, __unknown__ ... :void|mixed) Protocols.Bittorrent.Torrent.warning

Description

Called if there is a protocol error.


Method bytes_done

int bytes_done()

Description

Calculate the bytes successfully downloaded (full pieces).


Method bytes_left

int bytes_left()

Description

Calculate the bytes left to download.


Method contact_peers

void contact_peers(void|int n)

Description

Contact all or n peers.


Method file_got_bitfield

string file_got_bitfield()

Description

Returns the file got field as a string bitfield (cached).


Method fix_targets

int fix_targets(void|int(-1..2) allocate, void|string base_filename, void|function(int, int:void) progress_callback)

Description

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.

Parameter allocate

Determines allocation procedure if the file doesn't exist:

0

Don't allocate.

1

Allocate virtual file size (seek, write end byte).

2

Allocate for real (will call progress_callback(pos,length)).

-1

Means never create a file, only open old files.

Parameter my_filename

A new base filename to substitute the metainfo base target filename with.

Returns
1

The (a) file was already there.

2

All target files were created.


Method load_metainfo

void load_metainfo(string filename)

Description

Loads the metainfo from a file.


Method open_port

void open_port(void|int port)

Description

Open the port we're listening on.


Method start_download

void start_download()

Description

Initiate the downloading scheme.


Method start_update_tracker

void start_update_tracker(void|int interval)

Description

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.


Method stop_update_tracker

void stop_update_tracker(void|string event)

Description

Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.


Method update_tracker

void update_tracker(void|string event, void|int contact)

Description

Contact and update the tracker with current status will fill the peer list.


Method verify_targets

void verify_targets(void|function(int, int:void) progress_callback)

Description

Verify the file and fill file_got (necessary after load_info, but needs open_file before this call). [ progress_callback(at chunk,total chunks) ]

Class Protocols.Bittorrent.Torrent.Target

Description

Each bittorrent has one or more target files. This represents one of those.


Variable base
Variable length
Variable offset
Variable path

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


Method __create__

protected local void __create__(string base, int length, int offset, void|array path)


Method create

Protocols.Bittorrent.Torrent.Target Protocols.Bittorrent.Torrent.Target(string base, int length, int offset, void|array path)

Class Protocols.Bittorrent.Tracker


Variable dynamic_add_torrents

bool Protocols.Bittorrent.Tracker.dynamic_add_torrents

Description

Allow clients to dynamically add torrents to the tracker.


Variable interval

int(0..) Protocols.Bittorrent.Tracker.interval

Description

The query interval reported back to clients. Defaults to 1800.


Method add_torrent

void add_torrent(string id)

Description

Add a torrent to the tracker.

Parameter id

The info hash of the torrent file.


Method announce

string announce(mapping args, string ip)

Description

Handles HTTP announce queries to the tracker.


Method scrape

string scrape(mapping args)

Description

Returns the result of a scrape query.

Class Protocols.Bittorrent.Tracker.Client


Variable ip
Variable port

string Protocols.Bittorrent.Tracker.Client.ip
int Protocols.Bittorrent.Tracker.Client.port


Method __create__

protected local void __create__(string ip, int port)


Method create

Protocols.Bittorrent.Tracker.Client Protocols.Bittorrent.Tracker.Client(string ip, int port)

Module Protocols.Bittorrent.Bencoding


Method bits2string

string bits2string(array(bool) v)

Description

Convert an array of int(0..1) to a Bittorrent style bitstring. Input will be padded to even bytes.


Method decode

string|int|array|mapping decode(Stdio.Buffer buf)

Description

Decodes a Bittorrent bencoded data chunk and ignores the remaining string. Returns UNDEFINED if the data is incomplete.


Method encode

string encode(string|int|array|mapping data)

Description

Encodes a Bittorrent bencoded data chunk.


Method string2arr

array(int) string2arr(string s)

Description

Convert a Bittorrent style bitstring to an array of indices.


Method string2bits

array(bool) string2bits(string s)

Description

Convert a Bittorrent style bitstring to an array of int(0..1).

Module Protocols.Bittorrent.PeerID


Method identify_peer

string identify_peer(string peerid)

Description

Decodes the given peerid, returning an identification string for the client software. Assumes the peerid string is exactly 20 characters long.

Module Protocols.DNS_SD

Class Protocols.DNS_SD.Service

Description

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 Service

inherit _Protocols_DNS_SD.Service : Service


Method create

Protocols.DNS_SD.Service Protocols.DNS_SD.Service(string name, string service, string domain, int port, void|string|array(string) txt)

Description

Registers a service on the local network.

Parameter name

User-presentable name of the service.

Parameter 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.

Parameter domain

Domain name. Normally an empty string which the DNS-SD library will translate into local..

Parameter port

Port number for the service (e.g. 80 for a web site).

Parameter 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.

Example

object svc = Protocols.DNS_SD.Service( "Company Intranet Forum", // name "_http._tcp", // service type "", // domain (default) 80, // port ({ "path=/forum/" }) // TXT record );


Method update_txt

void update_txt(string|array(string) txt)

Description

Updates the TXT record for the service.

Parameter 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.

Module Protocols.HTTP2

Description

HTTP/2 protocol.

RFC 7540.


Constant TLS_CIPHER_SUITE_BLACK_LIST

constant Protocols.HTTP2.TLS_CIPHER_SUITE_BLACK_LIST

Description

RFC 7540 appendix A.

Enum Protocols.HTTP2.Error


Constant ERROR_no_error
Constant ERROR_protocol_error
Constant ERROR_internal_error
Constant ERROR_flow_control_error
Constant ERROR_settings_timeout
Constant ERROR_stream_closed
Constant ERROR_frame_size_error
Constant ERROR_refused_stream
Constant ERROR_cancel
Constant ERROR_compression_error
Constant ERROR_connect_error
Constant ERROR_enhance_your_calm
Constant ERROR_inadequate_security
Constant ERROR_http_1_1_required

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

Enum Protocols.HTTP2.Flag


Constant FLAG_end_stream
Constant FLAG_ack
Constant FLAG_end_headers
Constant FLAG_padded
Constant FLAG_priority

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

Enum Protocols.HTTP2.FrameType


Constant FRAME_data
Constant FRAME_headers
Constant FRAME_priority
Constant FRAME_rst_stream
Constant FRAME_settings
Constant FRAME_push_promise
Constant FRAME_ping
Constant FRAME_goaway
Constant FRAME_window_update
Constant FRAME_continuation

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

Enum Protocols.HTTP2.Setting


Constant SETTING_header_table_size
Constant SETTING_enable_push
Constant SETTING_max_concurrent_streams
Constant SETTING_initial_window_size
Constant SETTING_max_frame_size
Constant SETTING_max_header_list_size

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

Class Protocols.HTTP2.Frame

Description

HTTP/2 frame.


Variable frame_type
Variable flags

FrameType Protocols.HTTP2.Frame.frame_type
Flag Protocols.HTTP2.Frame.flags


Variable payload

int|Stdio.Buffer|array(array(string(8bit))) Protocols.HTTP2.Frame.payload

Description

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.


Variable promised_stream_id

int|void Protocols.HTTP2.Frame.promised_stream_id

Description

Only used with FRAME_push_promise, and overrides stream_id.


Variable stream_id

int|void Protocols.HTTP2.Frame.stream_id

Description

Stream identifier.


Method __create__

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)


Method create

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)

Module Protocols.IMAP

Description

IMAP (Internet Message Access Protocol) server support

Class Protocols.IMAP.imap_server

Description

imap_server.pike

Class Protocols.IMAP.parse_line

Description

parse_line.pike


Method get_atom_options

mapping|zero get_atom_options(int max_depth)

Description

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 })


Method get_flag_list

array(string)|zero get_flag_list()

Description

Get a list of atoms. Primarily intended for use by STORE for the flags argument.


Method get_range

mapping|zero get_range(mapping atom)

Description

Reads a <start.size> suffix


Method get_set

object|zero get_set()

Description

Returns a set object.


Method get_simple_list

mapping|zero get_simple_list(int max_depth)

Description

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.


Method get_token

mapping get_token(int eol, int accept_options)

Description

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.

Class Protocols.IMAP.parser

Description

Continuation based imap parser.

Class Protocols.IMAP.server

Description

IMAP.server

Handles the server side of the protocol.


Inherit imap_style

inherit Protocols.Line.imap_style : imap_style

Module Protocols.IMAP.requests

Description

IMAP.requests

Module Protocols.IMAP.types

Description

IMAP.types

Module Protocols.IPv6


Method format_addr_short

string format_addr_short(array(int(16bit)) bin_addr)

Description

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.

See also

parse_addr


Method normalize_addr_basic

string|zero normalize_addr_basic(string addr)

Description

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.

See also

normalize_addr_short


Method normalize_addr_short

string|zero normalize_addr_short(string addr)

Description

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.

See also

normalize_addr_basic


Method parse_addr

array(int(16bit))|zero parse_addr(string addr)

Description

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.

See also

format_addr_short

Module Protocols.IRC

Description

IRC client and connection handling.

Start with Client and Channel.

Example

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; }

Class Protocols.IRC.Channel

Description

Abstract class for an IRC channel.


Variable name

string Protocols.IRC.Channel.name

Description

The name of the channel.


Method not_join

void not_join(Person who)

Description

Called whenever someone joins this channel.


Method not_message

void not_message(Person who, string message)

Description

Called whenever a message arrives on this channel.

Class Protocols.IRC.Client


Method close

void close()

Description

Closes the connection to the server.


Method create

Protocols.IRC.Client Protocols.IRC.Client(string|object server, void|mapping(string:mixed) options)

Parameter 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.

Parameter options

An optional mapping with additional IRC client options.

"port" : int

Defaults to 6667.

"user" : string

Defaults to "unknown" on systems without getpwuid and getuid and to getpwuid(getuid())[0] on systems with.

"nick" : string

Defaults to "Unknown" on systems without getpwuid and getuid and to String.capitalize(getpwuid(getuid())[0]) on systems with.

"pass" : string

Server password, if any. Public servers seldom require this.

"realname" : string

Defaults to "Mr. Anonymous" on systems without getpwuid and getuid and to getpwuid(getuid())[4] on systems with.

"host" : string

Defaults to "localhost" on systems without uname and to uname()->nodename on systems with.

"ping_interval" : int

Defaults to 120.

"ping_timeout" : int

Defaults to 120.

"connection_lost" : function(void:void)

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.

"channel_program" : program

An instance of this is created for each channel connected to via join_channel() - should be a subclass of Protocols.IRC.Channel.

"error_notify" : function(mixed ... :void)

This function is called when a KILL or ERROR command is recieved from the IRC server.

"system_notify" : function(string, void|string:void) 
"motd_notify" : function(string, void|string:void) 
"error_nickinuse" : function(string:void) 
"generic_notify" : function(string, string, string, string, string:void)

The arguments are from, type, to, message and extra.

"quit_notify" : function(string, string:void)

The arguments are who and why.

"privmsg_notify" : function(Person, string, string:void)

The arguments are originator, message and to.

"notice_notify" : function(Person, string, string:void)

The arguments are originator, message and to.

"nick_notify" : function(Person, string:void)

The arguments are originator and to.

Class Protocols.IRC.Person

Description

Abstract class for a person.


Variable ip

string Protocols.IRC.Person.ip

Description

User domain, e.g. "mistel.idonex.se".


Variable last_action

int Protocols.IRC.Person.last_action

Description

Time of last action, represented as posix time.


Variable nick

string Protocols.IRC.Person.nick

Description

User nickname, e.g. "Mirar".


Variable user

string Protocols.IRC.Person.user

Description

User name, e.g. "mirar".

Module Protocols.Ident

Description

An implementation of the IDENT protocol, specified in RFC 0931.


Method lookup

array(string) lookup(object fd)

Throws

Throws exception upon any error.

Class Protocols.Ident.AsyncLookup


Method create

Protocols.Ident.AsyncLookup Protocols.Ident.AsyncLookup(object fd, function(array(string), mixed ... :void) cb, mixed ... args)

Module Protocols.LDAP


Constant GUID_USERS_CONTAINER
Constant GUID_COMPUTERS_CONTAINER
Constant GUID_SYSTEMS_CONTAINER
Constant GUID_DOMAIN_CONTROLLERS_CONTAINER
Constant GUID_INFRASTRUCTURE_CONTAINER
Constant GUID_DELETED_OBJECTS_CONTAINER
Constant GUID_LOSTANDFOUND_CONTAINER
Constant GUID_FOREIGNSECURITYPRINCIPALS_CONTAINER
Constant GUID_PROGRAM_DATA_CONTAINER
Constant GUID_MICROSOFT_PROGRAM_DATA_CONTAINER
Constant GUID_NTDS_QUOTAS_CONTAINER

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

Description

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 LDAP_SUCCESS
Constant LDAP_OPERATIONS_ERROR
Constant LDAP_PROTOCOL_ERROR
Constant LDAP_TIMELIMIT_EXCEEDED
Constant LDAP_SIZELIMIT_EXCEEDED
Constant LDAP_COMPARE_FALSE
Constant LDAP_COMPARE_TRUE
Constant LDAP_AUTH_METHOD_NOT_SUPPORTED
Constant LDAP_STRONG_AUTH_NOT_SUPPORTED
Constant LDAP_STRONG_AUTH_REQUIRED
Constant LDAP_PARTIAL_RESULTS
Constant LDAP_REFERRAL
Constant LDAP_ADMINLIMIT_EXCEEDED
Constant LDAP_UNAVAILABLE_CRITICAL_EXTENSION
Constant LDAP_CONFIDENTIALITY_REQUIRED
Constant LDAP_SASL_BIND_IN_PROGRESS
Constant LDAP_NO_SUCH_ATTRIBUTE
Constant LDAP_UNDEFINED_TYPE
Constant LDAP_INAPPROPRIATE_MATCHING
Constant LDAP_CONSTRAINT_VIOLATION
Constant LDAP_TYPE_OR_VALUE_EXISTS
Constant LDAP_INVALID_SYNTAX
Constant LDAP_NO_SUCH_OBJECT
Constant LDAP_ALIAS_PROBLEM
Constant LDAP_INVALID_DN_SYNTAX
Constant LDAP_IS_LEAF
Constant LDAP_ALIAS_DEREF_PROBLEM
Constant LDAP_INAPPROPRIATE_AUTH
Constant LDAP_INVALID_CREDENTIALS
Constant LDAP_INSUFFICIENT_ACCESS
Constant LDAP_BUSY
Constant LDAP_UNAVAILABLE
Constant LDAP_UNWILLING_TO_PERFORM
Constant LDAP_LOOP_DETECT
Constant LDAP_SORT_CONTROL_MISSING
Constant LDAP_NAMING_VIOLATION
Constant LDAP_OBJECT_CLASS_VIOLATION
Constant LDAP_NOT_ALLOWED_ON_NONLEAF
Constant LDAP_NOT_ALLOWED_ON_RDN
Constant LDAP_ALREADY_EXISTS
Constant LDAP_NO_OBJECT_CLASS_MODS
Constant LDAP_RESULTS_TOO_LARGE
Constant LDAP_AFFECTS_MULTIPLE_DSAS
Constant LDAP_OTHER

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

Description

LDAP result codes.

See also

Protocols.LDAP.client.error_number, Protocols.LDAP.client.result.error_number


Constant LDAP_CONTROL_MANAGE_DSA_IT

constant string Protocols.LDAP.LDAP_CONTROL_MANAGE_DSA_IT

Description

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 LDAP_CONTROL_VLVREQUEST

constant string Protocols.LDAP.LDAP_CONTROL_VLVREQUEST

Description

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 LDAP_CONTROL_VLVRESPONSE

constant string Protocols.LDAP.LDAP_CONTROL_VLVRESPONSE

Description

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 LDAP_PAGED_RESULT_OID_STRING

constant string Protocols.LDAP.LDAP_PAGED_RESULT_OID_STRING

Description

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 LDAP_SERVER_ASQ_OID

constant string Protocols.LDAP.LDAP_SERVER_ASQ_OID

Description

LDAP control: Microsoft AD: Control to force the query to be based on a specific DN-valued attribute.


Constant LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID

constant string Protocols.LDAP.LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID

Description

LDAP control: Microsoft AD: Control used with an extended LDAP rename function to move an LDAP object from one domain to another.


Constant LDAP_SERVER_DIRSYNC_OID

constant string Protocols.LDAP.LDAP_SERVER_DIRSYNC_OID

Description

LDAP control: Microsoft AD: Control that enables an application to search the directory for objects changed from a previous state.


Constant LDAP_SERVER_DOMAIN_SCOPE_OID

constant string Protocols.LDAP.LDAP_SERVER_DOMAIN_SCOPE_OID

Description

LDAP control: Microsoft AD: Control used to instruct the LDAP server not to generate any referrals when completing a request.


Constant LDAP_SERVER_EXTENDED_DN_OID

constant string Protocols.LDAP.LDAP_SERVER_EXTENDED_DN_OID

Description

LDAP control: Microsoft AD: Control to request an extended form of an Active Directory object distinguished name.


Constant LDAP_SERVER_LAZY_COMMIT_OID

constant string Protocols.LDAP.LDAP_SERVER_LAZY_COMMIT_OID

Description

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 LDAP_SERVER_NOTIFICATION_OID

constant string Protocols.LDAP.LDAP_SERVER_NOTIFICATION_OID

Description

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 LDAP_SERVER_PERMISSIVE_MODIFY_OID

constant string Protocols.LDAP.LDAP_SERVER_PERMISSIVE_MODIFY_OID

Description

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 LDAP_SERVER_QUOTA_CONTROL_OID

constant string Protocols.LDAP.LDAP_SERVER_QUOTA_CONTROL_OID

Description

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 LDAP_SERVER_RESP_SORT_OID

constant string Protocols.LDAP.LDAP_SERVER_RESP_SORT_OID

Description

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 LDAP_SERVER_SD_FLAGS_OID

constant string Protocols.LDAP.LDAP_SERVER_SD_FLAGS_OID

Description

LDAP control: Microsoft AD: Control used to pass flags to the server to control various security descriptor results.


Constant LDAP_SERVER_SEARCH_OPTIONS_OID

constant string Protocols.LDAP.LDAP_SERVER_SEARCH_OPTIONS_OID

Description

LDAP control: Microsoft AD: Control used to pass flags to the server to control various search behaviors.


Constant LDAP_SERVER_SHOW_DELETED_OID

constant string Protocols.LDAP.LDAP_SERVER_SHOW_DELETED_OID

Description

LDAP control: Microsoft AD: Control used to specify that the search results include any deleted objects that match the search filter.


Constant LDAP_SERVER_SORT_OID

constant string Protocols.LDAP.LDAP_SERVER_SORT_OID

Description

LDAP control: Microsoft AD: Control used to instruct the server to sort the search results before returning them to the client application.


Constant LDAP_SERVER_TREE_DELETE_OID

constant string Protocols.LDAP.LDAP_SERVER_TREE_DELETE_OID

Description

LDAP control: Microsoft AD: Control used to delete an entire subtree in the directory.


Constant LDAP_SERVER_VERIFY_NAME_OID

constant string Protocols.LDAP.LDAP_SERVER_VERIFY_NAME_OID

Description

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 MODIFY_ADD
Constant MODIFY_DELETE
Constant MODIFY_REPLACE

constant int Protocols.LDAP.MODIFY_ADD
constant int Protocols.LDAP.MODIFY_DELETE
constant int Protocols.LDAP.MODIFY_REPLACE

Description

Constants used in the attropval argument to Protocols.LDAP.client.modify.


Constant SCOPE_BASE
Constant SCOPE_ONE
Constant SCOPE_SUB

constant int Protocols.LDAP.SCOPE_BASE
constant int Protocols.LDAP.SCOPE_ONE
constant int Protocols.LDAP.SCOPE_SUB

Description

Constants for the search scope used with e.g. Protocols.LDAP.client.set_scope.

SCOPE_BASE

Return the object specified by the DN.

SCOPE_ONE

Return the immediate subobjects of the object specified by the DN.

SCOPE_SUB

Return the object specified by the DN and all objects below it (on any level).


Constant SEARCH_LOWER_ATTRS
Constant SEARCH_MULTIVAL_ARRAYS_ONLY
Constant SEARCH_RETURN_DECODE_ERRORS

constant int Protocols.LDAP.SEARCH_LOWER_ATTRS
constant int Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY
constant int Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS

Description

Bitfield flags given to Protocols.LDAP.client.search:

SEARCH_LOWER_ATTRS

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.

SEARCH_MULTIVAL_ARRAYS_ONLY

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.

SEARCH_RETURN_DECODE_ERRORS

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 SYNTAX_AD_CASE_IGNORE_STR
Constant SYNTAX_AD_LARGE_INT
Constant SYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR

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

Description

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 SYNTAX_ATTR_TYPE_DESCR
Constant SYNTAX_BINARY
Constant SYNTAX_BIT_STRING
Constant SYNTAX_BOOLEAN
Constant SYNTAX_CERT
Constant SYNTAX_CERT_LIST
Constant SYNTAX_CERT_PAIR
Constant SYNTAX_COUNTRY_STR
Constant SYNTAX_DN
Constant SYNTAX_DIRECTORY_STR
Constant SYNTAX_DIT_CONTENT_RULE_DESCR
Constant SYNTAX_FACSIMILE_PHONE_NUM
Constant SYNTAX_FAX
Constant SYNTAX_GENERALIZED_TIME
Constant SYNTAX_IA5_STR
Constant SYNTAX_INT
Constant SYNTAX_JPEG
Constant SYNTAX_MATCHING_RULE_DESCR
Constant SYNTAX_MATCHING_RULE_USE_DESCR
Constant SYNTAX_MHS_OR_ADDR
Constant SYNTAX_NAME_AND_OPTIONAL_UID
Constant SYNTAX_NAME_FORM_DESCR
Constant SYNTAX_NUMERIC_STRING
Constant SYNTAX_OBJECT_CLASS_DESCR
Constant SYNTAX_OID
Constant SYNTAX_OTHER_MAILBOX
Constant SYNTAX_POSTAL_ADDR
Constant SYNTAX_PRESENTATION_ADDR
Constant SYNTAX_PRINTABLE_STR
Constant SYNTAX_PHONE_NUM
Constant SYNTAX_UTC_TIME
Constant SYNTAX_LDAP_SYNTAX_DESCR
Constant SYNTAX_DIT_STRUCTURE_RULE_DESCR

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

Description

LDAP syntax: Standard syntaxes from RFC 2252.


Constant SYNTAX_CASE_EXACT_STR

constant Protocols.LDAP.SYNTAX_CASE_EXACT_STR

Description

"caseExactString" is an alias used in e.g. RFC 2079.


Constant SYNTAX_DELIVERY_METHOD
Constant SYNTAX_ENHANCED_GUIDE
Constant SYNTAX_GUIDE
Constant SYNTAX_OCTET_STR
Constant SYNTAX_TELETEX_TERMINAL_ID
Constant SYNTAX_TELETEX_NUM
Constant SYNTAX_SUPPORTED_ALGORITHM

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

Description

LDAP syntax: Standard syntaxes from RFC 2256.


Constant ldap_error_strings

constant Protocols.LDAP.ldap_error_strings

Description

Mapping from LDAP_* result codes to descriptive strings.


Constant syntax_decode_fns

constant mapping(string:function(string:string)) Protocols.LDAP.syntax_decode_fns

Description

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 syntax_encode_fns

constant mapping(string:function(string:string)) Protocols.LDAP.syntax_encode_fns

Description

Mapping containing the reverse functions from syntax_decode_fns.


Method canonicalize_dn

string canonicalize_dn(string dn, void|int strict)

Description

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.

Note

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.

Note

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.


Method encode_dn_value

string encode_dn_value(string str)

Description

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.


Method get_cached_filter

object get_cached_filter(string filter, void|int ldap_version)

Description

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.

Throws

If there's a parse error in the filter then a FilterError is thrown as from make_filter.


Method get_connection

object get_connection(string ldap_url, void|string binddn, void|string password, void|int version, void|SSL.Context ctx)

Description

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.


Method get_constant_name

string get_constant_name(mixed val)

Description

If val matches any non-integer constant in this module, its name is returned.


Method ldap_decode_string

string ldap_decode_string(string str)

Description

Decodes all \xx escapes in str.

See also

ldap_encode_string


Method ldap_encode_string

string ldap_encode_string(string str)

Description

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.

See also

ldap_decode_string, Protocols.LDAP.client.search


Method make_filter

object make_filter(string filter, void|int ldap_version)

Description

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.

Parameter 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.

Parameter 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.

Returns

An ASN1 object tree representing the filter.

Throws

FilterError is thrown if there's a syntax error in the filter.


Method num_connections

int num_connections(string ldap_url)

Description

Returns the number of currently stored connections for the given LDAP URL.


Method parse_ldap_url

mapping(string:mixed) parse_ldap_url(string ldap_url)

Description

Parses an LDAP URL and returns its fields in a mapping.

Returns

The returned mapping contains these fields:

scheme : string

The URL scheme, either "ldap" or "ldaps".

host : string

Self-explanatory.

port : int
basedn : string
attributes : array(string)

Array containing the attributes. Undefined if none was specified.

scope : int

The scope as one of the SEARCH_* constants. Undefined if none was specified.

filter : string

The search filter. Undefined if none was specified.

ext : mapping(string:string|int(1))

The extensions. Undefined if none was specified. The mapping values are 1 for extensions without values. Critical extensions are checked and the leading "!" do not remain in the mapping indices.

url : string

The original unparsed URL.

See also

get_parsed_url


Method return_connection

void return_connection(object conn)

Description

Use this to return a connection to the connection pool after you've finished using it. The connection is assumed to be working.

Note

Ensure that persistent connection settings such as the scope and the base DN are restored to the defaults

Class Protocols.LDAP.FilterError

Description

Error object thrown by make_filter for parse errors.


Constant is_ldap_filter_error

constant int Protocols.LDAP.FilterError.is_ldap_filter_error

Description

Recognition constant.

Class Protocols.LDAP.client

Description

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

inherit .protocol : protocol


Variable info

mapping Protocols.LDAP.client.info

Description

Several information about code itself and about active connection too


Method add

int add(string dn, mapping(string:array(string)) attrs)

Description

The Add Operation allows a client to request the addition of an entry into the directory

Parameter dn

The Distinguished Name of the entry to be added.

Parameter 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

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method bind

int bind()
int bind(string dn, string password)
int bind(string dn, string password, int version)

Description

Authenticates connection to the direcory.

First form uses default value previously entered in create.

Second form uses value from parameters:

Parameter dn

The distinguished name (DN) of an entry aginst which will be made authentication.

Parameter password

Password used for authentication.

Third form allows specify the version of LDAP protocol used by connection to the LDAP server.

Parameter version

The desired protocol version (current 2 or 3). Defaults to 3 if zero or left out.

Returns

Returns 1 on success, 0 otherwise.

Note

Only simple authentication type is implemented. So be warned clear text passwords are sent to the directory server.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method compare

int compare(string dn, string attr, string value)

Description

Compares an attribute value with one in the directory.

Parameter dn

The distinguished name of the entry.

Parameter attr

The type (aka name) of the attribute to compare.

Parameter value

The value to compare with. It's UTF-8 encoded automatically if the attribute syntax specifies that.

Returns

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).

Note

This function has changed arguments since version 7.6. From 7.3 to 7.6 it was effectively useless since it always returned true.

Note

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.


Method create

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)

Description

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.

Parameter 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.

Parameter context

TLS context of connection

See also

LDAP.client.bind, LDAP.client.search


Method delete

int delete(string dn)

Description

Deletes entry from the LDAP server.

Parameter dn

The distinguished name of deleted entry.

Returns

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method get_attr_type_descr

mapping(string:mixed)|zero get_attr_type_descr(string attr, v