364 lines
13 KiB
Markdown
364 lines
13 KiB
Markdown
# attest-tools
|
|
|
|
## INTRODUCTION
|
|
|
|
Managing the complete lifecycle of remote attestation can be very
|
|
complicate. A TSS library performs only part of the operations necessary
|
|
for the creation and verification of TPM objects. Other open source
|
|
solutions, such as IBM Attestation Client Server (ACS), have fixed purpose
|
|
and for this reason, they are difficult to customize and integrate in other
|
|
solutions.
|
|
|
|
attest-tools is a set of libraries and tools that can be used for managing
|
|
the complete lifecycle of remote attestation. Its advantages are:
|
|
|
|
- library API: main functions are exposed as a library: applications
|
|
wanting to provide Trusted Computing services can simply link this
|
|
library;
|
|
|
|
- modular design: variable parts, such as event log parsers or verifiers,
|
|
are modularized; attest-tools functionality can be easily extended with
|
|
third-part modules that support new event log format or new verifiers;
|
|
|
|
- simplicity: data to be processed and the status of the processing are
|
|
stored in contexts created by the applications; library functions
|
|
directly operate on these contexts;
|
|
|
|
- completeness: the library provide functions for all phases of the
|
|
remote attestation lifecycle; it supports both implicit and explicit
|
|
remote attestation.
|
|
|
|
|
|
|
|
## EXPLICIT vs IMPLICIT ATTESTATION
|
|
|
|
Explicit attestation means establishing a communication between a target
|
|
system and a verifier with the purpose of determining whether the former
|
|
satisfies requirements of the latter. It is called explicit because the
|
|
goal of the communication is explicitly to attest a system.
|
|
|
|
Implicit attestation means that attestation is not the primary purpose of
|
|
the communication, but requirements can be verified as part of the
|
|
establishment or execution of another protocol (e.g. TLS). This alternative
|
|
should be preferable to the explicit one, as it is easier to integrate in
|
|
legacy products. On the other end, implicit attestation introduces
|
|
additional challenges such as having a fixed representation of the system
|
|
state that can be translated in one or multiple Platform Configuration
|
|
Register values.
|
|
|
|
attest-tools allows verifiers to perform both explicit and implicit
|
|
attestation.
|
|
|
|
|
|
|
|
## SOFTWARE ARCHITECTURE
|
|
|
|
attest-tools is composed of different libraries, RA client/server and TLS
|
|
client/server.
|
|
|
|
|
|
+---------------------+ +---------------------+
|
|
| attest-tools client | | attest-tools server |
|
|
+---------------------+ +----------------------
|
|
+----------+ +---------------------+ +---------------------+
|
|
| SKAE lib | | enroll client lib | | enroll server lib |
|
|
+----------+ +---------------------+ +---------------------+
|
|
+-------------------------------------------------------------------------+
|
|
| Application API (north-bound) |
|
|
| +--------------------+ +---------------------+ +------+ +-----+ +-----+ |
|
|
| | | | | | util | | pcr | | ctx | |
|
|
| | Event log | | Verifier | +------+ +-----+ +-----+ |
|
|
| | | | | +----------+ +-----+ |
|
|
| | | | | | ctx_json | | tss | |
|
|
| +--------------------+ +---------------------+ +----------+ +-----+ |
|
|
| base lib |
|
|
| Developer API (south-bound) |
|
|
+-------------------------------------------------------------------------+
|
|
+--------------------+ +---------------------+
|
|
| event log parsers | | event log verifiers |
|
|
| (plugins) | | (plugins) |
|
|
+--------------------+ +---------------------+
|
|
|
|
|
|
### Base lib - libattest.so
|
|
|
|
The base library is the main library of attest-tool and provides basic
|
|
services for the other more complex libraries. Essentially, it is
|
|
responsible to manage the data and verifier contexts, and verify the TPM
|
|
structure TPMS_ATTEST (which might contain a quote or a certify info). The
|
|
base library exposes a north-bound interface (Application API), intended to
|
|
be used by applications, and a south-bound interface (Developer API),
|
|
intended to be used by developers willing to extend the library
|
|
functionality.
|
|
|
|
|
|
### SKAE lib - libskae.so
|
|
|
|
The SKAE library is the library that manages the Subject Key Attestation
|
|
Evidence X.509 extension defined by TCG:
|
|
|
|
https://trustedcomputinggroup.org/wp-content/uploads/IWG_SKAE_Extension_1-00.pdf
|
|
|
|
It offers function for the creation and for the verification of the data
|
|
inside the extension.
|
|
|
|
|
|
### Enroll client lib - libenroll_client.so
|
|
|
|
The enrollment library for clients is responsible for performing the
|
|
preliminary steps necessary for remote attestation: obtaining an AK
|
|
certificate from the Privacy CA (implemented by attest_tools_server), for
|
|
obtaining a certificate for generated TPM keys (which can be used with
|
|
openssl_tpm2_engine), and for verifying a quote.
|
|
|
|
|
|
### Enroll server lib - libenroll_server.so
|
|
|
|
The enrollment library for servers is responsible to verify the requests
|
|
sent by clients and to issue certificates. The function to issue
|
|
certificates can be replaced with functions from applications' developers.
|
|
|
|
|
|
### Event log parsers - libeventlog_*.so
|
|
|
|
These libraries implement parsers for event logs. Currently, the following
|
|
parsers are available:
|
|
|
|
- BIOS event log (TCG v1.2 and v2.0);
|
|
|
|
- IMA event log (ima-ng and ima-sig templates, little endian).
|
|
|
|
|
|
### Event log verifiers - libverifier_*.so
|
|
|
|
These libraries implement verifiers for event logs. Each verifier might
|
|
take requirement from remote attestation verifiers, that must be satisfied
|
|
by the system being attested. Currently, the following verifiers are
|
|
available:
|
|
|
|
- BIOS: no checks are done at the moment; verifiers must explicitly specify
|
|
'always-true' as requirement to skip verification;
|
|
|
|
- IMA boot aggregate: calculates the digest of PCRs 0-7 obtained by
|
|
simulating the PCR extend operation with digests from the provided event
|
|
logs, and compares the result with the file digest in the first entry of
|
|
the IMA measurement list;
|
|
|
|
- IMA cp: obtains the path of the files from the IMA measurements list that
|
|
don't have signature, so that it can be transfered from systems being
|
|
attested to remote attestation verifiers;
|
|
|
|
- IMA sig: verifies the signature of files by using the content of
|
|
/etc/keys/x509_ima.der (must be provided) as certificate; verifier must
|
|
accept the public key by providing the certificate common name as a
|
|
requirement (in the future, it must check the validity of the
|
|
certificate);
|
|
|
|
- IMA policy: checks that the loaded IMA policy is one of the pre-defined
|
|
types (currently, only the 'exec-policy' type is defined); the desired
|
|
policy type must be specified by the verifier as a requirement;
|
|
|
|
- EVM key: checks that the EVM key is securely generated by the TPM (this
|
|
probably will change, as it seems that the TCG specification don't allow
|
|
the sensitive data origin bit to be set for sealed data blobs); it also
|
|
checks the PolicyPCR policy by using the event logs supplied by the
|
|
system being attested and the PCR selection provided by the verifier as a
|
|
requirement.
|
|
|
|
|
|
### RA client - attest_ra_client
|
|
|
|
Contacts RA server for AK/TLS certificate and for verifying a quote. It use
|
|
TCP/IP for communication.
|
|
|
|
|
|
### RA server - attest_ra_server
|
|
|
|
Processes requests from RA client It use TCP/IP for communication.
|
|
|
|
|
|
### TLS client - attest_tls_client
|
|
|
|
It establishes a TLS communication with the TLS server. Before establishing
|
|
TLS, it exchanges attestation data with the TLS server, so that both client
|
|
and server certificates (the SKAE extension) can be verified.
|
|
|
|
|
|
### TLS server - attest_tls_server
|
|
|
|
It receives requests from the TLS client. Before establishing TLS, it
|
|
exchanges attestation data with the TLS clients, so that both client and
|
|
server certificates (the SKAE extension) can be verified.
|
|
|
|
|
|
|
|
### DATA AND VERIFIER CONTEXTS
|
|
|
|
Passing data required to perform remote attestation might not be always
|
|
possible. For example, in order to perform the verification of the SKAE
|
|
extension in a certificate, an application might pass the skae_callback()
|
|
function as argument to SSL_CTX_set_verify(). OpenSSL provides the
|
|
definition of the callback function, and new parameters cannot be
|
|
introduced.
|
|
|
|
To overcome this issue, the data and verifier contexts concept has been
|
|
defined. A data context is a data structure that contains a linked list of
|
|
data pointers and length for each type of defined information (for example
|
|
a Privacy CA certificate, or the public part of an AK). The reader can have
|
|
a look to include/ctx.h for more details.
|
|
|
|
A verifier context contains the list of requirements provided by a remote
|
|
attestation verifier (these requirements are passed to the verifiers
|
|
plugins mentioned above). It also contains a log for each verification step
|
|
executed and its status. If a verification step failed, the first log
|
|
contains the reason of the failure, while previous logs (created by the
|
|
callers of the failed function) have as reason '<called function> failed'.
|
|
|
|
For the data context, the base library provides functions to add binary
|
|
data from buffers and files. It also provides functions to import/print
|
|
JSON strings. Support for other data format might be provided.
|
|
|
|
For the verifier context, the base library provides functions to set
|
|
verifier requirements, to set the mask of PCRs to check, and to print the
|
|
logs with the list and result of the executed verification steps.
|
|
|
|
An application might pass a NULL pointer as data or verifier context. In
|
|
this case a global context (defined in the library) is used. This is the
|
|
only way to use the skae_callback() for OpenSSL, as it is not possible to
|
|
add a data and verifier context as parameters.
|
|
|
|
|
|
|
|
## USE CASES
|
|
|
|
This section provides an overview of how attest-tools can accomplish most
|
|
common tasks. The reader can modify these examples to implement his
|
|
scenario.
|
|
|
|
|
|
### Create an AK and request a certificate:
|
|
|
|
#### Preliminary Steps (on the server)
|
|
1) use existing CA or generate a new custom CA (key: cakey.pem,
|
|
key password: 1234, cert: cacert.pem)
|
|
2) configure a TPM (a software TPM is sufficient)
|
|
3) install openssl_tpm2_engine
|
|
4) create a key and certificate for the TLS server
|
|
|
|
#### Preliminary Steps (on the client)
|
|
1) obtain the EK credential from TPM NVRAM: ekcert_read.sh -a sha256 \
|
|
-o ek_cert.pem
|
|
2) manually retrieve CA certificates of EK credential and add their path to
|
|
the file 'list', one per line
|
|
|
|
#### Steps (on the server)
|
|
1) generate verifier requirements:
|
|
```
|
|
$ attest_build_json -j reqs -k 'dummy|verify' -q '' req-dummy.json
|
|
```
|
|
2) execute:
|
|
```
|
|
$ attest_ra_server -r req-dummy.json
|
|
```
|
|
|
|
#### Steps (on the client)
|
|
1) execute:
|
|
```
|
|
$ attest_ra_client -a -s <attest_server FQDN>
|
|
```
|
|
|
|
Create a TPM key not bound to any PCR, save attestation data to attest.txt
|
|
and request a certificate:
|
|
|
|
#### Steps (on the client)
|
|
1) execute:
|
|
```
|
|
$ attest_ra_client -k -s <attest_server FQDN> -r attest.txt
|
|
```
|
|
|
|
### Perform implicit RA:
|
|
|
|
#### Steps (on the server)
|
|
1) execute:
|
|
```
|
|
$ attest_tls_server -k key.pem -c cert.pem -d ca_cert.pem \
|
|
-r req-dummy.json -S -V
|
|
```
|
|
|
|
#### Steps (on the client)
|
|
1) execute:
|
|
```
|
|
$ attest_tls_client -k tpm_key.pem -c key_cert.pem -d ca_cert.pem \
|
|
-s <attest_server FQDN> -e -a attest.txt
|
|
```
|
|
|
|
### Create a TPM key bound to PCRs 0-9,10 and request a certificate:
|
|
|
|
#### Preliminary Steps (on the client)
|
|
1) ensure that the client has a BIOS event log accessible from
|
|
/sys/kernel/security/tpm0/binary_bios_measurements
|
|
2) ensure that the client has a IMA event log accessible from
|
|
/sys/kernel/security/ima/binary_runtime_measurements and that no IMA
|
|
policy is loaded
|
|
3) copy the name of the file containing the Privacy CA certificate to
|
|
a file named 'list_privacy_ca'
|
|
|
|
|
|
#### Steps (on the server)
|
|
1) create verifier requirement:
|
|
```
|
|
$ attest_build_json -j reqs -k 'bios|verify' -q 'always-true' \
|
|
req-bios-ima.json
|
|
$ attest_build_json -j reqs -k 'ima_boot_aggregate|verify' -q '' \
|
|
req-bios-ima.json
|
|
```
|
|
2) execute:
|
|
```
|
|
$ attest_ra_server -r req-bios-ima.json -p 0,1,2,3,4,5,6,7,8,9,10
|
|
```
|
|
|
|
#### Steps (on the client)
|
|
1) run:
|
|
```
|
|
$ attest_ra_client -k -s <attest_server FQDN> -r attest.txt -b -i \
|
|
-p 0,1,2,3,4,5,6,7,8,9,10
|
|
```
|
|
|
|
### Perform implicit RA:
|
|
|
|
#### Steps (on the server)
|
|
1) execute:
|
|
|
|
```
|
|
$ attest_tls_servers -k key.pem -c cert.pem -d ca_cert.pem \
|
|
-r req-bios-ima.json -S -V -p 0,1,2,3,4,5,6,7,8,9,10
|
|
```
|
|
|
|
#### Steps (on the client)
|
|
1) execute:
|
|
```
|
|
$ attest_tls_client -k tpm_key.pem -c key_cert.pem -d ca_cert.pem \
|
|
-s <attest_server FQDN> -e -a attest.txt
|
|
```
|
|
|
|
### Perform explicit RA:
|
|
|
|
#### Steps (on the client)
|
|
1) run:
|
|
```
|
|
$ attest_ra_client -q -s <attest_server FQDN> -b -i \
|
|
-p 0,1,2,3,4,5,6,7,8,9,10
|
|
```
|
|
|
|
### Update PCR and perform again explicit RA:
|
|
|
|
#### Steps (on the client)
|
|
1) run:
|
|
```
|
|
$ tsspcrextend -halg sha1 -ha 10 -ic "test"
|
|
$ attest_ra_client -q -s <attest_server FQDN> -b -i \
|
|
-p 0,1,2,3,4,5,6,7,8,9,10
|
|
```
|
|
|
|
This time RA should fail.
|