Complex operations on text
In addition to simple string matching, you can configure expressions that examine string length and 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 by a character count.
Character Count Operation | Description |
---|---|
|
Returns a string after truncating the end of the target by the number of characters in . If the entire string is shorter than , nothing is returned. |
, ) |
Returns a string after truncating the text after by the number of characters specified in . |
, ) |
选择the longest prefix in the target that has at most occurrences of . |
, ) |
选择the longest suffix in the target that has at most occurrences of . For example, consider the following response body:peninsula . The following expression returns a value ofsula: http.res.body(100).suffix('n',0) . The following expression returnsinsula: http.res.body(100).suffix('n',1) . The following expression returns a value ofpeninsula: http.res.body(100).suffix('n',2) . The following expression returns a value ofpeninsula: http.res.body(100).suffix('n',3) . |
) |
Select a string with number of characters from the target object. Begin extracting the string after the . If the number of characters after the offset are fewer than the value of the argument, select all the remaining characters. |
|
Select a string from the target after skipping over the longest prefix that has at most occurrences of . |
Operations on a portion of a string
Refer to theString operations tableto know how to extract a subset of a larger string by using one of the operations.
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 “and” 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.
Extract an integer from a string of bytes that represent text
Refer to theInteger extraction tableto know how to treat a string of bytes that represent text as a sequence of bytes, extract 8 bits, 16 bits, or 32 bits from the sequence, and then convert the extracted bits to an integer.
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:
这个函数忽略了案例和空白。对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.
Also, the EXTEND function can be used only with the following types of rewrite actions:
- replace_all
- insert_after_all
- delete_all
- insert_before_all
对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:
对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 Citrix ADC appliance or high availability (HA) pair is intended for decryption by the DECRYPT function on the same Citrix ADC 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, seeEncrypt 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 Citrix ADC configuration file. Therefore, 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 configuration utility, 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”。如果你想要这个设备来生成一个新密钥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
- Navigate toSystem>Settings.
- In theSettingsarea, clickChange Encryptionparameters.
- In theChange Encryption Parametersdialog 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.
- ClickOK.
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 decrypter.
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 Citrix ADC- appliances: RC4, which uses a 128 bit (16 bytes) 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 Citrix ADC 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 Citrix ADC 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 bytes) key length. AES has a block size of 16 bytes and (on Citrix ADC) 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 more 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 extra 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 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 Citrix ADC 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.
- Adding an encryption key. Configures an encryption key for a specified cipher method with a specified key value.
- Modifying an encryption key. You can edit parameters for a configured encryption key.
- 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.
- Removing an encryption key. Deletes a configured encryption key. The key cannot have any references.
- 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.
添加一个加密密钥使用CLI
At the command prompt, type:
add ns encryptionKey
Where,
= ( 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 ) = hex-encoded byte sequence
上面的加密方法指定操作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
Unset an encryption key by using the CLI
At the command prompt, type:
unset ns encryptionKey
Remove an encryption key by using the CLI
At the command prompt, type:
rm ns encryptionKey
Show an encryption key by using the CLI
At the command prompt, type:
Example:
show ns encryptionKey [] 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 toSystem>Encryption Keysand clickAddto create an encryption key.
Modify an encryption key by using the GUI
Navigate toSystem>Encryption Keysand clickEditto modify parameters for a configured encryption key.
Remove an encryption key by using the GUI
Navigate toSystem>Encryption keysand click删除.
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:
Variant | Description |
---|---|
ENCRYPT | 使用encryptionParamscommand and BASE64 output encoding parameter. |
ENCRYPT(out_encoding) | 使用encryptionParamsand 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 | 使用encryptionParamscommand and BASE64 input encoding parameter. |
DECRYPT(out_encoding) | 使用encryptionParamscommand 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
Citrix ADC 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 Citrix ADC 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:
- Adding an HMAC key. Configures an HMAC key with a specified key value.
- 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.
- 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.
- Removing an HMAC key. Deletes a configured key. The key cannot have any references.
- 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.
Configure a unique and random HMAC key
You can automatically generate an unique HMAC key. If you appliance is a cluster configuration, the HMAC key is generated at the start of the process and distributed to all nodes and packet engines. This ensures the HMAC key is same for all packet engines and all nodes in the cluster.
At the command prompt, type:
add ns hmacKey
Example:
add ns hmacKey
Where,
- Name syntax is correct and does not duplicate the name of an existing key.
- The “AUTO” keyValue can be used in the set commands to generate new keys for existing encrytionKey and hmacKey objects.
Note:
The automatic key generation is useful if the Citrix ADC appliance is encrypting and decrypting data with the key, or generating and verifying an HMAC key. Since the key value itself is already encrypted when displayed, you cannot retrieve the generated key value for use by any other party.
Example:
add ns hmacKey my_hmac_key -digest sha1 -keyValue 0c753c6c5ef859189cacdf95b506d02c1797407d
上面的加密方法指定操作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 an 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 [-digst ] [-keyValue ] [-comment ]
Unset an HMAC key by using the CLI
This command sets parameters configured for an 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
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
Show an HMAC key by using the CLI
At the command prompt, type:
show ns encryptionKey [] 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)
In this article
- Operations on the length of a string
- Operations on a portion of a string
- Operations for comparing the alphanumeric order of two strings
- Extract an integer from a string of bytes that represent text
- Convert text to a hash value
- Encode and decode text by applying the Base64 encoding algorithm
- Refine the search in a rewrite action by using the EXTEND function
- Convert text to hexadecimal format
- Encrypt and decrypt text
- Configure encryption key for third-party encryption
- Configure HMAC keys
- Show an HMAC key by using the CLI