Complex operations on text

In addition to performing simple string matching, you can configure expressions that examine more complex aspects of text, including examining the length of a string and looking within a text block for patterns rather than specific strings.

Be aware of the following for any text-based operation:

  • For any operation that takes a string argument, the string cannot exceed 255 characters.
  • You can include white space when you specify a string in an expression.

Operations on the length of a string

The following operations extract strings on the basis of a character count.

Character Count Operation Description
<text>.TRUNCATE(<count>) Returns a string after truncating the end of the target by the number of characters in <count>. If the entire string is shorter than <count>, nothing is returned.
<text>.TRUNCATE(<character>, <count>) Returns a string after truncating the text after <character> by the number of characters specified in <count>.
<text>.PREFIX(<character>, <count>) Selects the longest prefix in the target that has at most <count> occurrences of <character>.
<text>.SUFFIX(<character>, <count>) Selects the longest suffix in the target that has at most <count> occurrences of <character>. For example, consider the following response body: JLEwx. The following expression returns a value of “JLEwx”: http.res.body(100).suffix(‘L’,1) The following expression returns “LLEwx”: http.res.body(100).suffix(‘L’,2)  
<text>.SUBSTR(<starting_offset>, <length>) Select a string with <length> number of characters from the target object. Begin extracting the string after the <starting_offset>. If the number of characters after the offset are fewer than the value of the <length> argument, select all the remaining characters.
<text>.SKIP(<character>, <count>) Select a string from the target after skipping over the longest prefix that has at most <count> occurrences of <character>.

Operations on a portion of a string

You can extract a subset of a larger string by using one of the operations in the following table.

Basic Text Operation Description
<text>.BEFORE_STR(<string>) Returns the text that precedes the first occurrence of <string>. If there is no match for <string>, the expression returns a text object of 0 length. Following is an example: http.res.body(1024).after_str(“start_string”).before_str(“end_string”).contains(“https”)
<text>.AFTER_STR(<string>) Returns the text that follows the first occurrence of <string>. If there is no match for <string>, the expression returns a text object of 0 length. Following is an example: http.res.body(1024).after_str(“start_string”).before_str(“end_string”).contains(“https”)
<text>.BETWEEN(<starting string>, <ending string>) Returns a Boolean TRUE value if the length of the text object is greater than or equal to the sum <starting string>, <ending string> argument lengths, and if a prefix of the target matches <starting string>, and if the suffix of the target matches <ending string>.
<text>.PREFIX(<prefix length>) Returns the starting string from a target block of text that contains the number of characters in the <prefix length> argument. If the <prefix length> argument exceeds the number of characters in the target, the entire string is selected.
<text>.SUFFIX(<suffix length>) Returns the ending string from a target block of text that contains the number of characters in the <suffix length> argument. If the <suffix length> argument exceeds the number characters in the target, the entire string is selected.
<text>.SUBSTR(<string>) Select the first block of text in the target that matches the <string>.
<text>.SKIP(<prefix length>) Selects the text in the target after skipping over a <prefix length> number of characters. If the entire target has fewer characters than <prefix length>, the entire target is skipped.
<text>.STRIP_END_WS Selects the text after removing white space from the end of the target.
<text>.STRIP_START_WS Selects the text after removing white space from the beginning of the target.
<text>.UNQUOTE(<character>) Selects the <character>, removes white space that immediately precedes and follows the <character>, and if the remaining text is quoted by <character>, this prefix also removes the quotes. For example, the operation UNQUOTE(‘”’) changes the text: ”abc xyz def” to the following: abc xyz def

Operations for comparing the alphanumeric order of two strings

The COMPARE operation examines the first nonmatching character of two different strings. This operation is based on lexicographic order, which is the method used when ordering terms in dictionaries.

This operation returns the arithmetic difference between the ASCII values of the first nonmatching characters in the compared strings. The following differences are examples:

  • The difference between “abc” and “abd” is -1 (based on the third pair-wise character comparison).
  • The difference between “@” and “abc” is -33.
  • The difference between “1” and “abc” is -47.

