Citrix ADC extensions API reference

Behaviors are a formalization of common programmable patterns that are available on a Citrix ADC appliance. For example, a TCP virtual server supports a TCP client behavior and a TCP server behavior. A behavior is a pre-defined set of callback functions. You can implement behaviors by providing callback functions. For example, a TCP client behavior can consist of the on_data function, which processes the TCP data stream.

TCP client behavior

on_data - function callback for TCP client data events. The callback takes two arguments:

• ctxt - TCP client processing context
• payload – event payload
  • payload.data - TCP data received, available as a stream of bytes

TCP server behavior

on_data - function callback for TCP server data events, the callback takes two arguments:

• ctxt - TCP server processing context
• payload – event payload
  • payload.data - tcp data received, available as a stream of bytes

TCP client context

The context that is passed to the TCP client event callbacks:

• ctxt.output - The next processing context in the pipeline. Extension call back handlers can send ns.tcp.stream type data to ctxt.output using the events DATA, which means partial message or EOM which means end of protocol message. The EOM event may or may not have TCP data with it. An EOM event with TCP data can be sent without a preceding DATA event to send a whole protocol message data and mark the end of message. The load balancing decision is made, downstream by the load balancing virtual server, on the first data received. A new load balancing decision is made after the receipt of the EOM message. So, to stream protocol message data, send multiple DATA events with the last event as EOM. All the contiguous DATA events and the following EOM events are sent to the same server connection selected by the load balancing decision on the first DATA event in the sequence.

• ctxt.input - The previous processing context in the pipeline where the TCP stream data is coming from.

• ctxt:hold(data) - Function to store the data for future processing. On calling hold with data, the data is stored in the context. Later, when more data is received on the same context, newly received data is appended to the previously stored data and the combined data stream is then passed to the on_data callback function. After calling a hold, the data reference is no longer usable and gives error on any usage.

• ctxt.vserver - The virtual server context.

• ctxt.client – Client connection processing context. This processing context can be used to send data to the client, and to fetch some connection related information like IP address, source and destination ports.

• ctxt:close() – Close the client connection by sending FIN to the client. After calling this API, the client processing context is no longer usable and gives error on any usage.

TCP server context

The context that is passed to the TCP server event callbacks:

• ctxt.output – The next processing context in the pipeline. Extension call back handlers can send ns.tcp.stream type data to ctxt.output using the events DATA, which means partial message or EOM which means end of protocol message.

• ctxt.input - The previous processing context in the pipeline where the TCP stream data is coming from.

• ctxt:hold(data) - Function to store the data for future processing. On calling hold with data, the data is stored in the context. Later, when more data is received on the same context, newly received data is appended to the previously stored data and the combined data stream is then passed to the on_data callback function. After calling a hold, the data reference is no longer usable and gives error on any usage.

• ctxt.vserver - The virtual server context.

• ctxt.server - Server connection processing context. This processing context can be used to send data to the server, and to fetch some connection related information like IP address, source and destination ports.

• ctxt:reuse_server_connection () - This API is used to allow the server connection to be reused for other client connections in the server context only. This API can be used only if an EOM event is used (in ns.send() API) to send the data in the client context. Otherwise, the ADC appliance throws an error.

  To allow a server connection to be reused by other clients, this API must be called at the end of each response message. After calling this API, if more data is received on this server connection, this is treated as an error and the server connection is closed. If this API is not used, then the server connection can be used only for that client for which it was opened. Also, if the same server is selected for another load balancing decision for that client, then the same server connection is used to send the client data. After using this API, server connection stops being tied to the client connection for which it was opened, and can be reused for a new load balancing decision for any other client connection. After calling this API, the server context is no longer usable and throws an error on any usage.

  Note: This API is available in Citrix ADC 12.1 build 49.xx and later.

• ctxt:close() – Close the server connection by sending FIN to the server. After calling this API, the client processing context is no longer usable and displays an error on any usage.

  Note: This API is available in Citrix ADC 12.1 build 50.xx and later.

Vserver context

The user virtual server context available through the contexts passed to callbacks:

• vserver:counter_increment(counter_name) - Increments the value of a virtual server counter passed as argument. Currently the following built-in counters are supported.
  • - invalid_messages – Number of invalid requests/responses on this virtual server.
  • - invalid_messages_dropped – Number of invalid requests/responses dropped by this virtual server.
• vserver.params - The configured parameters for the user virtual server. Parameters provide configurability of extensions. The extension code can access parameters that are specified in the CLI to add a user virtual server.

Client connection context

Client connection processing context to get connection related information.

• client.ssl – SSL context
• client.tcp – TCP context
• client.is_ssl – True if client connection is SSL-based

Server connection context

Server connection processing context to get connection related information.

• server.ssl – SSL context
• server.tcp – TCP context
• server.is_ssl – True if server connection is SSL-based

TCP context

TCP context operates on TCP protocol.

• tcp.srcport – Source port as a number
• tcp.dstport - Destination port as a number

IP context

IP context works on IP or IPv6 protocol data.

• ip.src - Source IP address context.
• ip.dst - Destination IP address context.

Note: This API is available in Citrix ADC 12.1 build 51.xx and later.

IP address context

IP address context works on IP or IPv6 address data.

• <address>.to_s - The address string in the appropriate ASCII notation.
• <address>.to_n - The address’ numeric value as a string of bytes in network order (4 bytes for IPv4 and 16 bytes for IPv6).
• <address>.version - Returns 4 for IPv4 and 6 for IPv6.
• <address>:subnet(<prefix value>) - Returns the subnet address string after applying the prefix number.
  • For IPv4 address, value must be between 0 and 32
  • For IPv6 address, value must be between 0 and 128.
