acl-socket operators (original) (raw)

accept-connection

Generic function, acl-socket package

Arguments: sock &key (wait t)

If wait is true, waits for there to be a connection to this socket and returns a new stream object that can be used to do I/O to the connected socket. If wait is nil and there is no connection pending it returns nil immediately; if a connection is pending, connects and returns a new stream object that can be used to do I/O to the connected socket.

See <socket.html> for general information on sockets in Allegro CL.

configure-dns

Function, acl-socket package

Arguments: &key nameserver search domain auto

In order to work, the DNS utility needs to know the IP address of at least one nameserver willing to respond to recursive queries (that is, to do the work of the query if it doesn't know the answer). This function is used to specify the nameserver addresses. It can also specify other optional information. When DNS is configured, the variable *dns-configured* is set to true.

The arguments:

We would like to be able to compute this information automatically in every situation. Currently we can handle Unix machines that specify this information in a file called /etc/resolv.conf, and we try to handle all versions of Windows (but see the note under the heading Automatic DNS configuation on Windows below).

When dns-query is called, it checks to see if configure-dns has been called since lisp started, and if not it calls configure-dns with :auto t. If this doesn't work it means that you need to call configure-dns with the appropriate information before you call dns-query on this machine.

Automatic DNS configuation on Windows

On Windows the information we need to automatically configure this module is found in the Windows registry. Unfortunately the information we need is in a different place in each on the various Windows configurations we tested (such as Win NT 4 and Win2000, each with a fixed IP address or using DCHP to configure the IP address). Therefore it's likely that information will move around again in future versions of Windows. Furthermore sometimes we encounter stale information in the registry (for example, a laptop computer that used to be on a network but isn't at the moment may hold the last known nameserver information in the registry even though those nameservers are unreachable). Therefore, if you wish to make use of the Allegro CL DNS facility, you should be prepared to manually configure-dns on machines (by calling this function with auto nil and filling in the necessary information) when auto configuration fails.

See <dns.html> for information on the domain naming system utility in Allegro CL and see <socket.html> for general information on sockets in Allegro CL.

dns-ipaddr-to-hostname

Arguments: name &rest rest

Function, acl-socket package

This function calls dns-query passing a type value of :ptr. This is the functional equivalent of ipaddr-to-hostname when you ignore the extra values returned.

See also *dns-mode*.

See <dns.html> for information on the domain naming system utility in Allegro CL and see <socket.html> for general information on sockets in Allegro CL.

dns-lookup-hostname

Function, acl-socket package

Arguments: name &rest rest

