linux-ima-devel

[Linux-ima-devel] IMA SHA-1 log format "specification"

[Ken G. <kg...@li...>]

While writing an attestation server, I found that I had to write an IMA 
log format parser (now open source).  Below is an informal specification 
based on the best information I have.

1 - I offer it for anyone who may be able to use it.

2 - There are questions throughout the text.  If anyone would like to
offer an answer, please do it on the list so everyone can validate it.

It probably makes sense to send one answer per post with a good subject 
line, in case it starts a thread.

3 - The below text was created from a Word document.  If anyone wants 
the original, it is a bit easier to read - different fonts, hyperlinks, 
the usual word processor things.

~~~


IMA Event Log Format

Ken Goldman
kgo...@us...
July 13, 2017





1.	Introduction	2
2.	IMA Event	2
2.1.	PCR Index	2
2.2.	Template Hash	3
2.3.	Template Name Length	3
2.4.	Template Name	3
2.5.	Template Data Length	3
2.6.	Template Data	3
3.	Template Data	4
3.1.	Hash Length	4
3.2.	Hash Algorithm	4
3.3.	File Data Hash	5
3.1.	File Name Length	5
3.2.	File Name	5
3.3.	Signature Length	5
3.4.	Signature Header	5
3.4.1.	Signature Type	5
3.4.2.	Signature Version	6
3.4.3.	Hash Algorithm	6
3.4.4.	Public Key Identifier	6
3.4.5.	Signature Size	6
3.5.	Signature	6
1. Introduction

This details the IMA event log format, field by field.

Multi-byte integer values (PCR index, length, etc.) are in the byte 
order of the host where the event log was created.  The receiver can 
determine the byte order by looking at the PCR Index field, or the 
sender can convert to network byte order before transmission.

Fields are always concatenated with no padding.

Question:  What is the maximum number of event records?
2. IMA Event

An IMA event record has the following fields.

2.1. PCR Index

This is a 4-byte integer representing the PCR Index.

Note:  The value is currently always 10.
2.2.  Template Hash

This is a 20-byte SHA-1 hash of the Template Data field.

There is no associated length or descriptor.

The Template Hash is used directly in the PCR 10 extend operation.
2.3. Template Name Length

This is a 4-byte integer representing the length of the Template Name field.

Question:  What is the maximum length?

2.4. Template Name

This is a printable string representing the template name.

The string is NOT nul terminated.  It is guaranteed to be printable.

For legal names, see section 3 Template Data.

2.5. Template Data Length

This is a 4-byte integer representing the length of the Template Data field.

Note that there is redundancy, in that the ima-sig data fields are 
self-describing.  This can be checked for consistency.

2.6. Template Data

See Section 3 Template Data for the contents of this field.


3. Template Data

Template data can have the following fields.  Unless specified, each is 
preceded by a 4-byte length.

d	20-byte digest, SHA-1 or zero padded MD-5 (no length)
d-ng	hash algorithm + digest
n	256-byte nul terminated file name (no length)
n-ng	file name
sig	signature header + signature
uuid	(undocumented)
pid	(undocumented)
ppid	(undocumented)
gid	(undocumented)

The template names become (where | is the concatenation symbol)

ima		d | n
ima-ng		d-ng | n-ng
ima-sig		d-ng | n-ng | sig

3.1. Hash Length

This is a 4-byte integer representing the combined length of the Hash 
Algorithm and File Data Hash fields.  Note that the File Data Hash 
contains the two following fields, and those fields do not have explicit 
lengths.

3.2. Hash Algorithm

This is a nul terminated string representing the hash algorithm of the 
File Data Hash field.  Two values are currently used:

* sha256:
* sha1:

Note this redundancy, which can be checked for consistency:

* The Hash Length minus the length of the Hash Algorithm field 
(including the nul terminator) yields the size of the File Data Hash.
* The length of a hash based on the Hash Algorithm yields the size of 
the File Data Hash.