• <address>:apply_mask(<mask string>) - Returns the address string after applying mask string. API validates the version of argument and does appropriate error checking.
• address>:eq(<address string>) - Returns true or false based on whether the argument is equivalent to the address object. API validates the version of the arguments.

Note: This API is available in Citrix ADC 12.1 build 51.xx and later.

SSL context

The SSL context provides information related to frontend SSL connection.

• ssl.cert – SSL certificate context. For the client connection, it provides client certificate context and for the server connection, it provides server certificate context.

• ssl.version - A number that represents the SSL protocol version of the current transaction, as follows:

  • - 0: The transaction is not SSL-based
  • - 0x002: The transaction is SSLv2
  • - 0x300: The transaction is SSLv3
  • - 0x301: The transaction is TLSv1
  • - 0x302: The transaction is TLSv1.1
  • - 0x303: The transaction is TLSv1.2
• ssl.cipher_name - SSL Cipher name as string if invoked from an SSL connection, otherwise gives NULL string.
• ssl.cipher_bits – Number of bits in cryptographic key.

SSL certificate context

• Cert.version – Version number of the certificate. If the connection is not SSL based, returns 0.
• Cert.valid_not_before – Date in string format before which certificate is not valid.
• Cert.valid_not_after – Date in string format after which certificate is no longer valid.
• Cert.days_to_expire – Number of days before which certificate is valid. Returns -1 for expired certificate.
• Cert.to_pem – Certificate in binary format.

• cert.issuer - Distinguished Name (DN) of the Issuer in the certificate as a name-value list. An equals sign (“=”) is the delimiter for the name and the value, and the slash (“/”) is the delimiter that separates the name-value pairs.

  Following is an example of the returned DN: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

• cert.auth_keyid – Context of Authority Key Identifier extension of the X.509 V3 certificate.

  • auth_keyid.exists - TRUE if the certificate contains an Authority Key Identifier extension.

  • auth_keyid.issuer_name - Issuer Distinguished Name in the certificate as a name-value list. An equals sign (“=”) is the delimiter for the name and the value, and the slash (“/”) is the delimiter that separates the name-value pairs.

  Following is an example: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

  • auth_keyid.keyid - KeyIdentifier field of the Authority Key Identifier as a blob
  • auth_keyid.cert_serialnumber - SerialNumber field of the Authority Key Identifier as a blob.
• cert.pk_algorithm - Name of the public key algorithm used by the certificate.
• cert.pk_size - Size of the public key used in the certificate.
• cert.serialnumber - Serial number of the client certificate. If this is a non-SSL transaction or there is an error in the certificate, this gives an empty string.
• cert.signature_algorithm - Name of the cryptographic algorithm used by the CA to sign this certificate.
• cert.subject_keyid - Subject KeyID of the client certificate. If there is no Subject KeyID, this gives a zero-length text object.
• cert.subject - Distinguished Name of the Subject as a name-value. An equals sign (“=”) separates names and values and a slash (“/”) delimits name-value pairs.

Following is an example: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

Citrix ADC libraries

• ns.tcp.stream - String like library for handling TCP data as a stream of bytes. The maximum size of TCP stream data on which these APIs can work is 128 KB. The ns.tcp.stream library functions can also be called in the usual extension object oriented style of calling. For example, data:len() is the same as ns.tcp.stream.len(data)
  • ns.tcp.stream.len(data) - Returns length of data in bytes, similar to Lua’s string.len
  • ns.tcp.stream.find(data, pattern [, init]) - Function similar to Lua’s string.find. In addition, it also does partial matching at the end of data. Upon partial match, the start index is returned and the end index becomes nil.
  • ns.tcp.stream.split(data, length) - Splits the data into two chunks, the first chunk is of the specified length. After a successful split the original data is no longer usable as a TCP data stream. Any attempt to use it that way causes an error.
  • ns.tcp.stream.byte(data[, i [, j]]) - Function similar to Lua’s string.byte. Returns the internal numerical codes of the characters data[i], data[i+1], …, data[j].
  • ns.tcp.stream.sub(data, i [, j]) - Function similar to Lua’s string.sub. Returns the substring of s that starts at i and continues until j.
  • ns.tcp.stream.match(data, pattern, [, init]) - Function similar to Lua’s string.match. Looks for the first match of pattern in string s.

• ns.send(processing_ctxt, event_name, event_data) - Generic function to send events to a processing context. Event data is a Lua table that can have any content. The contents depend on the event. After the ns.send() API is called, the data reference is no longer usable. Any attempt to use it causes an error.

• ns.pipe(src_ctxt, dest_ctxt) - Using a call to pipe() API, extension code can connect source context to a destination context. After a call to pipe, all the events that are sent from source context to the next module in the pipeline go directly to the destination context. This API is typically used by the module that makes the pipe() call, to remove itself from the pipeline.

• ns.inet – Library for internet addresses.

  • ns.inet.apply_mask(address_str, mask_str) - returns the address string after applying mask string.
  • ns.inet.aton(address_str) - Returns address’ numeric value as a string of bytes in network order (4 bytes for IPv4 and 16 for IPv6).
  • ns.inet.ntoa(byte_str) - Converts numeric byte value as a string of bytes to address string.
  • ns.inet.ntohs(number) - Convert the given network byte order to host byte order. If the input is greater than 2^16 - 1, then throws an error.
  • ns.inet.htons(number) - Converts the given host byte order to network byte order. If the input is greater than 2^16 - 1, then throws an error.
  • ns.inet.ntohl(number) - Converts the given network byte order to host byte order. If the input is greater than 2^32 - 1, then throws an error.
  • ns.inet.htonl(number) - Converts the given host byte order to network byte order. If the input is greater than 2^32 - 1, then throws an error.
  • ns.inet.subnet(address_str, subnet_value) – Returns the subnet address string after applying given subnet.