13. Protocols

HTTP Status codes.

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

RFC 5842 section 7.1: 208 Already Reported

RFC 2518 section 10.5: 424 Failed Dependency

RFC 2518 section 10.4: 423 Locked

RFC 5842 section 7.2: 508 Loop Detected

RFC 2518 section 10.2: 207 Multi-Status

RFC 2518 section 10.1: 102 Processing

RFC 2518 section 10.6: 507 Insufficient Storage

RFC 2518 section 10.3: 422 Unprocessable Entry

RFC 3229 section 10.4.1: 226 IM Used

RFC 2324 section 2.3.2: 418 I'm a teapot

RFC 2616 section 10.2.3: 202 Accepted

RFC 2616 section 10.4.1: 400 Bad Request

RFC 2616 section 10.5.3: 502 Bad Gateway

RFC 2616 section 10.4.17: 416 Requested Range Not Satisfiable

RFC 2616 section 10.4.10: 409 Conflict

RFC 2616 section 10.1.1: 100 Continue

RFC 2616 section 10.2.2: 201 Created

RFC 8297 section 2: 103 Early Hints

RFC 2616 section 10.4.18: 417 Expectation Failed

RFC 2616 section 10.4.4: 403 Forbidden

RFC 2616 section 10.3.3: 302 Found

RFC 2616 section 10.4.11: 410 Gone

RFC 2616 section 10.5.5: 504 Gateway Timeout

RFC 6585 section 5: 431 Request Header Fields Too Large

RFC 2616 section 10.5.1: 500 Internal Server Error

RFC 7725 section 3: 451 Unavailable For Legal Reasons

RFC 2616 section 10.4.12: 411 Length Required

RFC 2616 section 10.4.6: 405 Method Not Allowed

RFC 7540 section 9.1.2: 421 Misdirected Request

RFC 2616 section 10.3.2: 301 Moved Permanently

RFC 2616 section 10.3.1: 300 Multiple Choices

RFC 6585 section 6: 511 Network Authentication Required

RFC 2616 section 10.2.4: 203 Non-Authorative Information

RFC 2616 section 10.4.7: 406 Not Acceptable

RFC 2774 section 7: 510 Not Extended (obsolete)

RFC 2616 section 10.4.5: 404 Not Found

RFC 2616 section 10.5.2: 501 Not Implemented

RFC 2616 section 10.3.5: 304 Not Modified

RFC 2616 section 10.2.5: 204 No Content

RFC 2616 section 10.2.1: 200 OK

RFC 2616 section 10.2.7: 206 Partial Content

RFC 2616 section 10.4.3: 402 Payment Required

RFC 7538 section 3: 308 Permanent Redirect

RFC 2616 section 10.4.13: 412 Precondition Failed

RFC 6585 section 3: 428 Precondition required

RFC 2616 section 10.4.8: 407 Proxy Authentication Required

RFC 2616 section 10.4.14: 413 Request Entity Too Large

RFC 2616 section 10.2.6: 205 Reset Content

RFC 2616 section 10.3.4: 303 See Other

RFC 2616 section 10.1.2: 101 Switching protocols

RFC 2616 section 10.3.8: 307 Temporary Redirect

RFC 2616 section 10.4.9: 408 Request Timeout

RFC 6585 section 4: 429 Too Many Requests

RFC 2616 section 10.4.2: 401 Unauthorized

RFC 2616 section 10.5.4: 503 Service Unavailable

RFC 2616 section 10.4.16: 415 Unsupported Media Type

RFC 2616 section 10.5.6: 505 HTTP Version Not Supported

RFC 2616 section 10.4.15: 414 Request-URI Too Long

RFC 2616 section 10.3.6: 305 Use Proxy

RFC 2295 section 8.1: 506 Variant Also Negotiates

RFC 8470 section 5.2: 425 Too Early

RFC 2817 section 4.2: 426 Upgrade Required

Open and execute an HTTP query.

Wait for connection to complete.

Returns 1 on successfull connection, 0 on failure.

Fetch all data in background.

timed_async_fetch(), async_request(), set_callbacks()

Setup and run an asynchronous request, otherwise similar to thread_request().

request_ok(Protocols.HTTP.Query httpquery,...extra args) will be called when connection is complete, and headers are parsed.

request_fail(Protocols.HTTP.Query httpquery,...extra args) is called if the connection fails.

Returns the called object

The header mapping ORed with the following mapping.

Gives back the answer as a string.

Close all associated file descriptors.

Gives back the data as a string.

Gives back a pseudo-file object, with the methods read() and close(). This could be used to copy the file to disc at a proper tempo.

datafile() doesn't give the complete request, just the data.

file()

Gives back the number of downloaded bytes.

Errno copied from the connection or simulated for async operations.

