{"id":18320311,"url":"https://github.com/tpm2-software/tpm2-tss-engine","last_synced_at":"2025-04-12T11:49:34.667Z","repository":{"id":33473399,"uuid":"136935379","full_name":"tpm2-software/tpm2-tss-engine","owner":"tpm2-software","description":"OpenSSL Engine for TPM2 devices","archived":false,"fork":false,"pushed_at":"2024-10-10T14:01:50.000Z","size":320,"stargazers_count":156,"open_issues_count":30,"forks_count":101,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-03T11:11:13.813Z","etag":null,"topics":["crypto","esapi","esys","openssl","tpm","tpm2","tpm2-tss","tss2"],"latest_commit_sha":null,"homepage":"https://tpm2-software.github.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tpm2-software.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-11T14:09:00.000Z","updated_at":"2025-03-19T03:14:58.000Z","dependencies_parsed_at":"2024-06-19T16:02:47.976Z","dependency_job_id":"63a99643-feff-4b9e-b033-8432bb6810fd","html_url":"https://github.com/tpm2-software/tpm2-tss-engine","commit_stats":{"total_commits":193,"total_committers":38,"mean_commits":5.078947368421052,"dds":0.7357512953367875,"last_synced_commit":"dcc5477c2fafc059c270296b763cb2119b8ed02f"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-tss-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-tss-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-tss-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-tss-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tpm2-software","download_url":"https://codeload.github.com/tpm2-software/tpm2-tss-engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248564888,"owners_count":21125412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crypto","esapi","esys","openssl","tpm","tpm2","tpm2-tss","tss2"],"created_at":"2024-11-05T18:15:53.394Z","updated_at":"2025-04-12T11:49:34.634Z","avatar_url":"https://github.com/tpm2-software.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Linux Build Status](https://github.com/tpm2-software/tpm2-tss-engine/workflows/Linux%20Build%20Status/badge.svg)](https://github.com/tpm2-software/tpm2-tss-engine/actions)\n[![Code Coverage](https://codecov.io/gh/tpm2-software/tpm2-tss-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/tpm2-software/tpm2-tss-engine)\n[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/tpm2-software/tpm2-tss-engine.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/tpm2-software/tpm2-tss-engine/context:cpp)\n[![Coverity Scan](https://img.shields.io/coverity/scan/22247.svg)](https://scan.coverity.com/projects/tpm2-tss-engine)\n\n\n# Overview\nThe tpm2-tss-engine project implements a cryptographic engine for\n[OpenSSL](https://www.openssl.org) for\n[Trusted Platform Module (TPM 2.0)](https://trustedcomputinggroup.org/work-groups/trusted-platform-module/)\nusing the [tpm2-tss](https://www.github.com/tpm2-software/tpm2-tss) software\nstack that follows the Trusted Computing Groups (TCG) \n[TPM Software Stack (TSS 2.0)](https://trustedcomputinggroup.org/work-groups/software-stack/).\nIt uses the \n[Enhanced System API (ESAPI)](https://trustedcomputinggroup.org/wp-content/uploads/TSS_ESAPI_Version-0.9_Revision-04_reviewEND030918.pdf)\ninterface of the TSS 2.0 for downwards communication. It supports RSA decryption\nand signatures as well as ECDSA signatures.\n\nIf you are looking for a provider following the OpenSSL 3.0 provider API instead of the engine API, please head over to [tpm2-openssl](https://github.com/tpm2-software/tpm2-openssl)\n\n# Operations\n\n## Key hierarchies\nThe keys used by this engine are all located underneath an ECC restricted\nprimary storage decryption key. This key is created on each invocation (since\nECC key creation is faster than RSA's). Thus, no persistent SRK key need to be\npredeployed.\n\nThe authorization value for the storage hierarchie (the owner password) is\nassumed to be clear (of zero length). If this is not the case, it needs to be\nset using the engine ctrl.\n\n## Key types\nThe RSA keys are created with the ability to sign as well as to decrypt.\nThis allows all RSA keys to be used for either operation.\nNote: The TPM's RSA sign operation will enforce tagging payloads with an ASN.1\nencoded identifier of the used hash algorithm. This is incompatible with\nOpelSSL's RSA interface structures. Thus, the TPM2_RSA_Decrypt method is also\nused for signing operations which also requires decrypt capabilities to be\nactivated for this key.\n\nThe ECDSA keys are created as ECDSA keys with the ability to perform signature\noperations.\n\n# Build and install instructions\nInstructions to build and install tpm2-tss are available in the\n[INSTALL](INSTALL.md) file.\n\n# Usage\n\nFor additional usage examples, please consider the integration tests under\n`tests/*.sh`.\n\n## Engine information\nEngine informations can be retrieved using\n```\nopenssl engine -t -c tpm2tss\n```\n\n## Random data\nA set of 10 random bytes can be retrieved using\n```\nopenssl rand -engine tpm2tss -hex 10\nengine \"tpm2tss\" set.\nWARNING:esys:src/tss2-esys/esys_tcti_default.c:137:tcti_from_file() Could not load TCTI file: libtss2-tcti-default.so\nWARNING:esys:src/tss2-esys/esys_tcti_default.c:137:tcti_from_file() Could not load TCTI file: libtss2-tcti-tabrmd.so\n40ac9191079e490d17b7\nWARNING:esys:src/tss2-esys/esys_tcti_default.c:137:tcti_from_file() Could not load TCTI file: libtss2-tcti-default.so\nWARNING:esys:src/tss2-esys/esys_tcti_default.c:137:tcti_from_file() Could not load TCTI file: libtss2-tcti-tabrmd.so\n```\nNote: These warnings stem from the tpm2-tss libraries and are not an issue, as\nlong as a TPM connection is established afterwards by a different tcti.\n\n## RSA operations\n\n### RSA decrypt\nThe following sequence of commands creates an RSA key using the TPM, exports the\npublic key, encrypts a data file and decrypts it using the TPM:\n```\ntpm2tss-genkey -a rsa -s 2048 mykey\nopenssl rsa -engine tpm2tss -inform engine -in mykey -pubout -outform pem -out mykey.pub\nopenssl pkeyutl -pubin -inkey mykey.pub -in mydata -encrypt -out mycipher\nopenssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -decrypt -in mycipher -out mydata\n```\nAlternatively, the data can be encrypted directly with the TPM key using:\n```\nopenssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -encrypt -in mydata -out mycipher\n```\n\n### RSA sign\nThe following sequence of commands creates an RSA key using the TPM, exports the\npublic key, signs a data file using the TPM and validates the signature:\n```\nopenssl rsa -engine tpm2tss -inform engine -in mykey -pubout -outform pem -out mykey.pub\nopenssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -sign -in mydata -out mysig\nopenssl pkeyutl -pubin -inkey mykey.pub -verify -in mydata -sigfile mysig\n```\nAlternatively, the data can be validated directly using:\n`openssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -verify -in mydata -sigfile mysig`\nNote: `mydata` must not exceed the size of the RSA key, since these operation\ndo not perform any hashing of the input data.\n\n## ECDSA operations\nThe following sequence of commands creates an ECDSA key using the TPM, signs\na data file using the TPM and validates the signature:\n```\ntpm2tss-genkey -a ecdsa mykey\nopenssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -sign -in mydata -out mysig\nopenssl pkeyutl -engine tpm2tss -keyform engine -inkey mykey -verify -in mydata -sigfile mysig\n```\n\nTo export the public key use:\n\n```\nopenssl ec -engine tpm2tss -inform engine -in mykey -pubout -outform pem -out mykey.pub\n```\n\n## Self Signed certificate generate operation \nThe following sequence of commands creates self signed certificate using TPM\nkey. Openssl command sets tpm2tss as engine and generates a self signed\ncertificate based on provided CSR configuration information.\n```\n$ tpm2tss-genkey -a rsa rsa.tss\n$ openssl req -new -x509 -engine tpm2tss -key rsa.tss  -keyform engine -out rsa.crt\n```\n\n## Signing using restricted key\nSigning using a restricted ECDSA key is possible with the caveat that\nthe TPM must be used for the digest, so higher-level digest \u0026 sign\noperations must be used instead, e.g.:\n```\n$ openssl dgst -engine tpm2tss -keyform engine -sha256 -sign ${HANDLE} -out mysig mydata.txt\n```\nWhere `${HANDLE}` is the TPM persistent handle ID for the restricted\nkey created by an external tool (since tpm2tss-genkey doesn't support\ncreating restricted keys).\n\n# TLS and s_server\nThis engine can be used in all places where OpenSSL is used to create a TLS\nsecure channel connection. You have can specify the command\n```\n./tpm2tss-genkey -a rsa rsa.tss\nopenssl req -new -x509 -engine tpm2tss -key rsa.tss  -keyform engine  -out rsa.crt\nopenssl s_server -cert rsa.crt -key rsa.tss -keyform engine -engine tpm2tss -accept 8443\n```\n\nFor ECDSA keys however, the Hash algorithm needs to be specified because the TPM\ndoes not support SHA512. You can blacklisting SHA512 universally. That is\npossible via openssl.cnf. See the \"SignatureAlgorithms\" configuration file\ncommand on this page:\nhttps://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html\n\nNote: Usage of s_server with HSM-protected private keys is only supported on\nOpenSSL 1.1.0 and newer.\n\n## Development prefixes\nIn order to use this engine without `make install` for testing call:\n```\nexport LD_LIBRAY_PATH=${TPM2TSS}/src/tss2-{tcti,mu,sys,esys}/.libs\nexport PKG_CONFIG_PATH=$PWD/../tpm2-tss/lib\n./bootstrap\n./configure \\\n    CFLAGS=\"-I$PWD/../tpm2-tss/include\" \\\n    LDFLAGS=\"-L$PWD/../tpm2-tss/src/tss2-{esys,sys,mu,tcti}/.libs\"\nmake\nmake check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpm2-software%2Ftpm2-tss-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftpm2-software%2Ftpm2-tss-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpm2-software%2Ftpm2-tss-engine/lists"}