Following is the syntax for the COMPARE operation.

<text>.COMPARE(<string>)

Extract an integer from a string of bytes that represent text

You can use the following functions to treat a string of bytes that represent text as a sequence of bytes, extract 8, 16, or 32 bits from the sequence, and then convert the extracted bits to an integer.

Function Description
<text>.GET_SIGNED8(<n>) Treats the string of bytes represented by text as a sequence of 8-bit signed integers and returns the integer at byte offset n. If the offset makes all or part of the value outside of the current text, an UNDEFcondition is raised.
<text>.GET_UNSIGNED8(<n>) Treats the string of bytes represented by text as a sequence of 8-bit unsigned integers and returns the integer at byte offset n. If the offset makes all or part of the value outside of the current text, an UNDEFcondition is raised.
<text>.GET_SIGNED16(<n>, <endianness>) Treats the text string returned by the prefix as a string of bytes, extracts 16 bits starting at byte offset n, and converts the extracted bit sequence to a 16-bit signed integer. If the offset makes all or part of the value outside of the current text, an UNDEF condition is raised. The first parameter n is the byte offset from the current position in the text string. Providing a byte offset enables the function to handle items that are not aligned on the boundaries that are required by indexes. The second parameter, endianness, takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN. Note: In NetScaler 9.2, the parameter n was an index into an array of 16-bit items. In NetScaler 9.3, the parameter is a byte offset. Therefore, if you used this function in NetScaler 9.2, after you upgrade to NetScaler 9.3, you must change n to 2*n to obtain the same results as you did earlier. For example, if the value of n before the upgrade was 4, you must change the value of n to 8. The parameter endianness also no longer takes the values that it did in NetScaler 9.2, which were 0 and 1. Instead, endianness accepts the mnemonic values mentioned earlier. Example: HTTP.REQ.BODY(100).GET_SIGNED16(8, BIG_ENDIAN)
<text>.GET_UNSIGNED16(<n>, <endianness>) Treats the text string returned by the prefix as a string of bytes, extracts 16 bits starting at byte offset n, and converts the extracted bit sequence to a 16-bit unsigned integer. If the offset makes all or part of the value outside of the current text, an UNDEF condition is raised. The first parameter n is the byte offset from the current position in the text string. Providing a byte offset enables the function to handle items that are not aligned on the boundaries that are required by indexes. The second parameter, endianness, takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN. Note: In NetScaler 9.2, the parameter n was an index into an array of 16-bit items. In NetScaler 9.3, the parameter is a byte offset. Therefore, if you used this function in NetScaler 9.2, after you upgrade to NetScaler 9.3, you must change n to 2*n to obtain the same results as you did earlier. For example, if the value of n before the upgrade was 4, you must change the value of n to 8. The parameter endianness also no longer takes the values that it did in NetScaler 9.2, which were 0 and 1. Instead, endianness accepts the mnemonic values mentioned earlier. Example: HTTP.REQ.BODY(100).GET_UNSIGNED16(8, LITTLE_ENDIAN)
<text>.GET_SIGNED32(<n>, <endianness>) Treats the text string returned by the prefix as a string of bytes, extracts 32 bits starting at byte offset n, and converts the extracted bit sequence to a 32-bit signed integer. If the offset makes all or part of the value outside of the current text, an UNDEF condition is raised. The first parameter n is the byte offset from the current position in the text string. Providing a byte offset enables the function to handle items that are not aligned on the boundaries that are required by indexes. The second parameter, endianness, takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN. Note: In NetScaler 9.2, the parameter n was an index into an array of 32-bit items. In NetScaler 9.3, the parameter is a byte offset. Therefore, if you used this function in NetScaler 9.2, after you upgrade to NetScaler 9.3, you must change n to 4*n to obtain the same results as you did earlier. For example, if the value of n before the upgrade was 4, you must change the value of n to 16. The parameter endianness also no longer takes the values that it did in NetScaler 9.2, which were 0 and 1. Instead, endianness accepts the mnemonic values mentioned earlier. Example: HTTP.REQ.BODY(1000).GET_SIGNED32(12, BIG_ENDIAN)
<text>.GET_UNSIGNED32(<n>, <endianness>) Treats the text string returned by the prefix as a string of bytes, extracts 32 bits starting at byte offset n, and returns the extracted bit sequence as part of a 64-bit unsigned long integer. If the offset makes all or part of the value outside of the current text, an UNDEFcondition is raised. The first parameter n is the byte offset from the current position in the text string. Providing a byte offset enables the function to handle items that are not aligned on the boundaries that are required by indexes. The second parameter, endianness, takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN. Example: HTTP.REQ.BODY(1000).GET_UNSIGNED32(30, LITTLE_ENDIAN

Convert text to a hash value

You can convert a text string to a hash value by using the HASH function. This function returns a 31-bit positive integer as a result of the operation. Following is the format of the expression:

<text>.HASH

This function ignores case and white spaces. For example, after the operation, the two strings Ab c and a bc would produce the same hash value.

Encode and decode text by applying the Base64 encoding algorithm

The following two functions encode and decode a text string by applying the Base64 encoding algorithm

Function Description
text.B64ENCODE Encodes the text string (designated by text) by applying the Base64 encoding algorithm.
text.B64DECODE Decodes the Base64-encoded string (designated by text) by applying the Base64 decoding algorithm. The operation raises an UNDEF if text is not in B64-encoded format.

Refine the search in a rewrite action by using the EXTEND function

The EXTEND function is used in rewrite actions that specify patterns or pattern sets and target the bodies of HTTP packets. When a pattern match is found, the EXTEND function extends the scope of the search by a predefined number of bytes on both sides of the matching string. A regular expression can then be used to perform a rewrite on matches in this extended region. Rewrite actions that are configured with the EXTEND function perform rewrites faster than rewrite actions that evaluate entire HTTP bodies using only regular expressions.

The format of the EXTEND function is EXTEND(m,n ), where m and n are the number of bytes by which the scope of the search is extended before and after the matching pattern, respectively. When a match is found, the new search scope comprises m bytes that immediately precede the matching string, the string itself, and the n bytes that follow the string. A regular expression can then be used to perform a rewrite on a portion of this new string.

The EXTEND function can be used only if the rewrite action in which it is used fulfills the following requirements:

  • The search is performed by using patterns or patterns sets (not regular expressions)
  • The rewrite action evaluates only the bodies of HTTP packets.

Additionally, the EXTEND function can be used only with the following types of rewrite actions:

  • replace_all
  • insert_after_all
  • delete_all
  • insert_before_all

For example, you might want to delete all instances of “http://exampleurl.com/” and “http://exampleurl.au/” in the first 1000 bytes of the body. To do this, you can configure a rewrite action to search for all instances of the string exampleurl, extend the scope of the search on both sides of the string when a match is found, and then use a regular expression to perform the rewrite in the extended region. The following example extends the scope of the search by 20 bytes to the left and 50 bytes to the right of the matching string:

add rewrite action delurl_example delete_all 'HTTP.REQ.BODY(1000)' -pattern exampleurl -refineSearch 'extend(20,50).regex_select(re#http://exampleurl.(com|au)#)'

Convert text to hexadecimal format

The following function converts text to hexadecimal format and extracts the resulting string:

<text>.BLOB_TO_HEX(<string>)

For example, this function converts the byte string “abc” to “61:62:63”.

Encrypt and decrypt text

In default syntax expressions, you can use the ENCRYPT and DECRYPT functions to encrypt and decrypt text. Data encrypted by the ENCRYPT function on a given NetScaler appliance or high availability (HA) pair is intended for decryption by the DECRYPT function on the same NetScaler appliance or HA pair. The appliance supports the RC4, DES3, AES128, AES192, and AES256 encryption methods. The key value that is required for encryption is not user-specifiable. When an encryption method is set, the appliance automatically generates a random key value that is appropriate for the specified method. The default method is AES256 encryption, which is the most secure encryption method and the one that Citrix recommends.

You do not need to configure encryption unless you want to change the encryption method or you want the appliance to generate a new key value for the current encryption method.

Note: You can also encrypt and decrypt XML payloads. For information about the functions for encrypting and decrypting XML payloads, see Encrypt and decrypt XML payloads.

Configure encryption

During startup, the appliance runs the set ns encryptionParams command with, by default, the AES256 encryption method, and uses a randomly generated key value that is appropriate for AES256 encryption. The appliance also encrypts the key value and saves the command, with the encrypted key value, to the NetScaler configuration file. Consequently, the AES256 encryption method is enabled for the ENCRYPT and DECRYPT functions by default. The key value that is saved in the configuration file persists across reboots even though the appliance runs the command each time you restart it.

You can run the set ns encryptionParams command manually, or use the GUI, if you want to change the encryption method or if you want the appliance to generate a new key value for the current encryption method. To use the CLI to change the encryption method, set only the method parameter, as shown in “Example 1: Changing the Encryption Method.” If you want the appliance to generate a new key value for the current encryption method, set the method parameter to the current encryption method and the keyValue parameter to an empty string (“”), as shown in “Example 2: Generating a New Key Value for the Current Encryption Method.” After you generate a new key value, you must save the configuration. If you do not save the configuration, the appliance uses the newly generated key value only until the next restart, after which it reverts to the key value in the saved configuration.

Configure encryption by using the GUI

  1. Navigate to System > Settings.
  2. In the Settings area, click Change Encryption parameters.
  3. In the Change Encryption Parameters dialog box, do one of the following:
    • To change the encryption method, in the Method list, select the encryption method that you want.
    • To generate a new key value for the current encryption method, click Generate a new key for the selected method.
  4. Click OK.

Use the ENCRYPT and DECRYPT functions

You can use the ENCRYPT and DECRYPT functions with any expression prefix that returns text. For example, you can use the ENCRYPT and DECRYPT functions in rewrite policies for cookie encryption. In the following example, the rewrite actions encrypt a cookie named MyCookie, which is set by a back-end service, and decrypt the same cookie when it is returned by a client:

add rewrite action my-cookie-encrypt-action replace “HTTP.RES.SET_COOKIE.COOKIE(“MyCookie”).VALUE(0)” “HTTP.RES.SET_COOKIE.COOKIE(“MyCookie”).VALUE(0).ENCRYPT” -bypassSafetyCheck YES

add rewrite action my-cookie-decrypt-action replace “HTTP.REQ.COOKIE.VALUE(“MyCookie”)” “HTTP.REQ.COOKIE.VALUE(“MyCookie”).DECRYPT” -bypassSafetyCheck YES

After you configure policies for encryption and decryption, save the configuration to bring the policies into effect.

Configure encryption key for third-party encryption

In default syntax expressions, you can use ENCRYPT and DECRYPT functions for encrypting and decrypting text in a request or response. The data encrypted by the ENCRYPT function on an appliance (standalone, high availability or cluster) is intended to be decrypted by the DECRYPT function by the same appliance. The appliance supports RC4, DES, Triple-DES, AES92, and AES256 encryption methods and each of these methods use a secret key for both encryption and decryption of data. You can use the any of these methods to encrypt and decrypt data in two ways - self-encryption and third-party encryption.

The self-encryption feature in an appliance (standalone, high availability or cluster) encrypts and then decrypts data by evaluating the header value. One example to understand this is the HTTP Cookie encryption. The expression evaluates the header, encrypts the HTTP cookie value in the Set-Cookie header in the outgoing response and then decrypts the cookie value when it is returned in the cookie header of a subsequent incoming request from the client. The key value is not user configurable, instead when an encryption method is configured in the set ns encryptionParams command, the appliance automatically generates a random key value for the configured method. By default, the command uses the AES256 encryption method, which is the highly secured method and Citrix recommends this method.

The third-party encryption feature encrypts or decrypts data with a third-party application. For example, a client may encrypt data in a request and the appliance decrypts the data before sending it the back-end server or vice versa. To perform this, the appliance and the third party application must share a secret key. On the appliance, you can directly configure the secret key using an encryption key object and key value is automatically generated by the appliance for a stronger encryption. The same key is manually configured on the third-party appliance so that both appliance and third-party application can use the same key for encrypting and decryption data.

Note: Using third-party encryption, you can also encrypt and decrypt XML payloads. For information about the functions for encrypting and decrypting XML payloads, see “Encrypting and Decrypting XML Payloads.

Cipher methods

A cipher method provides two functions: an encryption function that transforms a plaintext byte sequence into a ciphertext byte sequence, and a decryption function that transforms the ciphertext back to the plaintext. Cipher methods use byte sequences called keys to perform encryption and decryption. Cipher methods that use the same key for encryption and decryption are called symmetric. Cipher methods that use different keys for encryption and decryption are asymmetric. The most notable examples of asymmetric ciphers are in public key cryptography, which uses a public key available to anyone for encryption and a private key known only to the decryptor.

A good cipher method makes it infeasible to decrypt (“crack”) ciphertext if you don’t possess the key. “Infeasible” really means that cracking the cyphertext would take more time and computing resources than it is worth. As computers become more powerful and cheaper, ciphers that were formerly infeasible to crack become more feasible. Also, over time, flaws are found in cipher methods (or their implementations), making cracking easier. Newer cipher methods are therefore preferred over older ones. In general, longer length keys provide better security than shorter keys, at the cost of longer encryption and decryption times.

A cipher method can use stream ciphers or block ciphers. RC4 is the mostly secured stream ciphers and it is used only for legacy application. Block ciphers can include padding.

Stream ciphers

A stream cipher method operates on individual bytes. Only one stream cipher is available on NetScaler-  appliances: RC4, which uses a 128 bit (16 byte) key length. For a given key, RC4 generates a pseudo-random sequence of bytes, call a keystream, which is X-ORed with the plaintext to produce the ciphertext. RC4 is no longer considered secure and should be used only if required by legacy applications.

Block ciphers

A block cipher method operates on a fixed block of bytes. A NetScaler appliance provides two block ciphers: Data Encryption Standard (DES) and the Advanced Encryption Standard (AES). DES uses a block size of 8 bytes and (on a NetScaler appliance) two choices for key length: 64 bits (8 bytes), of which 56 bits are data and 8 bits are parity, and Triple-DES, a 192 bit (24 byte) key length. AES has a block size of 16 bytes and (on NetScaler) three choices for key length: 128 bits (16 bytes), 192 bits (24 bytes) and 256 bits (32 bytes).

Padding

If the plaintext for a block cipher is not an integral number of blocks, padding with additional bytes might be required. For example, suppose the plaintext is “xyzzy” (hex 78797a7a79). For an 8-byte Triple-DES block, this value would have to be padded to create 8 bytes. The padding scheme must allow the decryption function to determine the length of the original plaintext after decryption. Following are some padding schemes currently in use (n is the number of bytes added):

  • PKCS7: Adds n bytes of value n each. For example, 78797a7a79030303. This is the padding scheme used by OpenSSL and ENCRYPT() policy function. The PKCS5 padding scheme is the same as PKCS7.
  • ANSI X.923: Adds n-1 zero bytes and a final byte of value n. For example, 78797a7a79000003.
  • ISO 10126: Adds n-1 random bytes and a final byte of value n. For example, 78797a7a79xxxx03, where xx can be any byte value. The DECRYPT() policy function accepts this padding scheme, which also allows it to accept the PKCS7 and ANSI X.923 schemes.
  • ISO/IEC 7816-4: Adds a 0x80 byte and n-1 zero bytes. For example, 78797a7a79800000. This is also call OneAndZeros padding.
  • Zero: Adds n zero bytes. Example: 78797a7a79000000. This can only be used with plaintext that does not include NUL bytes.

If padding is used and the plaintext is an integral number of blocks, an additional block is typically added so that the decryption function can unambiguously determine the original plaintext length. For PCKS7 and 8 byte block, this would be 0808080808080808.

Modes of operation

There are a number of different modes of operation for block ciphers, which specify how multiple blocks of plaintext are encrypted. Some modes use an initialization vector (IV), a block of data apart from the plaintext that is used to start the encryption process. It is a good practice to use a different IV for each encryption, so that the same plaintext produces different ciphertext. The IV does not need to be secret, and so is usually prepended to the ciphertext. Modes include:

  • Electronic Codebook (ECB): Each block of plaintext is encrypted independently. An IV is not used. Padding is required if the plaintext is not a multiple of the cipher block size. The same plaintext and key always produces the same ciphertext. Because of this, ECB is considered less secure than other modes and should only be used for legacy applications.
  • Cipher Block Chaining (CBC): Each block of plaintext is XORed with the previous ciphertext block, or the IV for the first block, before being encrypted. Padding is required if the plaintext is not a multiple of the cipher block size. This is the mode used with the NetScaler encryptionParams method.
  • Cipher Feedback (CFB): The previous ciphertext block, or the IV for the first block, is encrypted and the output is XORed with the current plaintext block to create the current ciphertext block. The feedback can be 1 bit, 8 bits, or 128 bits. Since the plaintext is XORed with the cipher text, padding is not required.
  • Output Feedback (OFB): A keystream is generated by applying the cipher successively to the IV and XORing the keystream blocks with the plaintext. Padding is not required.

Configure encryption keys for third-party encryption

Following are the configuration tasks performed in configuring encryption key.

  1. Adding an encryption key. Configures an encryption key for a specified cipher method with a specified key value.
  2. Modifying an encryption key. You can edit parameters for a configured encryption key.
  3. Unsetting an encryption key. Sets parameters for a configured encryption key to their default values. An encryptionKey value with the name must exist. Sets padding to DEFAULT (determined by the method), Deletes an existing IV, which causes ENCRYPT() to generate a random IV. Deletes an existing comment. The method and key value cannot be reset.
  4. Removing an encryption key.  Deletes a configured encryption key. The key cannot have any references.
  5. Show an encryption key. Displays parameters for the configured encryption key or all configured keys. If the name is omitted, the key value is not displayed.

Add an encryption key by using the CLI

At the command prompt, type:

add ns encryptionKey <name> -method <method> [-keyValue <hexstring>][-padding (OFF | ON)] [-iv <hexstring>] [-comment <string>]

Where,

<method> = ( NONE RC4 DES3 AES128 AES192 AES256 DES DES-CBC DES-CFB DES-OFB DES-ECB DES3-CBC DES3-CFB DES3-OFB DES3-ECB AES128-CBC AES128-CFB AES128-OFB AES128-ECB AES192-CBC AES192-CFB AES192-OFB AES192-ECB AES256-CBC AES256-CFB AES256-OFB AES256-ECB ) <hexstring> = hex-encoded byte sequence

The above encryption methods specify the operation mode with CBC as the default mode of operation. Therefore, DES, DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-CBC, AES128-CBC, AES192-CBC, and AES256-CBC methods.

Modify an encryption key by using the CLI

At the command prompt, type:

set ns encryptionKey <name> [-method <method>] [-keyValue <hexstring>] [-padding ( OFF | ON )] [-iv <string>] [-comment <string>]

Unset an encryption key by using the CLI

At the command prompt, type:

unset ns encryptionKey <name> [-padding] [-iv] [-comment]

Remove an encryption key by using the CLI

At the command prompt, type:

rm ns encryptionKey <name>

Show an encryption key by using the CLI

At the command prompt, type:

Example:

show ns encryptionKey [<name>]

add ns encryptionKey my_key -method aes256 -keyValue 26ea5537b7e0746089476e5658f9327c0b10c3b4778c673a5b38cee182874711 –iv c2bf0b2e15c15004d6b14bcdc7e5e365
    set ns encryptionKey my_key -keyValue b8742b163abcf62d639837bbee3cef9fb5842d82d00dfe6548831d2bd1d93476
    unset ns encryptionKey my_key -iv
    rm ns encryptionKey my_key
    show ns encryptionKey my_key
    Name: my_key
    Method: AES256
    Padding: DEFAULT
    Key Value: (not disclosed)

Add an encryption key by using the GUI

Navigate to System > Encryption Keys and click Add to create an encryption key.

Modify an encryption key by using the GUI

Navigate to System > Encryption Keys and click Edit to modify parameters for a configured encryption key.

Remove an encryption key by using the GUI

Navigate to System > Encryption keys and click Delete.

ENCRYPT and DECRYPT functions for third-party encryption

Following is the ENCRYPT function used for third-part encryption.

ENCRYPT (encryptionKey, out_encoding)

Where,

Input data for the appliance is the text to be encrypted

encryptionKey: An optional string parameter that specifies the configured encryption key object to provide the encryption method, secret key value and other encryption parameters. If omitted, the method uses the automatically generated key value associated with the set ns encryptionParamS command.

out_encoding: This value specifies how the output is encoded. If omitted, BASE64 encoding is used.

Input:

BASE64:     original PEM base64-encoding: 6 bits (0..63) encoded as one ASCII character:
                  0..23 = 'A'..'Z', 24..51 = 'a'..'z', 52..61 = '0'..'9', 62 = '+', 63 = '/', '=' = pad byte.
      BASE64URL:  URL and Filename safe base64-encoding: same as BASE64 except 62 = '-', 63 = '_'
      HEX_UPPER:  Hexadecimal with 0..9 = '0'..'9' and 10..15 = 'A'..'F'.
      HEX_LOWER:  Hexadecimal with 0..9 = '0'..'9' and 10..15 = 'a'..'f'.
      HEX_COLONS: Hexadecimal with 0..9 = '0'..'9' and 10..15 = 'A'..'F'; ':' between each hex byte. Matches BLOB_TO_HEX() output format
      HEX:        For input, accepts HEX_UPPER, HEX_LOWER, and HEX_COLONS format. For output, produces HEX_LOWER format

Output: The output is a text encrypted using the specified method and key and encoded using a specified output encoding. It inserts a generated IV before the encrypted text for block methods and modes that require an IV, and either no IV is specified for the encryptionKey or the encryptionKey is omitted.

Following is the DECRYPT function used for third-part decryption.

DECRYPT(encryptionKey, in_encoding)

Where,

Input data is an encrypted text using the specified method and key encoded using the specified input encoding. This text is expected to include a generated IV before the encrypted text for block methods and modes that require an IV, and either no IV is specified for the encryptionKey or the encryptionKey is omitted.

encryptionKey—An optional string parameter that specifies the configured encryptionKey object to provide the encryption method, secret key and other encryption parameters. If omitted, the method and automatically generated key associated with the encryptionParams setting will be used

in_encoding—An optional enumeration parameter that specifies how the input is expected to be encoded. The values are the same as the out_encoding of ENCRYPT. If omitted, BASE64 encoding will be expected.

The output data is an unencoded decrypted text.

Variants and optional parameters

Following are the variants of these functions with the optional parameters:

ENCRYPT Use encryptionParams command and BASE64 output encoding parameter.
ENCRYPT(out_encoding) Use encryptionParams and specified output encoding parameter.
ENCRYPT(encryptionKey) Use the specified encryptionKey and BASE64 output encoding parameter.
ENCRYPT(encryptionKey, out_encoding) Use the specified encryptionKey and output encoding parameter.
DECRYPT Use encryptionParams command and BASE64 input encoding parameter.
DECRYPT(out_encoding) Use encryptionParams command and the specified input encoding parameter.
DECRYPT(encryptionKey) Use the specified encryptionKey and BASE64 input encoding parameter.
DECRYPT(encryptionKey, out_encoding) Use the specified encryptionKey and input encoding parameter.

Configure HMAC keys

NetScaler appliances support a Hashed Message Authentication Code (HMAC) function that calculates a digest method or hash of input text by using a secret key shared between a message sender and message receiver. The digest method (derived from an RFC 2104 technique) authenticates the sender and verifies that the message content has not been altered. For example, when a client sends a message with the shared HMAC key to a NetScaler appliance, advanced (PI) policy expressions use the HMAC function to compute the hash-based code on the selected text. Then, when the receiver receives the message with the secret key, it recomputes the HMAC by comparing it with the original HMAC to determine whether the message has been altered. The HMAC function is supported by standalone appliances and by appliances in a high availability configuration or in a cluster. Using it is similar to configuring an encryption key.

The add ns hmackey and set ns hmackey commands include a parameter that specifies the digest method and the shared secret key to use for the HMAC computation.

To configure a HMAC key, you must perform the following:

  1. Adding an HMAC key. Configures an HMAC key with a specified key value.
  2. Modifying an HMAC key. Modifies parameters for a configured HMAC key. The digest method can be changed without changing the key value, since the key value length is not determined by the digest. However, it is advisable to specify a new key when changing the digest.
  3. Unsetting an HMAC key. Sets parameters for a configured HMAC key to their default values. An hmacKey object with the name must exist. The only parameter that can be unset is the comment, which is deleted.
  4. Removing an HMAC key.  Deletes a configured key. The key cannot have any references.
  5. Show an HMAC key. Displays parameters for the configured HMAC ac key or all configured keys. If the name is omitted, the key value is not displayed.

Add an HMAC key by using the CLI

At the command prompt, type:

add ns hmacKey <name> -digest <digest> -keyValue <hexstring> [-comment <string>]

Where,

<digest> = (MD2 MD4 MD5 SHA1 SHA224 SHA256 SHA384 SHA512)

This command configures a key for the HMAC () function with the specified digest and key value and also validates the following:

  • Name syntax is correct and does not duplicate the name of an existing key.
  • Key value is valid hex. As specified by RFC 2104, the key can any length. On a NetScaler appliance, the key value can range from 0 to 255 bytes (0 to 510 hex characters). If the key is shorter than the digest block size, a warning is issued and the key is padded with zeroes. If the key is longer than the block size, it is run through the digest to produce an effective key that is the same length as the block.

Example:

add ns hmacKey my_hmac_key -digest sha1 -keyValue 0c753c6c5ef859189cacdf95b506d02c1797407d

The above encryption methods specify the operation mode with CBC as the default mode of operation. Therefore, DES, DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-CBC, AES128-CBC, AES192-CBC, and AES256-CBC methods.

Modify an HMAC key by using the CLI

This command modifies the parameters configured for a HMAC key. You can change the digest without changing the key value, since the key value length is not determined by the digest. However, it is advisable to specify a new key when changing the digest. At the command prompt, type:

set ns hmacKey <name> [-digest <digest>] [-keyValue <hexvalue>] [-comment <string>]

Unset an HMAC key by using the CLI

This command sets parameters configured for a HMAC key with their default values. An hmacKey object with the name must exist. The only parameter that you can unset is the comment option, which is deleted. At the command prompt, type:

unset ns hmacKey <name> -comment

Remove an HMAC key by using the CLI

This command deletes the configured hmac key. The key cannot have references. At the command prompt, type:

rm ns hmacKey <name>

Show an HMAC key by using the CLI

At the command prompt, type:

show ns encryptionKey [<name>]

add ns hmacKey my_hmac_key -digest sha1 -keyValue 0c753c6c5ef859189cacdf95b506d02c1797407d
set ns hmacKey my_hmac_key -keyValue f348c594341a840a1f641a1cf24aa24c15eb1317
rm ns hmacKey my_hmac_key
show ns hmacKey my_hmac_key
          Name: my_hmac_key
    Digest: SHA1
    Key Value: (not disclosed)