In Pike 7.8 and earlier hardcoded Linux values were used in async operations, 110 instead of System.ETIMEDOUT and 113 instead of System.EHOSTUNREACH.

Gives back a pseudo-file object, with the methods read() and close(). This could be used to copy the file to disc at a proper tempo.

newheaders, removeheaders is applied as: (oldheaders|newheaders))-removeheaders Make sure all new and remove-header indices are lower case.

datafile()

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

Connected host and port.

Used to detect whether keep-alive can be used.

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

Tells if the connection is successfull.

Protocol string, ie "HTTP/1.0".

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

Create a new query object and begin the query.

The query is executed in a background thread; call `() in the object to wait for the request to complete.

query is the first line sent to the HTTP server; for instance "GET /index.html HTTP/1.1".

headers will be encoded and sent after the first line, and data will be sent after the headers.

Returns the called object.

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

async_fetch(), async_request(), set_callbacks()

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

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

data

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.

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.

Default HTTP headers.

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.

The number of redirects to follow, if any. This is the default to the created Request objects.

A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.

Default is 20 redirects. A negative number will mean infinity.

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

Request.follow_redirects

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.

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.

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

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

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

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

Maximum total number of connections. Limits only async requests, and the number of kept-alive connections (live connections + kept-alive connections <= this number) Defaults to 50 connections.

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.

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.

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

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.

Fast HTTP header parser.

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

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

Makes a time notification suitable for the HTTP protocol.

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

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

Decode a HTTP date to seconds since 1970 (UTC)

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

Decodes an URL-encoded query into a mapping.

Alert packet.

Based on the base Packet.

Client-side connection state.

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

Initialize a new ClientConnection.

Context to use.

Optional host name of the server.

Optional Session to resume.

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.

Renegotiate the connection (client initiated).

Sends a client_hello to force a new round of handshaking.

SSL.Connection keeps the state relevant for a single SSL connection. This includes the Context object (which doesn't change), various buffers, the Session object (reused or created as appropriate), and pending read and write states being negotiated.

Each connection will have two sets of read and write 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.

This class should never be created directly, instead one of the classes that inherits it should be used (ie either ClientConnection or ServerConnection) depending on whether this is to be a client-side or server-side connection. These in turn are typically created by File()->create().

ClientConnection, ServerConnection, Context, Session, File, State

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

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

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

Initialize the connection state.

The context for the connection.

Returns a string describing the current connection state.

Main receive handler.

String of data received from the peer.

Returns one of:

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

Handle an alert received from the peer.

Alert level; either ALERT_warning or ALERT_fatal.

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

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.

The active Cipher.KeyExchange (if any).

Returns the number of packets queued for writing.

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

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

Initiate close.

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

Renegotiate the connection.

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.

Number of application data bytes sent by us.

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.

Bitfield with the current connection state.

Extracts data from the packet queues. Returns a string of data to be written, "" if there are no pending packets, 1 of the connection is being closed politely, and -1 if the connection died unexpectedly.

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

query_write_queue_size(), send_streaming_data().

Keeps the state that is shared by all SSL-connections on a client, or for one port on a server. It includes policy configuration, the server or client certificate(s), the corresponding private key(s), etc. It also includes the session cache.

The defaults are usually suitable for a client, but for a server some configuration is necessary.

Typical use is to:

• Call add_cert() with the certificates belonging to the server or client. Note that clients often don't have or need any certificates, and also that certificate-less server operation is possible, albeit discouraged and not enabled by default.

  Suitable self-signed certificates can be created with Standards.X509.make_selfsigned_certificate().

• Optionally call get_suites() to get a set of cipher_suites to assign to preferred_suites. This is only needed if the default set of suites from get_suites(128, 1) isn't satisfactory.

The initialized Context object is then passed to File()->create() or used as is embedded in Port.

File, Port, Standards.X509

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.

Private key matching the first certificate in certs.

Supported key types are currently:

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

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

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.

An alternative is to send an initialized CertificatePair.

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

find_cert()

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

Alert factory.

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

Connection which caused the alert.

Level of alert.

Description code for the alert.

Optional log message for the alert.

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

Policy for client authentication. One of SSL.Constants.AUTHLEVEL_none, SSL.Constants.AUTHLEVEL_ask and SSL.Constants.AUTHLEVEL_require.

Getting

The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

Compatibility, don't use.

Replaced by find_cert.

`rsa, find_cert()

Setting

The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

Compatibility, don't use.

Replaced by find_cert.

`rsa, find_cert()

Getting

The client's certificate, or a chain of X509.v3 certificates, with the client's certificate first and root certificate last.

Compatibility, don't use.

Replaced by find_cert.

`rsa, find_cert()

Setting

The client's certificate, or a chain of X509.v3 certificates, with the client's certificate first and root certificate last.

Compatibility, don't use.

