{"id":13420835,"url":"https://github.com/OpenSC/libp11","last_synced_at":"2025-03-15T07:31:38.767Z","repository":{"id":5630734,"uuid":"6838886","full_name":"OpenSC/libp11","owner":"OpenSC","description":"PKCS#11 wrapper library","archived":false,"fork":false,"pushed_at":"2024-10-21T16:03:15.000Z","size":1225,"stargazers_count":308,"open_issues_count":40,"forks_count":188,"subscribers_count":36,"default_branch":"master","last_synced_at":"2024-10-23T10:16:06.670Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenSC.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-11-24T11:07:51.000Z","updated_at":"2024-10-23T07:17:34.000Z","dependencies_parsed_at":"2023-10-04T15:01:05.226Z","dependency_job_id":"d884a469-4e25-4fa5-b521-d5fb0625e5b2","html_url":"https://github.com/OpenSC/libp11","commit_stats":{"total_commits":736,"total_committers":81,"mean_commits":9.08641975308642,"dds":0.5774456521739131,"last_synced_commit":"89ccb1f097f56a0933f881af051422b8d67e457f"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSC%2Flibp11","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSC%2Flibp11/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSC%2Flibp11/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSC%2Flibp11/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenSC","download_url":"https://codeload.github.com/OpenSC/libp11/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242864305,"owners_count":20197689,"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":[],"created_at":"2024-07-30T22:01:42.431Z","updated_at":"2025-03-15T07:31:38.760Z","avatar_url":"https://github.com/OpenSC.png","language":"C","funding_links":[],"categories":["TODO scan for Android support in followings"],"sub_categories":[],"readme":"# Build state\n\n[![Tests](https://github.com/OpenSC/libp11/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenSC/libp11/actions/workflows/ci.yml)\n[![Coverity Scan Status](https://scan.coverity.com/projects/15472/badge.svg)](https://scan.coverity.com/projects/opensc-libp11)\n\n\n# Overview\n\nThis code repository produces two libraries:\n* libp11 provides a higher-level (compared to the PKCS#11 library)\ninterface to access PKCS#11 objects.  It is designed to integrate with\napplications that use OpenSSL.\n* pkcs11 engine plugin for the OpenSSL library allows accessing\nPKCS#11 modules in a semi-transparent way.\n\nThe wiki page for this project is at https://github.com/OpenSC/libp11/wiki\nand includes a bug tracker and source browser.\n\n## PKCS#11\n\nThe PKCS#11 API is an abstract API to perform operations on cryptographic objects\nsuch as private keys, without requiring access to the objects themselves. That\nis, it provides a logical separation of the keys from the operations. The\nPKCS #11 API is mainly used to access objects in smart cards and Hardware or Software\nSecurity Modules (HSMs). That is because in these modules the cryptographic keys\nare isolated in hardware or software and are not made available to the applications\nusing them.\n\nPKCS#11 API is an OASIS standard and it is supported by various hardware and software\nvendors. Usually, hardware vendors provide a PKCS#11 module to access their devices.\nA prominent example is the OpenSC PKCS #11 module which provides access to a variety\nof smart cards. Other libraries like NSS or GnuTLS already take advantage of PKCS #11\nto access cryptographic objects.\n\n## OpenSSL engines\n\nOpenSSL implements various cipher, digest, and signing features and it can\nconsume and produce keys. However plenty of people think that these features\nshould be implemented in separate hardware, like USB tokens, smart cards or\nhardware security modules. Therefore OpenSSL has an abstraction layer called\n\"engine\" which can delegate some of these features to different piece of\nsoftware or hardware.\n\nengine_pkcs11 tries to fit the PKCS#11 API within the engine API of OpenSSL.\nThat is, it provides a gateway between PKCS#11 modules and the OpenSSL engine API.\nOne has to register the engine with OpenSSL and one has to provide the\npath to the PKCS#11 module which should be gatewayed to. This can be done by editing\nthe OpenSSL configuration file, by engine specific controls,\nor by using the p11-kit proxy module.\n\nThe p11-kit proxy module provides access to any configured PKCS #11 module\nin the system. See [the p11-kit web pages](http://p11-glue.freedesktop.org/p11-kit.html)\nfor more information.\n\n\n# PKCS #11 module configuration\n\n## Copying the engine shared object to the proper location\n\nOpenSSL has a location where engine shared objects can be placed\nand they will be automatically loaded when requested. It is recommended\nto copy the engine_pkcs11 to that location as \"libpkcs11.so\" to ease usage.\nThis is handle by 'make install' of engine_pkcs11.\n\n\n## Using the engine from the command line\n\nIn systems with p11-kit-proxy engine_pkcs11 has access to all the configured\nPKCS #11 modules and requires no further OpenSSL configuration.\nIn systems without p11-kit-proxy you need to configure OpenSSL to know about\nthe engine and to use OpenSC PKCS#11 module by the engine_pkcs11. For that you\nadd something like the following into your global OpenSSL configuration file\n(often in ``/etc/ssl/openssl.cnf``).  This line must be placed at the top,\nbefore any sections are defined:\n\n```\nopenssl_conf = openssl_init\n```\n\nThis should be added to the bottom of the file:\n\n```\n[openssl_init]\nengines=engine_section\n\n[engine_section]\npkcs11 = pkcs11_section\n\n[pkcs11_section]\nengine_id = pkcs11\ndynamic_path = /usr/lib/ssl/engines/libpkcs11.so\nMODULE_PATH = opensc-pkcs11.so\ninit = 0\n```\n\nThe dynamic_path value is the engine_pkcs11 plug-in, the MODULE_PATH value is\nthe OpenSC PKCS#11 plug-in. The engine_id value is an arbitrary identifier for\nOpenSSL applications to select the engine by the identifier. In systems\nwith p11-kit-proxy installed and configured, you do not need to modify the\nOpenSSL configuration file; the configuration of p11-kit will be used.\n\nIf you do not update the OpenSSL configuration file you will need to\nspecify the engine configuration explicitly. The following line loads\nengine_pkcs11 with the PKCS#11 module opensc-pkcs11.so:\n\n```\nOpenSSL\u003e engine -t dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so\n         -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD \n         -pre MODULE_PATH:opensc-pkcs11.so\n```\n\n\n## Testing the engine operation\n\nTo verify that the engine is properly operating you can use the following example.\n\n```\n$ openssl engine pkcs11 -t\n(pkcs11) pkcs11 engine\n     [ available ]\n```\n\n## Using p11tool and OpenSSL from the command line\n\nThis section demonstrates how to use the command line to create a self signed\ncertificate for \"Andreas Jellinghaus\". The key of the certificate will be generated\nin the token and will not exportable.\n\nFor the examples that follow, we need to generate a private key in the token and\nobtain its private key URL. The following commands utilize p11tool for that.\n\n```\n$ p11tool --provider /usr/lib/opensc-pkcs11.so --login --generate-rsa --bits 1024 --label test-key\n$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-privkeys --login\n```\n\nNote the PKCS #11 URL shown above and use it in the commands below.\n\nTo generate a certificate with its key in the PKCS #11 module, the following commands commands\ncan be used. The first command creates a self signed Certificate for \"Andreas Jellinghaus\". The\nsigning is done using the key specified by the URL. The second command creates a self-signed \ncertificate for the request, the private key used to sign the certificate is the same private key\nused to create the request. Note that in a PKCS #11 URL you can specify the PIN using the \n\"pin-value\" attribute.\n\n```\n$ openssl\nOpenSSL\u003e req -engine pkcs11 -new -key \"pkcs11:object=test-key;type=private;pin-value=XXXX\" \\\n         -keyform engine -out req.pem -text -x509 -subj \"/CN=Andreas Jellinghaus\"\nOpenSSL\u003e x509 -engine pkcs11 -signkey \"pkcs11:object=test-key;type=private;pin-value=XXXX\" \\\n         -keyform engine -in req.pem -out cert.pem\n```\n\n\n## Engine controls\n\nThe supported engine controls are the following.\n\n* **SO_PATH**: Specifies the path to the 'pkcs11-engine' shared library \n* **MODULE_PATH**: Specifies the path to the pkcs11 module shared library \n* **PIN**: Specifies the pin code \n* **DEBUG_LEVEL**: Set the debug level: 0=emerg, 1=alert, 2=crit, 3=err, 4=warning, 5=notice (default), 6=info, 7=debug\n* **QUIET**: Do not print additional details \n* **LOAD_CERT_CTRL**: Load a certificate from token\n* **SET_USER_INTERFACE**: Set the global user interface\n* **SET_CALLBACK_DATA**: Set the global user interface extra data\n* **FORCE_LOGIN**: Force login to the PKCS#11 module\n* **RE_ENUMERATE**: re-enumerate the slots/tokens, required when adding/removing tokens/slots\n* **VLOG_A**: Set the logging callback\n\nAn example code snippet setting specific module is shown below.\n\n```\nENGINE_ctrl_cmd(engine, \"MODULE_PATH\",\n\t\t0, \"/path/to/pkcs11module.so\", NULL, 1);\n```\n\nIn systems with p11-kit, if this engine control is not called engine_pkcs11\ndefaults to loading the p11-kit proxy module.\n\n\n# Developer information\n\n## Thread safety in libp11\n\nlibp11 internally uses OS locking, and configures the PKCS#11 module to do\nthe same.\n\nAccess to the the PKCS#11 tokens and objects is via a pool of PKCS#11 sessions.\nThis allows concurrent usage of crypto operations in thread safe manner.\n\n## Submitting pull requests\n\nFor adding new features or extending functionality in addition to the code,\nplease also submit a test program which verifies the correctness of operation.\nSee tests/ for the existing test suite.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSC%2Flibp11","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenSC%2Flibp11","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSC%2Flibp11/lists"}