diff --git a/README.en.md b/README.en.md index 9d88dacf845d00c634dab5b8de08f5ca93bb9ea2..be11b2215d2c445c4e74613fd7c78f2d426c6921 100644 --- a/README.en.md +++ b/README.en.md @@ -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 +- completeness: the library provide functions for all phases of the + remote attestation lifecycle; it supports both implicit and explicit + remote attestation. -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request -#### Gitee Feature +## EXPLICIT vs IMPLICIT ATTESTATION -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 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 ' 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 +``` + +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 -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 -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 -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 -e -a attest.txt +``` + +### Perform explicit RA: + +#### Steps (on the client) +1) run: +``` +$ attest_ra_client -q -s -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 -b -i \ + -p 0,1,2,3,4,5,6,7,8,9,10 +``` + +This time RA should fail. diff --git a/attest-tools-0.2.90.tar.gz b/attest-tools-0.2.90.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..28dc4fb3be04add80bcfff8b30c8e080afcdbc84 Binary files /dev/null and b/attest-tools-0.2.90.tar.gz differ diff --git a/attest-tools.spec b/attest-tools.spec new file mode 100644 index 0000000000000000000000000000000000000000..0124dea4d2d6c84ac9fba58bd5c0d04851f55fcd --- /dev/null +++ b/attest-tools.spec @@ -0,0 +1,88 @@ +name: attest-tools +Version: 0.2.90 +Release: 1 +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://gitee.com/openeuler/attest-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 to perform remote attestation with a quote +or a TPM key. + +%prep +%autosetup -n %{name}-%{version} -p1 +%setup -a 1 -n %{name}-%{version} + +%build +autoreconf -iv +%configure +make %{?_smp_mflags} + +%install +rm -rf $RPM_BUILD_ROOT +%make_install %{?_smp_mflags} + +%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 - 0.2.90 +- Bug fixes + +* Thu Dec 12 2019 Roberto Sassu - 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 - 0.1.0 +- First public release diff --git a/openssl_tpm2_engine-2.4.2.tar.gz b/openssl_tpm2_engine-2.4.2.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..b40b3f350192a4396468f339111a48704a51436f Binary files /dev/null and b/openssl_tpm2_engine-2.4.2.tar.gz differ