Replaced by find_cert.

`rsa, find_cert()

Getting

The clients RSA private key.

Compatibility, don't use.

Replaced by find_cert.

`certificates, find_cert()

Setting

The clients RSA private key.

Compatibility, don't use.

Replaced by find_cert.

`certificates, find_cert()

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.

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

Allow additional suites.

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

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

get_suites()

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

The default implementation just calls lookup_session().

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

encode_ticket(), lookup_session()

Supported DH groups for DHE key exchanges, in order of preference. Defaults to FFDHE-2048.

Set preferred_suites to DSS based methods.

Minimum acceptable key length in bits.

rsa_mode(), filter_weak_suites()

Replaced by get_suites.

Getting

Compatibility.

Replaced by find_cert.

Setting

Compatibility.

Replaced by find_cert.

Supported elliptical curve cipher curves in order of preference.

Generate a session ticket for a session.

The default implementation just generates a random ticket and calls record_session() to store it.

Over-ride this function (and decode_ticket()) to implement server-side state-less session resumption.

If the context signals that it does offer tickets via offers_tickets(), this function must offer an encoded ticket for the session as the connection may have signalled to the client that a ticket will be offered. However, tickets are not guaranteed to be actually usable, so if you cannot offer a ticket when you must, "INVALID" might be an option...

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

Attempt to enable encrypt-then-mac mode.

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

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

Look up a suitable set of certificates for the specified issuer. UNDEFIEND if no certificate was found.

Get the list of allowed authorities. See set_authorities.

Returns a list of all server certificates added with add_cert.

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

signature_algorithms

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

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

Level of protection for the key exchange.

Multiset of ciphers that are NOT to be used.

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

Multiset of hash algoriths that are NOT to be used.

Multiset of cipher modes that are NOT to be used.

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

Get the list of trusted issuers. See set_trusted_issuers.

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.

Temporary, non-certified, private keys, used for RSA key exchange in export mode. They are used as follows:

short_rsa is a 512-bit RSA key used for the SSL 3.0 and TLS 1.0 export cipher suites.

long_rsa is a 1024-bit RSA key to be used for the RSA_EXPORT1024 suites from draft-ietf-tls-56-bit-ciphersuites-01.txt.

They have associated counters short_rsa_counter and long_rsa_counter, which are decremented each time the keys are used.

When the counters reach zero, the corresponding RSA key is cleared, and a new generated on demand at which time the counter is reset.

Counters for export RSA keys.

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

Maximum number of sessions to keep in the cache.

The maximum supported protocol version.

Defaults to PROTOCOL_TLS_MAX.

This value should not be less than min_version.

The minimum supported protocol version.

Defaults to PROTOCOL_TLS_1_0.

This value should not be greater than max_version.

Create a new session.

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

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

For client authentication. Used only if auth_level is AUTH_ask or AUTH_require.

Lists the supported compression algorithms in order of preference.

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

Cipher suites we want to support, in order of preference, best first.

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

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 Crypto.Random.random_string.

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

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.

Getting

The servers default private RSA key.

Compatibility, don't use.

Replaced by find_cert.

`certificates, find_cert()

Setting

The servers default private RSA key.

Compatibility, don't use.

Replaced by find_cert.

