Symmetric Algorithm Encipher (CSNBSAE)

Edit online

Use the Symmetric Algorithm Encipher verb to encipher data using the AES algorithm.

CCA supports the following processing rules to encipher 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 enciphered in Galois/Counter Mode (GCM). See also Symmetric Algorithm Decipher (CSNBSAD). 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 encipher 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:
    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 encryption 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 in application storage or a key label of such a key in AES key-storage
    4. For processing rule CBC or ECB, an optional ICV (initial chaining value) selection using the keyword INITIAL (the default) or 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 that can be used for encryption (key-usage field 1 high-order byte is 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 is 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 is 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, 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 cleartext to be enciphered.
  • A ciphertext buffer large enough to receive the enciphered output.
This verb does the following when it enciphers the data:
  1. Verifies the AES key-token for keyword KEYIDENT.
  2. Deciphers the input AES key if the key is encrypted (MKVP was present in token).
  3. Pads the cleartext data with 1 - 16 bytes on the right for keyword PKCS-PAD, otherwise verifies that the cleartext length is a multiple of the block size.
  4. Enciphers the cleartext, including any pad characters, with the AES clear key according to the encryption mode specified.
  5. Returns the ciphertext data and its length.
  6. Returns the chain data and its length if keyword ECB is not specified.
  7. Constructs an authentication tag in the key_parms variable if the GCM processing rule is specified in the rule array.

CPACF exploitation for CSNBSAE requires fixed-length AES key-tokens with a key type of DATA or variable-length AES key-tokens of type CIPHER with ENCRYPT 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.

Support of the Australian Payment Network (APN)

The Symmetric Algorithm Encipher service supports the Australian Payment Network (APN) standards to generate and verify MACs and related processing as defined in AS2805.5.4.

To generate a MAC with the processing rule keyword A28MACGN, specify the following parameters:

  • key_identifier: Double-length TDES MAC key.
  • key_parms: Double-length TDES CIPHER key.
  • cleartext: Clear message text.
  • chain_data:
    • Input: Starting MAC residue, encrypted by the key in the key_parms parameter.
    • Output: Final MAC residue, encrypted by the key in the key_parms parameter.
  • ciphertext:
    • Output: 8-byte MAC.

To verify a MAC with the processing rule keyword A28MACVR, specify the following parameters:

  • key_identifier: Double-length TDES MAC key.
  • key_parms: Double-length TDES CIPHER key.
  • cleartext: Clear message text.
  • chain_data:
    • Input: Starting MAC residue as indicated by the Residue value keyword, encrypted by the key in the key_parms parameter.
    • Output: Final MAC residue, encrypted by the key in the key_parms parameter.
  • ciphertext:
    • Input: 8-byte MAC to verify.
    • Output: 8-byte MAC.

For the One Way Function processing with the processing rule keyword A28OWFEC (only valid with DES), specify the following parameters:

  • key_identifier: Double-length DES EXPORTER key.
  • key_parms: Double-length DES CIPHER or DECIPHER key.
  • chain_data: Input value ECB-wrapped by the key specified in the key_parms parameter.
  • ciphertext: Output of the OWF.

For the One Way Function processing with the processing rule keyword A28OWFCL (only valid with DES), specify the following parameters:

  • key_identifier: Double-length DES CIPHER key.
  • chain_data: Clear input value.
  • ciphertext: Output of the OWF: ciphertext = OWF(key_identifier, chain_data)

This verb does not need to document any Usage notes.