3.3. File Data Hash

This is a hash of the file data that was used to compute the Signature.

The length and hash algorithm are determined by the Hash Algorithm field.

3.1. File Name Length

This is a 4-byte integer representing the length of the file name, 
including the nul terminator.  The maximum value is MAXPATHLEN +1?

Note that there is redundancy, in that the file name is nul terminated. 
This can be checked for consistency.

3.2. File Name

This is a nul terminated string representing the name of the file that 
was measured.

The length is determined by the File Name Length.

3.3. Signature Length

This is a 4-byte integer representing the total length of the Signature 
Header and Signature fields.  The value may be zero, indicating that 
those two fields are not present.

3.4. Signature Header

This field is fixed at 9 bytes, consisting of 5 fields.
3.4.1. Signature Type

This is a 1-byte field.  The value is 0x03.

Question:  What are the valid values and meanings.  How does the type 
affect the other fields.

Question:  Is the signature algorithm encoded here, or anywhere, or is 
RSA assumed?

3.4.2. Signature Version

This is a 1-byte field.  The value is 0x02.

Question:  What are the valid values and meanings.  How does the version 
affect the other fields.

3.4.3. Hash Algorithm

This is a 1-byte field representing the hash algorithm used for the File 
Data Hash.  The legal values are:

* 0x02: SHA-1
* 0x04: SHA-256

Note that there is redundancy, in that this field must be consistent 
with the Hash Algorithm field on the Template Data.

3.4.4. Public Key Identifier

This is a 4-byte field that identifies the public key.  It is the last 4 
bytes of the key's X.509 certificate Subject Key Identifier.

3.4.5. Signature Size

This is a 2-byte integer representing the size of the Signature field.

Question:  What are the legal values?  1024 and 2048?  Others?

3.5. Signature

This field represents the signature over the File Data Hash using the 
key specified by the Public Key Identifier and the hash algorithm 
represented by the (two) Hash Algorithm fields.





	Page 2	

Re: [Linux-ima-devel] IMA SHA-1 log format "specification"

[Mehmet K. <mka...@li...>]

> On Jul 17, 2017, at 4:44 PM, Ken Goldman <kg...@li...> wrote:
> 
> Question:  What is the maximum number of event records?

There is no limit and the number is stored in a long field. 

> 2. IMA Event
> 
> An IMA event record has the following fields.
> 
> 2.1. PCR Index
> 
> This is a 4-byte integer representing the PCR Index.
> 
> Note:  The value is currently always 10.
> 2.2.  Template Hash
> 
> This is a 20-byte SHA-1 hash of the Template Data field.
> 
> There is no associated length or descriptor.
> 
> The Template Hash is used directly in the PCR 10 extend operation.
> 2.3. Template Name Length
> 
> This is a 4-byte integer representing the length of the Template Name field.
> 
> Question:  What is the maximum length?

in security/integrity/ima/ima_template.c
#define MAX_TEMPLATE_NAME_LEN 15

