Symmetric Algorithm Decipher (CSNBSAD)

Edit online

Use the Symmetric Algorithm Decipher verb to decipher data with an Advanced Encryption Standard (AES) algorithm.

Data can be deciphered in either Cipher Block Chaining (CBC) mode with or without padding, or in Electronic Code Book (ECB) mode. Beginning with Release 5.2, data can be deciphered in Galois/Counter Mode (GCM). Also see Symmetric Algorithm Encipher (CSNBSAE).

CCA supports the following processing rules to decipher data. You choose the type of processing rule that the verb should use for block chaining.

Cipher Block Chaining (CBC)
The plaintext must be an exact multiple of eight bytes, and the ciphertext will have the same length.
Electronic Code Book (ECB)
The plaintext length must be a multiple of the block size.
Galois/Counter Mode (GCM)
The plaintext can be deciphered in Galois/Counter Mode (GCM). For more information on GCM, read NIST SP 800-38D Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC, November 2007. Available at http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf.
Public Key Cryptography Standards Pad (PKCS-PAD)
The plaintext was padded on the right with 1 - 16 bytes of pad characters, making the padded text a multiple of the block size.
The AES key used to decipher the data can either be 16, 24, or 32 bytes (128, 192, or 256 bits) in length. The key can be supplied to the verb in any of three forms:
  1. A cleartext key consisting of only the key bytes, not contained in a key token.
  2. A cleartext key contained in an internal fixed or variable length AES key-token.
  3. An encrypted key contained in an internal fixed or variable length AES key-token, where the key is wrapped (encrypted) with the AES master key.
Note: This verb supports PCI-HSM 2016 compliant-tagged key tokens.

To use this verb, specify:

  • The rule_array parameter:
    1. The algorithm identifier keyword AES, which is the only symmetric algorithm currently supported.
    2. An optional processing rule using keyword CBC (the default), ECB, GCM, or PKCS-PAD, which selects the decryption mode.
    3. An optional key rule using the keyword KEY-CLR (the default) or KEYIDENT, which selects whether the key_identifier parameter points to a 16-byte, 24-byte, or 32-byte clear key, or a key contained in a 64-byte AES key-token, either in application storage or a key label of such a key in key storage.
    4. For processing rule CBC or ECB, specify an optional ICV (initial chaining value) selection using the keyword INITIAL (the default). Or use keyword CONTINUE, which indicates whether it is the first or a subsequent request, and which parameter points to the initialization vector.

      For processing rule GCM, specify an optional ICV keyword ONLY (default).

  • For a key rule of KEY-CLR, a key identifier containing a 16-byte, 24-byte, or 32-byte clear key. For a key rule of KEYIDENT, a fixed-length or variable-length internal AES key-token or the key label of such a key in AES key-storage. The key token can contain either a clear or enciphered key.

    A variable-length AES key-token must have a key type of CIPHER that can be used for decryption (key-usage field 1 high-order byte = B'x1xx xxxx') and cannot be used for data translation (KUF1 high-order byte = B'xx0x xxxx'). Also, for processing rule CBC or PKCS-PAD, key usage must allow the key to be used for Cipher Block Chaining (KUF2 high-order byte = X'00' or X'FF').

    For processing rule ECB, key usage must allow the key to be used for Electronic Code Book (KUF2 high-order byte = X'01' or X'FF').

    For processing rule GCM, the key usage must allow the key to be used for Galois/Counter mode (KUF2 high-order byte = X'04' or X'FF').

  • A block size of 16 for the cryptographic algorithm.
  • For cipher block chaining, specify either one of these:
    1. For an ICV selection of INITIAL, a 16-byte initialization vector of your choosing and a 32-byte chain data buffer.
    2. For an ICV selection of CONTINUE, no initialization vector and the 32-byte chain data buffer from the output of the previous chained call. The electronic code book algorithm does not use an initialization vector or a chain data buffer.
    3. For an ICV selection of ONLY, an initialization vector greater than 0 and a maximum of 232 - 1, and a 104-byte chain data buffer.
  • The ciphertext to be deciphered.
  • A cleartext buffer large enough to receive the deciphered output.
This verb does the following when it deciphers the data:
  1. Verifies the AES key-token for keyword KEYIDENT.
  2. Verifies that the ciphertext length is a multiple of the block size.
  3. Deciphers the input AES key if the key is encrypted (MKVP was present in token).
  4. Deciphers the ciphertext with the AES clear key according to the encryption mode specified.
  5. Removes from 1 - 16 pad characters from the right of the clear data for keyword PKCS-PAD.
  6. Returns the cleartext data and its length.
  7. Returns the chain data and its length if keyword ECB is not specified.

CPACF exploitation for CSNBSAD requires fixed-length AES key-tokens with a key type of DATA or variable-length AES key-tokens of type CIPHER with DECRYPT key-usage enabled. A fixed-length AES DATA key has a control vector (CV) of all X'00' bytes for all active bytes of the CV. For details about CPACF, see CPACF support.

This verb does not need to document any Usage notes.