This function calls dns-query passing a type value of :a. This is the functional equivalent of lookup-hostname if you ignore the extra values returned. It has one additional feature, which is that if the query on name doesn't return any IP addresses, and if name doesn't contain any periods (that is, it's not a fully qualified domain name), then we try appending the values in *domain-search-list* to the name and redoing the query. Because the query can be done once for the given name and once for each name in the *domain-search-list*, this function can take longer to return than dns-query when nameservers aren't responsive.

Limitations

  1. This function does not check a local file (often /etc/hosts) for name to IP address mappings. Thus there are cases where dns-lookup-hostname won't act just like lookup-hostname.
  2. If a nameserver response is too large to fit in 512 bytes and is thus truncated, this function does not switch from UDP to TCP and retry the query.

See also *dns-mode*.

See <dns.html> for information on the domain naming system utility in Allegro CL and see <socket.html> for general information on sockets in Allegro CL.

dns-nameserver-ipaddr

Function, acl-socket package

Arguments: dns-nameserver-object

Accessor for the ipaddr slot of dns-nameserver-object. See dns-nameserver.

See <dns.html>.

dns-nameserver-name

Function, acl-socket package

Arguments: dns-nameserver-object

Accessor for the name slot of dns-nameserver-object. See dns-nameserver.

See <dns.html>.

dns-nameserver-received

Arguments: dns-nameserver-object

Accessor for the received slot of dns-nameserver-object. See dns-nameserver.

See <dns.html>.

dns-nameserver-sent

Function, acl-socket package

Arguments: dns-nameserver-object

Accessor for the sent slot of dns-nameserver-object. See dns-nameserver.

See <dns.html>.

dns-query

Function, acl-socket package

Arguments: name &key type nameserver repeat timeout queue decode search ignore-cache

The arguments are:

Name Default What
name Depending on the value of the type argument, this is either a string or an integer IP address.
type :a The type of dns query to make. :a means determine the ip address(es) for the given name. (_name_should be a string.) :ptr means determine the hostname for a given IP address. (_name_should be an integer IP address, a string containing a dotted IP address, or an IPv6 address. :mx means determine if there is another machine that email for _name_should be directed. (_name_should be a string.):srv means get SRV records for a domain. name should be a string. See SRV queries in <dns.html> :txt means get all TXT records associated with name. The answer is a list containing one or more strings (TXT records can be composed of multiple strings), or nil if there are no TXT records. If there is more than one TXT record, then the third return value will contain a list of the remaining answers. :aaaa means look up IPv6 adresses. :any means return all information about the first argument. decode should be specified nil (its default is t) when type is :any.
nameserver nil If specified this can be an IP address or a list of IP addresses. This overrides the configured list of nameservers for just this query.
repeat 5 How many times to try to get an answer to this query before giving up.
timeout 5 How long to wait until we assume that a try has failed and we then try again or give up. The value should be an integer indicating a number of seconds.
queue t If true then handle this request using the background process that is backed up by a cache of recent answers. If this is nil then a request will always be sent to the nameserver
decode t The nameserver returns a structure of many fields. If true then dns-querywill examine the returned structures and will return only the information requested by the query. If this is nil then the result of dns-query will be the actual information returned by the nameserver. This response is a dns-response object. See that page for information on this raw object. Please specify nil when you specify :anyas the value of type.
search nil When specified true,*dns-domain* and*domain-search-list* will be used to fully qualify the name argument before doing the query. See below for details on how the search is conducted.
ignore-cache nil Allegro CL DNS caches positive and negative responses for at least the time-to-live specified in the respones. If dns-queryis called again with the same request before the time-to-live expires, the cached information will be returned immediately. If ignore-cache is true, then the cached value will be ignored and a DNS lookup will occur.

If either nameserver is non-nil or decode is nil, then queue will be set to nil regardless of the value of queue supplied. This ensures that a fresh query is sent to the nameserver.

Where an IP address is a valid argument, it can be specified as either an integer or as a string such as "192.132.95.1" or "127.1". Ipv6 address structures and IPv6 colon hex strings are allowed too.

Search details

When the search keyword argument is specified true, and so *dns-domain* and *domain-search-list* are used to fully qualify the name argument before doing the query, the search steps are as follows:

  1. The search list comprises *dns-domain* followed by *domain-search-list*. If the given name ends in a period (e.g. www.cnn.com.) then that is an absolute name. Only that name is checked and the search list is not used.
  2. If the given name has a period in it, but that period is not at the end (e.g. www.cnn.com) then that name is checked first.
  3. Finally for the given name N and for each name S in the search list a new name is constructed by concatenating the strings with a period in between (e.g N.S). That constructed name is used in the query. If the query returns a response with :no-such-domain then the next item in the search list is used.

Thus the first response from the search (with a positive or negative valid time, which is the second returned value) is returned as the first returned value, but illegal domains in the search list are ignored.

Return values

There are four return values from dns-query.

  1. the primary answer
  2. the amount of time that that answer is valid (in seconds) This can be a negative number (see the discussion in the The DNS API section of <dns.html> for why).
  3. a list of other answers
  4. a list of the flags returned by the dns server that replied to the query

There are examples of using dns-query in the subsections of The DNS API in <dns.html>.

See <dns.html> for information on the domain naming system utility in Allegro CL and see <socket.html> for general information on sockets in Allegro CL.

dns-response-additional

Function, acl-socket package

Arguments: dns-response-object

Accessor for the additional slot of dns-response-object. See dns-response.

See <dns.html>.

dns-response-answer

Function, acl-socket package

Arguments: dns-response-object

Accessor for the answer slot of dns-response-object. See dns-response.

See <dns.html>.

Function, acl-socket package

Arguments: dns-response-object

Accessor for the authority slot of dns-response-object. See dns-response.

See <dns.html>.

dns-response-flags

Function, acl-socket package

Arguments: dns-response-object

Accessor for the flags slot of dns-response-object. See dns-response.

See <dns.html>.

dns-response-flags-value

Function, acl-socket package

Arguments: dns-response-object

Accessor for the flags-value slot of dns-response-object. See dns-response.

See <dns.html>.

dns-response-id

Function, acl-socket package

Arguments: dns-response-object

Accessor for the id slot of dns-response-object. See dns-response.

See <dns.html>.

dns-rr-answer

Function, acl-socket package

Arguments: dns-rr-object

Accessor for the answer slot of dns-rr-object. See dns-rr.

See <dns.html>.

dns-rr-class

Function, acl-socket package

Arguments: dns-rr-object

Accessor for the class slot of dns-rr-object. See dns-rr.

See <dns.html>.

dns-rr-name

Function, acl-socket package

Arguments: dns-rr-object

Accessor for the name slot of dns-rr-object. See dns-rr.

See <dns.html>.

dns-rr-time-to-live

Function, acl-socket package

Arguments: dns-rr-object

Accessor for the time-to-live slot of dns-rr-object. See dns-rr.

See <dns.html>.

dns-rr-type

Function, acl-socket package

Arguments: dns-rr-object

Accessor for the type slot of dns-rr-object. See dns-rr.

See <dns.html>.

dotted-address-p

Function, acl-socket package

Arguments: object

This function was added in an update released around June 20, 2006.

Returns true if the argument is a string in dotted IP address form.

See <socket.html>, particularly the Host naming section, where the dotted form is described with examples.

dotted-to-ipaddr

Function, acl-socket package

Arguments: dotted &key errorp

If dotted is a string like "192.132.95.84" (or one of the extensions to this format), this function converts the string to an unsigned 32-bit IP address. If there are any invalid characters in the string then an error will be signaled unless the value of errorp keyword is nil, in which case nil is returned.

dotted-to-ipaddr supports IPv6 "colon hex" address notation, including the %scopeid extension. The scope id can be an interface number or interface name. dotted-to-ipaddr supports IPv4-mapped IPv6 address notation (::ffff:w.x.y.z).

IPv6 colon hex notation examples:

"2001:5c0:0:2::24"              ;; 6bone.net
"fe80::209:5bff:fe8e:61c1"      ;; a link-local address
"fe80::209:5bff:fe8e:61c1%eth0" ;; a link-local address with scope-id
"fe80::209:5bff:fe8e:61c1%2"    ;; a link-local address with numeric scope-id
"::"                            ;; unspecific/wildcard address
"::1"                           ;; loopback
"::ffff:192.168.0.1"            ;; IPv4-mapped IPv6 address

See also get-ip-interfaces.

See <socket.html> for general information on sockets in Allegro CL.

ftp-transfer-file

Function, acl-socket package

Arguments: from-host from-port from-file (from-user "anonymous") (from-password "[email protected]") to-host to-port to-file (to-user "anonymous") (to-password "[email protected]") (mode :binary) debug*

This function transfers the file from-file from from-port on the from-host machine to to-file via the to-port on the to-host machine. (from-port and to-port have standard defaults and it is typical not to provide values for them. The arguments are there to allow specification of servers on non-default ports.) The files on the different machines can have different names. Users and passwords should be strings.

mode can be :binary (the default), or :text. :text mode lines end with cr-lf (the internet standard).

If debug is a stream (or t) is given, this function will print the ftp interaction to that stream.

get-ip-interfaces

Function, acl-socket package

Arguments:

This function returns a list of conses. The car of each cons is the interface id. The cdr of each cons is the name of the interface.

Either the numeric interface id or the name can be used in the %scopid extension of dotted (colon hex) IPv6 addresses.

Not supported on HP/UX or Mac OS X 64-bit

This function is not supported on HP/UX. It also does not work (it typically signals an error when called) on Mac OS X 64-bit. (The problem on the Mac 64-bit seems to result from an Operating System bug, so it may at some later time be fixed by an OS update. This function does work on Mac OS X 32-bit.)

See also: dotted-to-ipaddr

See <socket.html>.

get-ssl-peer-certificate

Generic Function, acl-socket package

Arguments: stream

get-ssl-peer-certificate returns an x509-certificate object representing the certificate that the peer supplied. If the peer did not supply a certificate, nil is returned. The x509-certificate is created the first time this function is called on a stream.

stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and make-ssl-client-stream).

Note that get-ssl-peer-certificate automatically calls ssl-do-handshake if SSL handshake has not already occurred.

See <socket.html>.

get-ssl-verify-result

Generic Function, acl-socket package

Arguments: stream

get-ssl-verify-result returns information about the success or failure of peer certificate verification.

stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and make-ssl-client-stream).