> 
> 2.4. Template Name
> 
> This is a printable string representing the template name.
> 
> The string is NOT nul terminated.  It is guaranteed to be printable.
> 
> For legal names, see section 3 Template Data.
> 
> 2.5. Template Data Length
> 
> This is a 4-byte integer representing the length of the Template Data field.
> 
> Note that there is redundancy, in that the ima-sig data fields are self-describing.  This can be checked for consistency.
> 
> 2.6. Template Data
> 
> See Section 3 Template Data for the contents of this field.
> 
> 
> 3. Template Data
> 
> Template data can have the following fields.  Unless specified, each is preceded by a 4-byte length.
> 
> d	20-byte digest, SHA-1 or zero padded MD-5 (no length)
> d-ng	hash algorithm + digest
> n	256-byte nul terminated file name (no length)
> n-ng	file name
> sig	signature header + signature
> uuid	(undocumented)
> pid	(undocumented)
> ppid	(undocumented)
> gid	(undocumented)
> 
> The template names become (where | is the concatenation symbol)
> 
> ima		d | n
> ima-ng		d-ng | n-ng
> ima-sig		d-ng | n-ng | sig
> 
> 3.1. Hash Length
> 
> This is a 4-byte integer representing the combined length of the Hash Algorithm and File Data Hash fields.  Note that the File Data Hash contains the two following fields, and those fields do not have explicit lengths.
> 
> 3.2. Hash Algorithm
> 
> This is a nul terminated string representing the hash algorithm of the File Data Hash field.  Two values are currently used:
> 
> * sha256:
> * sha1:
> 
> Note this redundancy, which can be checked for consistency:
> 
> * The Hash Length minus the length of the Hash Algorithm field (including the nul terminator) yields the size of the File Data Hash.
> * The length of a hash based on the Hash Algorithm yields the size of the File Data Hash.
> 
> 3.3. File Data Hash
> 
> This is a hash of the file data that was used to compute the Signature.
> 
> The length and hash algorithm are determined by the Hash Algorithm field.
> 
> 3.1. File Name Length
> 
> This is a 4-byte integer representing the length of the file name, including the nul terminator.  The maximum value is MAXPATHLEN +1?
> 
> Note that there is redundancy, in that the file name is nul terminated. This can be checked for consistency.
> 
> 3.2. File Name
> 
> This is a nul terminated string representing the name of the file that was measured.
> 
> The length is determined by the File Name Length.
> 
> 3.3. Signature Length
> 
> This is a 4-byte integer representing the total length of the Signature Header and Signature fields.  The value may be zero, indicating that those two fields are not present.
> 
> 3.4. Signature Header
> 
> This field is fixed at 9 bytes, consisting of 5 fields.
> 3.4.1. Signature Type
> 
> This is a 1-byte field.  The value is 0x03.
> 
> Question:  What are the valid values and meanings.  How does the type affect the other fields.

The whole signature data is part of the xattr data. This is actually 
not the signature type, but the xattr type defined in:
security/integrity/integrity.h as:

enum evm_ima_xattr_type {
	IMA_XATTR_DIGEST = 0x01,
	EVM_XATTR_HMAC,
	EVM_IMA_XATTR_DIGSIG,
	IMA_XATTR_DIGEST_NG,
	IMA_XATTR_LAST
};

So the only value is 3 for an event with signature.

> 
> Question:  Is the signature algorithm encoded here, or anywhere, or is RSA assumed?
> 

I guess the version field could identify the algorithm, currently
asymmetric_verify function defined in security/integrity/digsig_asymmetric.c
uses the signature_v2_hdr and RSA is hardcoded as:

pks.pkey_algo = "rsa";

> 3.4.2. Signature Version
> 
> This is a 1-byte field.  The value is 0x02.
> 
> Question:  What are the valid values and meanings.  How does the version affect the other fields.

Only 1 and 2 are valid right now. In function integrity_digsig_verify:

switch (sig[1]) {
case 1:
	/* v1 API expect signature without xattr type */
	return digsig_verify(keyring[id], sig + 1, siglen - 1,
			     digest, digestlen);
case 2:
	return asymmetric_verify(keyring[id], sig, siglen,
				 digest, digestlen);
}

So, for 1, it skips over the xattr type (EVM_IMA_XATTR_DIGSIG).
The rest is interpreted by digsig_verify in lib/digsig.c as of type
struct signature_hdr defined in include/linux/digsig.h

struct signature_hdr {
	uint8_t		version;	/* signature format version */
	uint32_t	timestamp;	/* signature made */
	uint8_t		algo;
	uint8_t		hash;
	uint8_t		keyid[8];
	uint8_t		nmpi;
	char		mpi[0];
} __packed;

> 
> 3.4.3. Hash Algorithm
> 
> This is a 1-byte field representing the hash algorithm used for the File Data Hash.  The legal values are:
> 
> * 0x02: SHA-1
> * 0x04: SHA-256

