MUNGE Credential Format

The current version of the credential format is as follows:

  +---+------------------------------------------------------------+---+
  |   | 08b : version number (3)                                   |   |
  | O | 08b : cipher type (munge_cipher_t)                         | O |
  | U | 08b : message authentication code type (munge_mac_t)       | U |
  | T | 08b : compression type (munge_zip_t)                       | T |
  | E | 08b : length (in bytes) of security realm string           | E |
  | R | var : security realm string (w/o terminating null)         | R |
  |   | var : cipher IV (initialization vector)                    |   |
  +---+------------------------------------------------------------+---+
  | M | var : MAC (message authentication code)                    | M |
  +---+------------------------------------------------------------+---+
  |   | 64b : salt                                                 |   |
  |   | 08b : length (in bytes) of the origin IP address           |   |
  |   | var : origin IP address (where the credential was encoded) |   |
  | I | 32b : time at which the credential was encoded (time_t)    | I |
  | N | 32b : time to live (in seconds) once encoded               | N |
  | N | 32b : UID of the client that requested the credential      | N |
  | E | 32b : GID of the client that requested the credential      | E |
  | R | 32b : UID of the client allowed to decode the credential   | R |
  |   | 32b : GID of the client allowed to decode the credential   |   |
  |   | 32b : length (in bytes) of payload data                    |   |
  |   | var : payload data being munged into the credential        |   |
  +---+------------------------------------------------------------+---+

• Field lengths are expressed in bits, or 'var' for variable length.
• All 32b integers are in network byte order (i.e., big endian / MSBF).
• The length of the cipher IV is dependent upon the munge_cipher_t.
• The length of the MAC is dependent upon the munge_mac_t.

For encoding, the following rules determine the order of operations:

1. Compression must occur before encryption since the resulting ciphertext should appear statistically random and therefore be incompressible.
2. The MAC must be computed after compression because it must protect the validity of the 64b compression header that encodes the original length of the uncompressed data.
3. The MAC must be computed before encryption because the MAC is used to compute the data encryption key (DEK) for the symmetric cipher.
4. Base64 encoding must occur last.

Consequently, credentials are encoded in the following steps:

1. The INNER layer is compressed according to the munge_zip_t.
2. The MAC is computed over the entire message (i.e., OUTER + INNER) using an HMAC specified by the munge_mac_t in combination with the MAC subkey.
3. The INNER layer is encrypted in cipher block chaining mode with PKCS #5 padding according to the munge_cipher_t. The DEK used for symmetric encryption is computed from the credential's MAC using an HMAC specified by the munge_mac_t in combination with the DEK subkey.
4. The entire message (i.e., OUTER + MAC + INNER) is base64 encoded.
5. The base64 encoding is prepended with "MUNGE:" and appended with ":".