get-ssl-verify-result returns two values. The first value is a numeric code indicating the status of verification. 0 indicates successful verification. The second value is a string with a text representation of the status.

Note, if SSL handshake has not yet been performed, or if the peer did not provide a certificate, this function returns an OK status.

The possible return values are shown in the following information copied from the OpenSSL documentation. The numeric value (0, 2, 3, 4, etc.) is the first returned value and the string is the second. The string does not include the capitalized and underscored descriptor. Additional information not included in the returned string is included in this list. Thus, when the peer certificate verification is sucessful, 0 and "ok" are returned. X509_V_OK and 'the operation was successful.' are not part of the string.

See <socket.html>.

initialize-socket

Function, acl-socket package

Arguments: &key menup

On Unix systems this is unnecessary and always does nothing. On Windows, if the socket system has already been initialized then this does nothing. If it hasn't, then the socket system is initialized. If, on Windows, this function hasn't been called before the first network operation, then it will be called automatically.

See <socket.html> for general information on sockets in Allegro CL.

ipaddr-equalp

Function, acl-socket package

Arguments: addr1 addr2 &key compare-scope-id

addr1 and addr2 should be ip addresses in some form (either dotted, 32-bit unsigned, or ipv6-address structure). This function returns true when the addresses match.

When comparing IPv6 addresses, normally the scope id is not used in the comparison. To include the scope id in the comparison, specify a non-nil value for the compare-scope-id keyword argument.

See <socket.html>.

ipaddr-to-dotted

Function, acl-socket package

Arguments: addr &key values

Convert a 32-bit unsigned IP address, ipaddr, to a string in dotted form. The value is always converted to the format "_a.b.c.d_", even if it is a class A or B address. If values is true, then return a, b, c and d as multiple values instead of a single string.

This function works on IPv6 address structures as well. If the IPv6 address structure's scope-id field is non-zero, then the dotted result will have the %scopeid extension. When an IPv6 address is specified, then the values keyword argument has no effect.

See <socket.html> for general information on sockets in Allegro CL.

ipaddr-to-hostname

Function, acl-socket package

Arguments: ipaddr &key ignore-cache

ipaddr should be a 32-bit unsigned integer (representing an IPv4 address), an ipv6-address stucture, or a dotted IP address string. This function returns, as a string, the hostname of the machine with the given address.