`certificates, find_cert()

Set preferred_suites to RSA based methods.

Minimum acceptable key length in bits.

dhe_dss_mode(), filter_weak_suites()

Replaced by get_suites.

Sessions are removed from the cache when they are older than this limit (in seconds). Sessions are also removed from the cache if a connection using the session dies unexpectedly.

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.

Sets the list of trusted certificate 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.

The set of <hash, signature> combinations to use by us.

Only used with TLS 1.2 and later.

Defaults to all combinations supported by Pike except for MD5.

This list is typically filtered by get_signature_algorithms() to get rid of combinations not supported by the runtime.

According to RFC 5246 7.4.2 all certificates needs to be signed by any of the supported signature algorithms. To be forward compatible this list needs to be limited to the combinations that have existing PKCS identifiers.

get_signature_algorithms()

Sort a set of cipher suites according to our preferences.

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

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

Non-zero to enable caching of sessions

Mapping of supported verifier algorithms to hash implementation.

Standards.X509.get_algorithms()

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

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.

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

Configure as server and set up the connection.

Any data that has already been read from the stream. This is typically used with protocols that use START TLS or similar, where there's a risk that "too much" data (ie part of the TLS ClientHello) has been read from the stream before deciding that the connection is to enter TLS-mode.

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

connect()

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

Read only

Run one pass of the backend.

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

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

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.

I/O errors are normally thrown, but that can be turned off with dont_throw. In that case errno is set instead and 0 is returned. 1 is always returned otherwise. It's not an error to close an already closed connection.

If a clean close is requested in nonblocking mode then the stream is most likely not closed right away, and the backend is then still needed for a while afterwards to exchange the close packets. is_open returns 2 in that time window.

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

If a clean close is requested and data following the close message is received at the same time, then this object will read it and has no way to undo that. That data can be retrieved with read afterwards.

shutdown

Configure as client and set up the connection.

Optional name of the server that we are connected to.

Session to resume (if any).

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

Throws an error if a connection already has been established.

accept()

Create an SSL connection over an open stream.

Open socket or pipe to create the connection over.

The SSL context.

The backend used by stream is taken over and restored after the connection is closed (see close and shutdown). The callbacks and id in stream are overwritten.

The operation mode defaults to nonblocking mode.

accept(), connect()

Try to close down the connection properly since it's customary to close files just by dropping them. No guarantee can be made that the close packet gets sent successfully though, because we can't risk blocking I/O here. You should call close explicitly.

close

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

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

Returns peer certificate information, if any.

Returns the peer certificate chain, if any.

Check whether any callbacks may need to be called.

Always run via the real_backend.

schedule_poll()

Returns nonzero if the stream currently is open, zero otherwise.

This function does nonblocking I/O to check for a close packet in the input buffer.

If a clean close has been requested in nonblocking mode, then 2 is returned until the close packet exchanged has been completed.

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

Set the linger time on close().

Returns the current accept callback.

set_accept_callback

Returns the address and port of the connection.

See Stdio.File.query_address for details.

Stdio.File.query_address

Returns the current alert callback.

set_alert_callback

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

Context.advertised_protocols

Return the backend used for the file callbacks.

set_backend

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

Returns an array with two elements:

set_buffer_mode()

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

set_callbacks, set_nonblocking

Returns the current close callback.

set_close_callback, set_nonblocking, query_callbacks

Return the SSL connection object.

This returns the low-level SSL.connection object.

Return the SSL context object.

Returns the file descriptor number associated with this object.

Returns the currently set id.

set_id

Returns the current read callback.

set_read_callback, set_nonblocking, query_callbacks

Return the underlying stream.

Avoid any temptation to do destruct(file_obj->query_stream()). That almost certainly creates more problems than it solves.

You probably want to use shutdown.

shutdown

Return the currently active cipher suite.

Get the timeout for blocking operations.

set_timeout()

Return the currently active SSL/TLS version.

Returns the current write callback.

set_write_callback, set_nonblocking, query_callbacks

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

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

write

Renegotiate the connection by starting a new handshake. Note that the accept callback will be called again when the handshake is finished.

Returns zero if there are any I/O errors. errno() will give the details.

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

Data in the write queue in nonblocking mode is not properly written before resetting the connection. Do a blocking write("") first to avoid problems with that.

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

internal_poll()

Install a function that will be called when the handshake is finished and the connection is ready for use.

The callback function will be called with the File object and the additional id arguments (set with set_id).

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

set_nonblocking, set_callbacks, query_accept_callback, query_callbacks

Install a function that will be called when an alert packet is about to be sent. It doesn't affect the callback mode - it's called both from backends and from within normal function calls like read and write.

This callback can be used to implement fallback to other protocols when used on the server side together with shutdown().

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

This callback is not cleared by set_blocking, or settable by set_callbacks or set_nonblocking. It is also not part of the set returned by query_callbacks.

query_alert_callback

Set the backend used for the file callbacks.

query_backend

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

There might be some data still waiting to be written to the stream. That will be written in the next blocking call, regardless what it is.

This function doesn't solve the case when the connection is used nonblocking in some backend thread and another thread switches it to blocking and starts using it. To solve that, put a call out in the backend from the other thread that switches it to blocking, and then wait until that call out has run.

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

set_nonblocking, set_blocking_keep_callbacks, set_nonblocking_keep_callbacks

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

set_blocking, set_nonblocking

Toggle the file to Buffer mode.

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

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

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

query_buffer_mode()

Installs all the specified callbacks at once. Use UNDEFINED to keep the current setting for a callback.

Like set_nonblocking, the callbacks are installed atomically. As opposed to set_nonblocking, this function does not do anything with the stream, and it doesn't even have to be open.

read_oob and write_oob are currently ignored.

set_read_callback, set_write_callback, set_close_callback, set_accept_callback, query_callbacks

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

query_close_callback, set_nonblocking, query_callbacks

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

query_id

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

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

read_oob and write_oob are currently ignored.

set_callbacks, query_callbacks, set_nonblocking_keep_callbacks, set_blocking

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

set_nonblocking, set_blocking, set_blocking_keep_callbacks

Install a function to be called when data is available.

query_read_callback, set_nonblocking, query_callbacks

Set timeout for blocking operations.

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

By default there is no timeout.

query_timeout()

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

query_write_callback, set_nonblocking, query_callbacks