Cryptography

The term signature is used throughout this document to refer to the authentication tag used to integrity protect data and authenticate the entity. The signature data may actually consist of an HMAC or some other form of authentication tag instead of a true cryptographic signature. The data structures also use the text “signature” for this field.

Encryption and signature computation is always performed over binary data. When the data is a string it will be converted to its UTF-8 binary representation before performing encryption and sign operations, and the same binary representation will be included in MSL messages. This ensures that the same binary data is used when performing decryption and verify operations.

The following ciphertext and signature envelopes are defined. They may be used by specific entity authentication schemes, but will always be used when performing encryption or computing signatures using session keys. The envelopes are designed to allow detection of the version from the envelope data itself.

Ciphertext Envelopes

Version 1

cipherenvelope = {
  "#mandatory" : [ "keyid", "iv", "ciphertext", "sha256" ],
  "keyid" : "string",
  "iv" : "binary",
  "ciphertext" : "binary",
  "sha256" : "binary"
}

Field	Description
ciphertext	encrypted data
iv	initialization vector
keyid	encryption key ID
sha256	SHA-256 hash of the encryption envelope

Key ID & SHA-256

The key ID and SHA-256 values are included to provide sanity checks but do not include integrity checks; it is assumed that ciphertext envelopes will be part of any authenticated data covered by a signature. These values are of limited use and only remain for legacy reasons.

The SHA-256 is computed over the concatenation of the key ID (UTF-8), IV, and ciphertext.

Version 2

This version is not yet fully validated or in use.

cipherenvelope = {
  "#mandatory" : [ "version", "cipherspec", "ciphertext" ],
  "version" : "number",
  "cipherspec" : "string",
  "iv" : "binary",
  "ciphertext" : "binary"
}

Field	Description
cipher spec	The encryption algorithm, mode, and padding
ciphertext	encrypted data
iv	initialization vector
version	The number ‘2’

Cipher Specification

Some example cipher specifications are:

Cipher Specification	Description
AES/CBC/PKCS5Padding	AES encryption CBC mode PKCS#5 padding
AES/CTR/PKCS5Padding	AES encryption CTR mode PKCS#5 padding
AES/GCM/PKCS5Padding	AES encryption GCM mode PKCS#5 padding

Signature Envelopes

Version 1

Signatures are not enveloped and are represented as raw bytes. This version can be identified by having a byte length equal to the expected signature byte length.

signature

Version 2

This version is not fully validated or in use.

signatureenvelope = {
  "#mandatory" : [ "version", "algorithm", "signature" ],
  "version" : "number",
  "algorithm" : "string",
  "signature" : "binary",
}

Field	Description
algorithm	The signature algorithm
signature	raw signature
version	The number ‘2’

Algorithm

Note that the algorithm need not refer to an actual cryptographic signature but may also refer to some other form of authentication tag such as HMAC.

Some example algorithms are:

Algorithm	Description
HmacSHA256	HMAC SHA-256
SHA1withRSA	SHA-1 with RSA
SHA256withECDSA	SHA-256 with ECDSA
SHA256withRSA	SHA-256 with RSA

Algorithm Names

The Java Cryptography Architecture Standard Algorithm Names are used throughout to refer to cryptographic algorithms. Unless otherwise stated, an algorithm’s implementation should match the description of this document and the implementation found in the Java Cryptography Extension.