if the ignore-cache argument is specified true, then the lookup will be done by querying the operating system ipaddr lookup libraries rather than using a value that Lisp has cached. The result of the lookup is still cached, however.

See also *dns-mode*.

See <socket.html> for general information on sockets in Allegro CL.

ipaddrp

Function, acl-socket package

Arguments: object

Returns true if the argument is an IP address (either an integer or an ipv6-address structure).

See <socket.html>.

ipv6

Generic Function, acl-socket package

Arguments: internet-socket

Returns true if the argument, which must be an internet socket, is a IPv6 socket. See make-socket.

See <socket.html>.

ipv6-address-p

Function, acl-socket package

Arguments: object

Returns true if the argument is an IPv6 address structure.

See <socket.html>.

local-filename

Generic Function, acl-socket package

Arguments: af-file

Returns the local filename of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

local-host

Generic Function, acl-socket package

Arguments: af-internet

Returns an IP address. You can use ipaddr-to-dotted or ipaddr-to-hostname to make a more readable version of this value if you plan to print it out.

See <socket.html> for general information on sockets in Allegro CL.

local-port

Generic Function, acl-socket package

Arguments: af-internet

Returns the local port of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

lookup-hostname

Function, acl-socket package

Arguments: host &key ignore-cache ipv6 all

host should be a string naming a host, a 32-bit IP address, a string in dotted form, or an IPv6 address. This function returns the 32-bit IP address or an IPv6 address structure for the host. An error is signaled if the host can not be found. See the documentation for *dns-mode* for information on the manner in which name resolution occurs.

To enhance performance, lookup-hostname caches answers to queries and reuses those answers for subsequent lookups of the same name. If the IP address associated with a given hostname has changed since the information was cached, lookup-hostname may return out-of-date information.

If the ignore-cache argument is specified true, then the lookup will be done by querying the operating system libraries rather than using a value that Lisp has cached. The result of the lookup is still cached, however.

The ipv6 keyword argument was added with IPv6 support. ipv6 defaults to the value of *ipv6*. If nil, only IPv4 addresses will be returned. If :ipv6, then only IPv6 addresses will be returned. If t, then IPv6 addresses (if any) are returned in preference of IPv4 addresses. If ipv6 and all are both t, IPv6 addresses will be before IPv4 addresses in the returned list.

The all keyword argument was added with IPv6 support. If all is true, this function will return a list of all records.

See also *dns-mode*.

See <socket.html> for general information on sockets in Allegro CL.

lookup-port

Function, acl-socket package

Arguments: port protocol