these are defined by the crypto subsystem in 
include/uapi/linux/hash_info.h:

enum hash_algo {
	HASH_ALGO_MD4,
	HASH_ALGO_MD5,
	HASH_ALGO_SHA1,
	HASH_ALGO_RIPE_MD_160,
	HASH_ALGO_SHA256,
	HASH_ALGO_SHA384,
	HASH_ALGO_SHA512,
	HASH_ALGO_SHA224,
	HASH_ALGO_RIPE_MD_128,
	HASH_ALGO_RIPE_MD_256,
	HASH_ALGO_RIPE_MD_320,
	HASH_ALGO_WP_256,
	HASH_ALGO_WP_384,
	HASH_ALGO_WP_512,
	HASH_ALGO_TGR_128,
	HASH_ALGO_TGR_160,
	HASH_ALGO_TGR_192,
	HASH_ALGO_SM3_256,
	HASH_ALGO__LAST
};

> 
> Note that there is redundancy, in that this field must be consistent with the Hash Algorithm field on the Template Data.
> 
> 3.4.4. Public Key Identifier
> 
> This is a 4-byte field that identifies the public key.  It is the last 4 bytes of the key's X.509 certificate Subject Key Identifier.
> 
> 3.4.5. Signature Size
> 
> This is a 2-byte integer representing the size of the Signature field.
> 
> Question:  What are the legal values?  1024 and 2048?  Others?

This one is defined by the signature. For RSA, the key determines the
resulting signature size. When writing the xattr, it is set to the return value
of RSA_private_encrypt:

From: https://linux.die.net/man/3/rsa_private_encrypt
>#include <openssl/rsa.h>
>
>int RSA_private_encrypt(int flen, unsigned char *from,
>   unsigned char *to, RSA *rsa, int padding);
>
>RSA_private_encrypt() returns the size of the signature
>(i.e., RSA_size(rsa)).

From: https://linux.die.net/man/3/rsa_size
>#include <openssl/rsa.h>
>
>int RSA_size(const RSA *rsa);
>
>This function returns the RSA modulus size in bytes. It can be 
>used to determine how much memory must be allocated for an
>RSA encrypted value.

Mehmet

Re: [Linux-ima-devel] IMA SHA-1 log format "specification"

[Ken G. <kg...@li...>]

On 7/17/2017 7:26 PM, Mehmet Kayaalp wrote:
> 
>>
>> Question:  What is the maximum number of event records?
> 
> There is no limit and the number is stored in a long field.

1 - Long is platform dependent, right?

2 - If an attacker sends a long with 0xffffffff records, or 0xfffffff 
ffffffff records, the server should not blindly try to malloc that much 
memory.

>> This is a 4-byte integer representing the length of the Template Name field.
>>
>> Question:  What is the maximum length?
> 
> in security/integrity/ima/ima_template.c
> #define MAX_TEMPLATE_NAME_LEN 15

I'm looking for a guaranteed maximum.  I don't want a server to break
if the client side code changes.

>> 3.4.1. Signature Type
>>
>> This is a 1-byte field.  The value is 0x03.
>>
>> Question:  What are the valid values and meanings.  How does the type affect the other fields.
> 
> The whole signature data is part of the xattr data. This is actually
> not the signature type, but the xattr type defined in:
> security/integrity/integrity.h as:
> 
> enum evm_ima_xattr_type {
> 	IMA_XATTR_DIGEST = 0x01,
> 	EVM_XATTR_HMAC,
> 	EVM_IMA_XATTR_DIGSIG,
> 	IMA_XATTR_DIGEST_NG,
> 	IMA_XATTR_LAST
> };
> 
> So the only value is 3 for an event with signature.

I'm looking for a definition of 0x03, as well as any other values a 
server might receive.

> 
>> 3.4.2. Signature Version
>>
>> This is a 1-byte field.  The value is 0x02.
>>
>> Question:  What are the valid values and meanings.  How does the version affect the other fields.
> 
> Only 1 and 2 are valid right now. In function integrity_digsig_verify:

What are the meanings of 1 and 2 - something I could add to the 
specification.

>> 3.4.5. Signature Size
>>
>> This is a 2-byte integer representing the size of the Signature field.
>>
>> Question:  What are the legal values?  1024 and 2048?  Others?
> 
> This one is defined by the signature. For RSA, the key determines the
> resulting signature size. When writing the xattr, it is set to the return value
> of RSA_private_encrypt:

Understood, but what are the legal sizes that a server must handle.

Re: [Linux-ima-devel] IMA SHA-1 log format "specification"

[Mimi Z. <zo...@li...>]

On Fri, 2017-07-28 at 17:11 -0400, Ken Goldman wrote:
> On 7/17/2017 7:26 PM, Mehmet Kayaalp wrote:
> > 
> >>
> >> Question:  What is the maximum number of event records?
> > 
> > There is no limit and the number is stored in a long field.
> 
> 1 - Long is platform dependent, right?
> 
> 2 - If an attacker sends a long with 0xffffffff records, or 0xfffffff 
> ffffffff records, the server should not blindly try to malloc that much 
> memory.

Based on policy, files are measured and appended to the tail of the
measurement list.  From a design perspective of measure before use,
the number of elements in the measurement list can not be limited.  At
some point we might want to add support for saving the measurements
offline.

> >> This is a 4-byte integer representing the length of the Template Name field.
> >>
> >> Question:  What is the maximum length?
> > 
> > in security/integrity/ima/ima_template.c
> > #define MAX_TEMPLATE_NAME_LEN 15
> 
> I'm looking for a guaranteed maximum.  I don't want a server to break
> if the client side code changes.

As new template fields are defined, the maximum custom template name
length will change.  The template data is prefixed with a length.
 Unknown template records can be skipped.  Template field data is
prefixed with a length. Unknown fields can be ignored/skipped.

> 
> >> 3.4.1. Signature Type
> >>
> >> This is a 1-byte field.  The value is 0x03.
> >>
> >> Question:  What are the valid values and meanings.  How does the type affect the other fields.
> > 
> > The whole signature data is part of the xattr data. This is actually
> > not the signature type, but the xattr type defined in:
> > security/integrity/integrity.h as:
> > 
> > enum evm_ima_xattr_type {
> > 	IMA_XATTR_DIGEST = 0x01,
> > 	EVM_XATTR_HMAC,
> > 	EVM_IMA_XATTR_DIGSIG,
> > 	IMA_XATTR_DIGEST_NG,
> > 	IMA_XATTR_LAST
> > };
> > 
> > So the only value is 3 for an event with signature.
> 
> I'm looking for a definition of 0x03, as well as any other values a 
> server might receive.

The last field of the ima-sig ("d-ng|n-ng|sig") template includes the
file signature (0x03) in the measurement list.  When Thiago
Bauermann's "Appended signatures support for IMA appraisal" patch set
is upstreamed, it will introduce a new signature format named
IMA_MOD_SIG (0x05).

Mimi

> > 
> >> 3.4.2. Signature Version
> >>
> >> This is a 1-byte field.  The value is 0x02.
> >>
> >> Question:  What are the valid values and meanings.  How does the version affect the other fields.
> > 
> > Only 1 and 2 are valid right now. In function integrity_digsig_verify:
> 
> What are the meanings of 1 and 2 - something I could add to the 
> specification.
> 
> >> 3.4.5. Signature Size
> >>
> >> This is a 2-byte integer representing the size of the Signature field.
> >>
> >> Question:  What are the legal values?  1024 and 2048?  Others?
> > 
> > This one is defined by the signature. For RSA, the key determines the
> > resulting signature size. When writing the xattr, it is set to the return value
> > of RSA_private_encrypt:
> 
> Understood, but what are the legal sizes that a server must handle.