packages/attest-tools
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial import

Browse Source 
Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
This commit is contained in:
Roberto Sassu 2020-07-09 10:54:07 +02:00
parent 923439883e
commit a125fd3211
3 changed files with 442 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

377
README.en.md
View File

@ -1,36 +1,363 @@
# attest-tools
#### Description
A library that makes implementation of remote attestation easier
## INTRODUCTION
#### Software Architecture
Software architecture description
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.
#### Installation
attest-tools is a set of libraries and tools that can be used for managing
the complete lifecycle of remote attestation. Its advantages are:
1. xxxx
2. xxxx
3. xxxx
- library API: main functions are exposed as a library: applications
wanting to provide Trusted Computing services can simply link this
library;
#### Instructions
- 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;
1. xxxx
2. xxxx
3. xxxx
- 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;
#### Contribution
1. Fork the repository
2. Create Feat_xxx branch
3. Commit your code
4. Create Pull Request
- completeness: the library provide functions for all phases of the
remote attestation lifecycle; it supports both implicit and explicit
remote attestation.
#### Gitee Feature
1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md
2. Gitee blog [blog.gitee.com](https://blog.gitee.com)
3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore)
4. The most valuable open source project [GVP](https://gitee.com/gvp)
5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help)
6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
## 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.

BIN
attest-tools-0.2.90.tar.gz Normal file
View File

Binary file not shown.

90
attest-tools.spec Normal file
View File

@ -0,0 +1,90 @@
name: attest-tools
Version: 0.2.90
Release: 1%{?dist}
Summary: Attestation tools
Source0: %{name}-%{version}.tar.gz
Source1: openssl_tpm2_engine-2.4.2.tar.gz
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
License: GPL-2.0
Url: https://github.com/euleros/digest-list-tools
BuildRequires: autoconf automake libcurl-devel libtool
BuildRequires: digest-list-tools json-c-devel libcurl-devel tss2-devel
Requires: json-c curl tss2
%if 0%{?suse_version}
BuildRequires: libopenssl-devel
%else
BuildRequires: openssl-devel
%endif
%description
This package includes the tools for configure the IMA Digest Lists extension.
%prep
%autosetup -n %{name}-%{version} -p1
%setup -a 1 -n %{name}-%{version}
%build
autoreconf -iv
%configure
make %{?_smp_mflags}
make check
%install
rm -rf $RPM_BUILD_ROOT
make install DESTDIR=$RPM_BUILD_ROOT
mkdir -p ${RPM_BUILD_ROOT}%{_sysconfdir}/ima/digest_lists
mkdir -p ${RPM_BUILD_ROOT}%{_mandir}/man1
%post
ldconfig
%postun
ldconfig
%clean
rm -rf $RPM_BUILD_ROOT
%files
%defattr(-,root,root,-)
%{_libdir}/libenroll_client.so
%{_libdir}/libverifier_ima_policy.so
%{_libdir}/libskae.so
%{_libdir}/libverifier_bios.so
%{_libdir}/libattest.so
%{_libdir}/libverifier_dummy.so
%{_libdir}/libenroll_server.so
%{_libdir}/libverifier_ima_cp.so
%{_libdir}/libverifier_ima_sig.so
%{_libdir}/libverifier_evm_key.so
%{_libdir}/libeventlog_ima.so
%{_libdir}/libverifier_ima_boot_aggregate.la
%{_libdir}/libverifier_ima_boot_aggregate.so
%{_libdir}/libeventlog_bios.so
%exclude %{_libdir}/*.la
%{_bindir}/attest_tls_client
%{_bindir}/attest_build_json
%{_bindir}/attest_tls_server
%{_bindir}/attest_ra_server
%{_bindir}/attest_ra_client
%{_bindir}/attest_create_skae
%{_bindir}/attest_certify.sh
%{_bindir}/ekcert_read.sh
%{_bindir}/attest_parse_json
%changelog
* Wed Jul 08 2020 Roberto Sassu <roberto.sassu@huawei.com> - 0.2.90
- Bug fixes
* Fri Dec 12 2019 Roberto Sassu <roberto.sassu@huawei.com> - 0.2.0
- Add quote protocol
- Add parser for TPM 2.0 event log
- Add evm_key and dummy verifiers
- Add creation of certificate for TPM key
- Add creation of symmetric key to be used with EVM
- Add ima-sig and ima-cp verifiers
* Fri Aug 16 2019 Roberto Sassu <roberto.sassu@huawei.com> - 0.1.0
- First public release