A port number is a 16-bit unsigned number (except port 0 is not used). Certain commonly used ports on machines are given symbolic names. The mapping between name and port number is kept in a file in the system area of the machine (often /etc on Unix and the Windows system directory on MS Windows). Given a symbolic name as the value of port and a protocol (either "tcp" or "udp"), lookup-port returns the associated port number (or signals an error if such a port doesn't exist). The reason that the protocol type is supplied is that the port N for protocol "tcp" is distinct from port N for protocol "udp".

See <socket.html> for general information on sockets in Allegro CL.

make-socket

Function, acl-socket package

Arguments: &rest args &key type format connect address-family eol ipv6 scope-id tcp-md5-sig-key tcp-md5-sig-key-ef

Create and return a socket object with characteristics specified by the arguments. make-socket checks whether multiprocessing has been started and starts it if it hasn't been. The socket object will be an instance of a particular class (see socket for a list of classes). The class is determined from the values supplied to the keyword arguments.

The keywords arguments have the following possible values (with the default value given first):

All of the various kinds of sockets are created with make-socket, which determines the kind of socket you want based on the values of the type, format, connect, and address-family arguments. The value of the address-family keyword can't be :file on Windows because Windows does not support it.

The following socket options for an existing socket can be modified with set-socket-options. The options that can be set are reuse-address, broadcast, keepalive, nodelay, oob-inline, receive-buffer-size, and send-buffer-size. Not all options are relevant for all types of sockets. Look at the man pages for your specific OS to see what options are supported for particular sockets. Each socket type below specifies additional keyword arguments accepted by make-socket.

Additional options are tcp-keepalive-idle-time, tcp-keepalive-probe-interval, and tcp-keepalive-max-probes. These correspond to the C constants TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT available on some (but not all) operating systems. These can only be set with set-socket-options. See the description of that function for more information.

make-socket calls a specialized socket creation function and that function looks for other keywords designed just for that socket type (some naming options that can be modified with set-socket-options). We describe next the extra keywords that are permitted for given values of address-family and type:

See <socket.html> for general information on sockets.

make-ssl-client-context

Function, acl-socket package

Arguments: &key method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file prefer-server-cipher-order

This function creates and returns an SSL context object (an instance of the class excl::ssl-context) suitable for use as the value of the context keyword argument to make-ssl-client-stream.

The context has values for all relevant arguments. For the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order, specifying a value in a call to make-ssl-client-stream which is also passed a context object as the value of the context argument causes the associated argument value to be local to that connection (i.e. the specified argument value overrides the value in the context object). The value for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check cannot be overridden when a context is provided. It is an error to supply a context and values for any of those arguments.

The keyword arguments

See <socket.html> for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.

make-ssl-client-stream

Function, acl-socket package

Arguments: socket &key context method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file server-name

You must have the OpenSSL libraries installed for this facility to work. Note that shared library versions of the OpenSSL libraries (required by Allegro CL) are not available on all platforms. The SSL functionality is in the ssl module. To ensure it is loaded, evaluate (require :ssl). Calling this function automatically loads the module.

This function creates and returns a new SSL server socket stream that communicates via SSL via the given socket. Once this function is called and an SSL socket stream is returned, no I/O calls should be done directly to socket. Note that closing the SSL socket stream will result in the original socket file descriptor being closed as well. Therefore, the idiomatic way to establish an SSL server socket stream is:

;; SOCK is already a socket:
(setf sock (make-ssl-server-stream sock ...))

Unless ssl-do-handshake is called, the secure connection isn't negotiated until the first byte is sent through the SSL socket stream to the underlying stream (and this will usually occur when the first force-output is done to the SSL socket stream).

When that first write is done a negotiation process is begun that involves reads and writes. This negotiation process will not occur if the SSL socket on the other end of the connection is not sitting waiting for data to arrive. Thus if you create two connected sockets in a single Lisp process, and make one the client and the other the server, and then write to the client side the Lisp will hang since the server side socket isn't being read. You can make this work if you use the Lisp multiprocessing facility (see <multiprocessing.html>) to cause the server socket to be read at the same time that the write to the client socket is being done.

The context keyword argument takes an SSL context object as a value. Such objects contain relevant information about the client stream being created. The function make-ssl-client-context create a context suitable for a client stream.

Note: if you supply an SSL context object as the value of context, you can specify values for the arguments method, ciphers, ciphersuites, verify, and max-depth in the call to this function. Doing so causes the associated argument value to be local to the connection being created (i.e. the specified argument value overrides the value in the context object). However, it is an error to specify values for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check. Those arguments cannot be overridden when a context is provided.

If an error occurs, a condition of type excl::ssl-error is signaled. This condition has slots what (a string indicating what internal operation was being performed when the error occurred), codes (a ist of numeric OpenSSL error codes that represented the accumulated errors that resulted in the final error), strings (a list of the corresponding string forms of the OpenSSL error codes in the 'codes' slot) and verify-result, and verify-result-string. The last two will be populated if possible when an ssl error occurs. If non-nil, this information is included in the printed representation of the condition. This aids recognizing and debugging certificate-related SSL errors.

The keyword arguments

make-ssl-client-stream's keyword arguments are the same as make-ssl-server-stream's. The keyword arguments to make-ssl-client-stream are:

See make-ssl-server-stream. See also <socket.html> for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.

make-ssl-server-context

Function, acl-socket package

Arguments: &key method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file (prefer-server-cipher-order t) server-name

This function creates and returns an SSL context object (an instance of the class excl::ssl-context) suitable for use as the value of the context keyword argument to make-ssl-server-stream.

The context has values for all relevant arguments. For the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order, specifying a value in a call to make-ssl-server-stream which is also passed a context object as the value of the context argument causes the associated argument value to be local to that connection (i.e. the specified argument value overrides the value in the context object). The value for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check cannot be overridden when a context is provided. It is an error to supply a context and values for any of those arguments.

The keyword arguments

See <socket.html> for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.

make-ssl-server-stream

Function, acl-socket package

Arguments: socket &key context certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file prefer-server-cipher-order server-name

You must have the OpenSSL libraries installed for this facility to work. Note that shared library versions of the OpenSSL libraries (required by Allegro CL) are not available on all platforms. The SSL functionality is in the ssl module. To ensure it is loaded, evaluate (require :ssl). Calling this function automatically loads the module.

This function creates and returns a new SSL server socket stream that communicates via SSL via the given socket. Once this function is called and an SSL socket stream is returned, no I/O calls should be done directly to socket. Note that closing the SSL socket stream will result in the original socket file descriptor being closed as well. Therefore, the idiomatic way to establish an SSL server socket stream is:

;; SOCK is already a socket:
(setf sock (make-ssl-server-stream sock ...))

Unless ssl-do-handshake is called, the secure connection isn't negotiated until the first byte is sent through the SSL socket stream to the underlying stream (and this will usually occur when the first force-output is done to the SSL socket stream).

When that first write is done a negotiation process is begun that involves reads and writes. This negotiation process will not occur if the SSL socket on the other end of the connection is not sitting waiting for data to arrive. Thus if you create two connected sockets in a single Lisp process, and make one the client and the other the server, and then write to the client side the Lisp will hang since the server side socket isn't being read. You can make this work if you use the Lisp multiprocessing facility (see <multiprocessing.html>) to cause the server socket to be read at the same time that the write to the client socket is being done.

The context keyword argument takes an SSL context object as a value. Such objects contain relevant information about the server stream being created. The function make-ssl-server-context create a context suitable for a server stream.

Note that if you supply an SSL context object as the value of context, you can specify values for the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order in the call to this function. Doing so causes the associated argument value to be local to the connection being created (i.e. the specified argument value overrides the value in the context object). However, it is an error to specify values for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check as they cannot be overridden when a context is provided.

The server-name keyword argument appears in the argument list for this function but is not supported at this time. Do not specify a value for that argument.

If an error occurs, a condition of type excl::ssl-error is signaled. This condition has slots what (a string indicating what internal operation was being performed when the error occurred), codes (a ist of numeric OpenSSL error codes that represented the accumulated errors that resulted in the final error), strings (a list of the corresponding string forms of the OpenSSL error codes in the 'codes' slot) and verify-result, and verify-result-string. The last two will be populated if possible when an ssl error occurs. If non-nil, this information is included in the printed representation of the condition. This aids recognizing and debugging certificate-related SSL errors.

The keyword arguments

make-ssl-server-stream's keyword arguments are the same as make-ssl-client-stream's. The keyword arguments to make-ssl-server-stream are:

See make-ssl-client-stream. See also <socket.html> for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.

open-ftp-stream

Function, acl-socket package

Arguments: file &key (host "localhost") (user "anonymous") (password (format nil "~[email protected]" (sys:user-name))) (direction :input) debug (mode :binary) passive

This function creates a stream to/from the given file on the given host using the given user and password for authentication.

The keyword arguments are:

receive-from

Generic Function, acl-socket package

Arguments: sock size &key buffer extract

This generic function is used to read from a datagram socket. You must specify a size bigger than the size of the message you expect (usually the rest of the datagram will be thrown away if it doesn't all fit).

If the buffer argument is given then it should be a Lisp vector of some raw type (like (unsigned-byte 8) but definitely not t) of at least size bytes that will be used to read in the datagram. If buffer is not given then a fresh buffer will be created (of the type appropriate to the format of the socket).

The buffer argument may be a character vector. In this case receive-from will create a temporary buffer of type (unsigned-byte 8) into which to read the octets and then octets-to-string will be used to convert those octets to characters. If you want to save the creation of this temporary array for each call to receive-from you should pass an (unsigned-byte 8) array in as the buffer. When using an 8-bit character Lisp (e.g., alisp8 or mlisp8-- see Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi in <startup.html>), no temporary buffer is created and no conversion occurs.

If extract is unspecified or nil then the first value returned is the buffer used to read the data. If extract is true then the first value returned is a subsequence of the buffer, that subsequence being that part of the buffer that contains the data just read.

The second value returned is the number of bytes read by receive-from.

In the case of an :internet socket, the third value returned is the 32-bit internet address or the IPv6 address of the sender of the data and the fourth value is the port number.

In the case of a :file socket, the third (and last) value returned is the filename of the sender's socket (or "" if there is no filename).

See <socket.html> for general information on sockets in Allegro CL.

remote-filename

Generic Function, acl-socket package

Arguments: af-file

Returns the remote filename of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

remote-host

Generic Function, acl-socket package

Arguments: af-internet

Returns an IP address. You can use ipaddr-to-dotted or ipaddr-to-hostname to make a more readable version of this value if you plan to print it out.

See <socket.html> for general information on sockets in Allegro CL.

remote-port

Generic Function, acl-socket package

Arguments: af-internet

Returns the remote port of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

send-to

Generic Function, acl-socket package

Arguments: sock buffer size &key remote-host remote-port ipv6 scope-id

For datagram sockets you can't do normal Lisp stream I/O. The data is written to the socket using this function.

The buffer argument can be a string or a byte vector; the size argument is the number of bytes of data to send. (The buffer argument is actually passed unmodified to a foreign function that will grab bytes from the address, so any simple 1-d Lisp array with any element size can in principle work, given the right byte count, provided sender and receiver have the same endianess.)

remote-host and remote-port describe where to send the data. If they aren't given then the values saved when the socket was created with make-socket are used.

The ipv6 and scope-id keyword arguments are part of IPv6 support. ipv6 defaults to the value of *ipv6*. This keyword argument is passed on to lookup-hostname when resolving remote-host.

scope-id specifies the interface to use when sending IPv6 traffic to remote-host. If remote-host is specified and is an ipv6-address structure, its scope-id slot will be updated to the value of the scope-id keyword argument.

If scope-id is not specified, then the scope-id slot of the remote-host argument will be used. If remote-host is not specified or does not have a scope-id, then 0 will be used.

Method for file-datagram-socket

Arguments (sock file-datagram-socket) buffer size &key remote-filename

The method for file-datagram-sockets is like the method for datagram sockets described above, except it is used for sockets within the address family :file.

The method for file-datagram-socket is unaffected by the IPv6 changes. file-datagram sockets are not internet sockets so they cannot use IPv6 (or IPv4) addresses.

See <socket.html> for general information on sockets in Allegro CL.

set-socket-format

Generic Function, acl-socket package

Arguments: str to

Because socket formats are not used (see socket-format), this generic function has no effect.

See <socket.html> for general information on sockets in Allegro CL.

set-socket-options

Function, acl-socket package

Arguments: socket &key reuse-address broadcast keepalive nodelay oob-inline receive-buffer-size send-buffer-size tcp-keepalive-idle-time tcp-keepalive-probe-interval tcp-keepalive-max-probes

Sets system socket options for this socket.
The meanings of most of the options are described in the description of make-socket. The various tcp-keepalive-* options are described below.

The following are boolean options, and so specifying a true value turns them on and specifying nil turns them off. If you do not specify a value for one of these options, then the value is not changed.

receive-buffer-size and send-buffer-size take integer arguments. Again, not specifying a value leaves it unchanged.

Note that certain options only work with certain kinds of sockets (e.g. broadcast only works for datagram sockets). See the description of make-socket for more information on what works with what sort of socket.

The tcp-keepalive-idle-time, tcp-keepalive-probe-interval, and tcp-keepalive-max-probes keywords set socket options defined by the C constants TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT on operating systems where they are supported (none is supported on Solaris, TCP_KEEPIDLE is not supported on macOS). The values should be integers (defaults 7200, 75, and 9 respectively). See the tcp(7) UNIX man page for more information.

It is an error to try to specify a value of an unsupported value. Thus (socket:set-socket-options socket :tcp-keepalive-idle-time 1) will signal an error on Solaris and macOS.

See <socket.html> for information on sockets.

set-tcp-md5-sig

Generic Function, acl-socket package

Arguments: socket address key &key (external-format :default)

This function only works on Linux. If executed on a non-Linux host, an error will be generated.

This function provides an interface to the TCP_MD5SIG (RFC2385) socket option. It sets the key to be used for TCP connections from address. This function can be called multiple times to set up keys for different addresses.

socket must be a passive stream socket (as created by (make-socket :connect :passive ...)). See make-socket.

address must be an IP address.

key must be a string or octet array.

If key is a string, external-format can supplied to specify a non-default external format for the string. The string will not be null-terminated.

See <socket.html>.

shutdown

Generic Function, acl-socket package

Arguments: sock &key direction

sock is a socket currently connected to another socket. The value of the direction must be specified either :input or :output. Note that direction defaults to nil which is not a legal value. shutdown will signal an error if direction is not specified either :input or :output.

shutdown closes down the specified half of the bidirectional socket connection. It does not force out unflushed buffers first (as the close function does).

Calling shutdown on a socket twice, once for :input and once for :output will cause the operating system file descriptor associated with the socket to be closed. Thus you need not call the Lisp function close. Note it is not an error to call close; it will just do nothing.

This function is useful in many socket applications.

For example:

(setq sock (make-socket :remote-host &quot;foo&quot; :remote-port 1234))
(format sock &quot;are you ok?~%&quot;)
(force-output sock)
(shutdown sock :direction :output)

(read sock)

Calling shutdown in the above example causes the program at the other end of the connection to receive an End of File indication. Some programs, when they receive an End of File, formulate and send a reply back down the socket. Using shutdown rather than close allows this reply to be read.

See <socket.html> for general information on sockets in Allegro CL.

socket-address-family

Generic Function, acl-socket package

Arguments: socket

Returns the socket address family of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

socket-connect

Generic Function, acl-socket package

Arguments: socket

Returns the type of connection for socket. The value can be :active or :passive. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

socket-control

Generic Function, acl-socket package

Arguments: sock &key output-chunking output-chunking-eof input-chunking read-timeout write-timeout

This function modifies the state of the socket stream. The associated value in the argument socket of any unspecified keyword argument is not modified. Only specified keyword arguments change the state of the argument socket.

If specified, the output-chunking argument controls whether the chunking protocol will be used for output on this socket (yes if true, no if nil). If this argument is not specified, output chunking is not affected. Note that if there is data still in the output buffer for this socket stream and chunking is turned on, then the chunking protocol will be applied to the data in the buffer when it is eventually written to the socket. Therefore you may want to call force-output before turning on chunking.

If output-chunking-eof is true then this occurs:

  1. a force-output is done to flush the socket output buffer.
  2. a zero sized chunk message is sent to the socket, which causes the process at the other end of the socket connect to interpret this as a chunking end of file.
  3. chunking for this socket is turned off (as if socket-control were called with :output-chunking nil)

If specified, the input-chunking argument controls whether data being read from the socket is interpreted as chunked data (yes if true, no if nil). If this argument is not specified, input chunking is not affected.

When input chunking is enabled a chunk end of file will cause the reading function (read-byte, read-char, read-sequence) to return just as if a real end of file was reached. In order to distinguish a real end of file from a chunking end of file, when a chunking end of file occurs the socket code will signal the condition excl::socket-chunking-end-of-file with the format-arguments slot being a list whose sole member is the stream that received the chunking end of file. This condition is not an error or warning, thus if it isn't caught Lisp will simply ignore it.

Timeout arguments

If specified, the value timeout arguments read-timeout and write-timeout should be nil or a positive real number. If nil, reads or writes will not timeout (except possibly because of other timeouts specified by other tools). If the value is a positive real number, attempted reads (when read-timeout is not nil) and attempted writes (when write-timeout is not nil) will timeout if the time is exceeded and the system will signal a socket-error.

Specifying timeout can be important for SSL streams (such as created by make-ssl-client-stream and make-ssl-server-stream) because read from and writes to a socket stream will not timeout when executed in a sys:with-timeout body (see the description of sys:with-timeout for more information). Reads from and writes to an SSL stream are done by breaking the data to be read/written into blocks and then processing the blocks one at a time. Note: the timeout values for SSL streams apply to the reading/writing time for individual blocks ony, not to the entire read or write.

Note that if reading from/writing to an SSL stream times out and an error is signaled, it is very likely the SSL stream will be in a broken state and should be closed (with the abort keyword argument to close specified true).

See <socket.html> for general information on sockets in Allegro CL.

socket-format

Generic Function, acl-socket package

Arguments: socket

Starting in 6.0, all sockets have :multivalent format and this function always returns :multivalent.

See <socket.html> for general information on sockets in Allegro CL.

socket-os-fd

Generic Function, acl-socket package

Arguments: sock

Return the operating system file descriptor associated with this socket. This is useful if you want to do some socket processing in foreign code and that code needs to access the socket directly. Note: Such accessing will likely confuse the buffering done by Lisp.

See <socket.html> for general information on sockets in Allegro CL.

socket-type

Generic Function, acl-socket package

Arguments: socket

Returns the type of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.

See <socket.html> for general information on sockets in Allegro CL.

ssl-do-handshake

Generic Function, acl-socket package

Arguments: stream

This function returns t but is called for its side effect, which is to initiate a handshake between SSL server and client streams.

make-ssl-server-stream and make-ssl-client-stream do not immediately initiate SSL handshake. Instead, handshake is deferred until the first I/O is made on the stream. If there are certificate verification or other errors during SSL handshake, the error will be generated during the I/O request that initiated handshake.

In some circumstances you may want to control when SSL starts. The ssl-do-handshake method initiates SSL handshake. stream must be an SSL client or server stream (such as is created by make-ssl-server-stream).

This function returns t but is called for its side effect, which is to initiate a handshake between SSL server and client streams.

make-ssl-server-stream and make-ssl-client-stream do not immediately initiate SSL handshake. Instead, handshake is deferred until the first I/O is made on the stream. If there are certificate verification or other errors during SSL handshake, the error will be generated during the I/O request that initiated handshake.

In some circumstances you may want to control when SSL starts. The ssl-do-handshake method initiates SSL handshake. stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and ) and make-ssl-client-stream).

