diff --git a/README.en.md b/README.en.md deleted file mode 100644 index be11b2215d2c445c4e74613fd7c78f2d426c6921..0000000000000000000000000000000000000000 --- a/README.en.md +++ /dev/null @@ -1,363 +0,0 @@ -# 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 ' 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/README.md b/README.md deleted file mode 100644 index 6a928ed05b6f01914b7c407c3f8d22fd171d977d..0000000000000000000000000000000000000000 --- a/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# attest-tools - -#### 介绍 -A library that makes implementation of remote attestation easier - -#### 软件架构 -软件架构说明 - - -#### 安装教程 - -1. xxxx -2. xxxx -3. xxxx - -#### 使用说明 - -1. xxxx -2. xxxx -3. xxxx - -#### 参与贡献 - -1. Fork 本仓库 -2. 新建 Feat_xxx 分支 -3. 提交代码 -4. 新建 Pull Request - - -#### 码云特技 - -1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md -2. 码云官方博客 [blog.gitee.com](https://blog.gitee.com) -3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解码云上的优秀开源项目 -4. [GVP](https://gitee.com/gvp) 全称是码云最有价值开源项目，是码云综合评定出的优秀开源项目 -5. 码云官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help) -6. 码云封面人物是一档用来展示码云会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/attest-tools.spec b/attest-tools.spec index 82ae68d1cc73b06d0104089c60c935c0cb0a35df..b368cc64a8ef2dd3d43f642e455c1457e2356b3d 100644 --- a/attest-tools.spec +++ b/attest-tools.spec @@ -1,14 +1,13 @@ name: attest-tools -Version: 0.2.91 +Version: 0.2.92 Release: 1 Summary: Attestation tools Source0: https://gitee.com/openeuler/%{name}/repository/archive/v%{version}.tar.gz -Source1: https://git.kernel.org/pub/scm/linux/kernel/git/jejb/openssl_tpm2_engine.git/snapshot/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: autoconf automake libcurl-devel libtool openssl-devel BuildRequires: digest-list-tools json-c-devel libcurl-devel tss2-devel Requires: json-c curl tss2 @@ -31,7 +30,6 @@ This package includes the headers of the libraries. %prep %autosetup -n %{name}-%{version} -p1 -%setup -a 1 -n %{name}-%{version} %build autoreconf -iv @@ -41,6 +39,11 @@ make %{?_smp_mflags} %install rm -rf $RPM_BUILD_ROOT %make_install %{?_smp_mflags} +install -m 755 -d $RPM_BUILD_ROOT/etc/attest-tools/ek_ca_certs +install -m 755 -d $RPM_BUILD_ROOT/etc/attest-tools/privacy_ca_certs +install -m 755 -d $RPM_BUILD_ROOT/etc/sysconfig +install -m 644 etc/attest_ra_server %{buildroot}/etc/sysconfig/attest_ra_server +install -m 644 etc/attest_tls_server %{buildroot}/etc/sysconfig/attest_tls_server %post ldconfig @@ -53,6 +56,14 @@ rm -rf $RPM_BUILD_ROOT %files %defattr(-,root,root,-) +%dir %{_sysconfdir}/%{name} +%dir %{_sysconfdir}/%{name}/ek_ca_certs +%dir %{_sysconfdir}/%{name}/privacy_ca_certs +%{_sysconfdir}/%{name}/req_examples/* +%config(noreplace) %{_sysconfdir}/sysconfig/attest_ra_server +%config(noreplace) %{_sysconfdir}/sysconfig/attest_tls_server +%{_unitdir}/attest_ra_server.service +%{_unitdir}/attest_tls_server.service %{_libdir}/libenroll_client.so %{_libdir}/libverifier_ima_policy.so %{_libdir}/libskae.so @@ -77,11 +88,23 @@ rm -rf $RPM_BUILD_ROOT %{_bindir}/attest_certify.sh %{_bindir}/ekcert_read.sh %{_bindir}/attest_parse_json +%{_bindir}/get_pgp_keys.sh +%{_bindir}/generate_demoCA.sh %files devel %{_prefix}/include/attest-tools %changelog +* Wed Feb 10 2021 Roberto Sassu - 0.2.92-1 +- Remove dependency on openssl_tpm2_engine +- Add support for PGP keys +- Move configuration files to /etc/attest-tools +- Obtain CA files from openssl configuration +- Make primary key persistent +- Add systemd units and requirements examples +- Add SKAE DATA URL extension to CSR +- Bug fixes + * Fri Nov 13 2020 Roberto Sassu - 0.2.91-1 - Update algorithm for boot_aggregate calculation - Install includes diff --git a/openssl_tpm2_engine-2.4.2.tar.gz b/openssl_tpm2_engine-2.4.2.tar.gz deleted file mode 100644 index b40b3f350192a4396468f339111a48704a51436f..0000000000000000000000000000000000000000 Binary files a/openssl_tpm2_engine-2.4.2.tar.gz and /dev/null differ diff --git a/v0.2.91.tar.gz b/v0.2.91.tar.gz deleted file mode 100644 index 148b734b10dc7dd7e0e0ee38b1b9d88a04c1154b..0000000000000000000000000000000000000000 Binary files a/v0.2.91.tar.gz and /dev/null differ diff --git a/v0.2.92.tar.gz b/v0.2.92.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..c26967dcf903ff96b05d077aa9e7ea15c68ceb46 Binary files /dev/null and b/v0.2.92.tar.gz differ