Peer certificate verification (if requested) occurs during SSL handshake. If verification fails, an error will be generated.

See <socket.html>.

with-pending-connect

Macro, acl-socket package

Arguments: &rest body

A call to make-socket can take a while (maybe a minute or two) to make or fail to make a connection.

If you want to limit the amount of time spent in the make-socket call you can write it with a with-timeout. If the timeout occurs, then the program gives up on trying to make the connection. However the connection is offically still pending and operating system resources will continue to be used. Thus, it's important to clean up after a timed out attempt to make a connection.

The best way to ensure that things are cleaned up is to use with-pending-connect. Just write your code something like this:

(socket:with-pending-connect
  (sys:with-timeout (10 (error &quot;connect failed&quot;))
    (socket:make-socket
      :remote-host &quot;foo.com&quot; :remote-port 1234)))

The with-pending-connect wraps the body with an unwind-protect that will clean up the pending connection as control passes through it.

See <socket.html> for general information on sockets in Allegro CL.

x509-certificate-issuer

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the issuer slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the issuer (i.e., signer) of the certificate. The issuer information is represented as a list of attribute/value conses. The car of each cons is a string representing the attribute type ("CN", "ST", "L", "O", "OU", "CN", etc.) and the cdr of each cons is a string representing the value of the attribute.

See <socket.html>.

x509-certificate-not-after

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the not-after slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the expiration date of the certificate, in universal time format.

See <socket.html>.

x509-certificate-not-before

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the not-before slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the beginning validity date of the certificate, in universal time format.

See <socket.html>.

x509-certificate-serial-number

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the serial-number slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the serial number of the certificate, in integer form.

See <socket.html>.

x509-certificate-subject

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the subject slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the subject of the certificate (i.e., the entity to which the certificate belongs). The subject information is represented in the same way as the issuer information (see x509-certificate-issuer).

See <socket.html>.

x509-certificate-subject-alt-name

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the subject-alt-name slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the subjectAltName extension information which may be part of v3 certificates. If available, the subjectAltName information is represented as a list of attribute/value conses. The car of each cons is a string representing the type of subjectAltName (such as "DNS"). The cdr of each cons is a string representing the attribute value.

See <socket.html>.

x509-certificate-version

Generic Function, acl-socket package

Arguments: stream

This function returns the value of the version slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot typically contains a keyword indicating the version number of the certificate. The value will be either :v1, :v2, or :v3. If the version number of the certificate is not recognized, this slot will contain the raw integer supplied in the certificate.

The version number indicates the format of the certificate. Most certificates seen these days will be version 3 certificates (:v3).

See <socket.html>.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.