{"id":28577502,"url":"https://github.com/mastercard/libpkcs11shim","last_synced_at":"2025-06-11T00:38:51.463Z","repository":{"id":177001885,"uuid":"657034226","full_name":"Mastercard/libpkcs11shim","owner":"Mastercard","description":"A PKCS#11 shim library, that can log API calls and be used for troubleshooting and performance measurements of a PKCS#11 library.","archived":false,"fork":false,"pushed_at":"2025-03-14T12:52:44.000Z","size":169,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-14T13:39:19.443Z","etag":null,"topics":["debugging","logging","performance-analysis","pkcs11","profiling","shim"],"latest_commit_sha":null,"homepage":"","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/Mastercard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-06-22T07:08:51.000Z","updated_at":"2025-03-14T12:52:49.000Z","dependencies_parsed_at":"2024-12-04T11:22:03.916Z","dependency_job_id":"5e9d77a2-c8eb-45df-bbaa-30d61b63ca70","html_url":"https://github.com/Mastercard/libpkcs11shim","commit_stats":null,"previous_names":["mastercard/libpkcs11shim"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flibpkcs11shim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flibpkcs11shim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flibpkcs11shim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flibpkcs11shim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/libpkcs11shim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flibpkcs11shim/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177332,"owners_count":22817349,"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":["debugging","logging","performance-analysis","pkcs11","profiling","shim"],"created_at":"2025-06-11T00:37:59.309Z","updated_at":"2025-06-11T00:38:51.442Z","avatar_url":"https://github.com/Mastercard.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libpkcs11shim : a shim library for PKCS#11\n\n## Introduction\n\n`libpkcs11shim` is a shim library that you insert between an application and a target PKCS#11 library. This project is actually a fork on a small part of [OpenSC project on GitHub](https://github.com/OpenSC/OpenSC), called [`pkcs11-spy`](src/pkcs11/pkcs11-spy.c). In addition to `pkcs11-spy`, `libpkcs11shim` adds some capabilities:\n\n - cleaner log output\n - ability to capture logs in a multithreaded environment\n - ability to carry on capture upon fork of the calling process\n - provides a deferred logging capability, reducing significantly the impact on performance on a library being logged (at the cost of extra memory allocation)\n - microsecond resolution for API call, allowing to identify library performance problems\n - hides passphrase information by default (that can be overriden by an environment variable)\n\n## Download\nReleases are hosted on Github: https://github.com/Mastercard/libpkcs11shim/releases/\n\n## Usage\nTo use this library:\n- define `PKCS11SHIM` environment variable to contain the original PKCS#11 library full path;\n- in your application, set the path to the `libpkcs11shim.so` library as the PKCS#11 library to use;\n- run your program as usual.\n\n### options\nThe following environment variables can be defined, to adjust logging behaviour:\n\n- `PKCS11SHIM_OUTPUT`, when present, specifies a filename where the log entries should be written. Fi the file already exists, logs will be appended to it. If the filename contains `%p`, it will be replaced with the pid of the running process. When `PKCS11SHIM_OUTPUT` is not specified, output goes to `/dev/stderr`.\n- `PKCS11SHIM_CONSISTENCY`; when present, allows to adjust how consistent are logs, in a multithreaded environment:\n\n\t- `0` (basic)\n\t  Logs are directly written, from the same thread, to the output file. Logs are therefore **synchronous** with the thread execution. If several threads are running concurrently, log entries may overlap. The basic mode is **adequate for single-threaded executions**.\n\t- `1` (consistent callblocks)\n\t  Logs are still written from the same thread as the caller, but there is a mutex preventing log entries to overlap, within one calling block. As a consequence, log entries will never overlap for multithreaded executions. However, it has a **significant impact on performance**. **Use this mode for logging on multithreaded executions, where impact on performance is acceptable**, or if you absolutely need to print log entries synchronously with other output.\n\t- `2` (deferred)\n\t  Log entries are pushed to a queue. There is a queue worker that takes care of emptying the queue, in a separate thread. **This mode provides good performance, and guarantees that, in log output, no overlap may occur accross threads**. However it is memory-hungry, and log output is deferred, which means you can't rely on the log entry to be printed in sync with other output. Use this mode for logging on multithreaded execution, where impact on performance must be minimized, at the expense of memory consumption and loss of synchronicity between logs and other output.\n\t  Beware: **this mode may overflow memory, if writing to the output can't keep up with the rate of incoming messages**. You have been warned!\n\n- `PKCS11SHIM_REVEALPIN`, when present and set to `1`, `on`, `yes` or `true`, will reveal the PIN or passphrase passed to the `C_Login()` API call.\n- `PKCS11SHIM_PRESERVED_IS_A_STRING`, when present and set to `1`, `on`, `yes` or `true`, will cast the pReserved member of CK_C_INITIALIZE_ARGS struct as a string pointer. This is expected by NSS only, and should be used only in this circumstance. Setting the variable may lead to undefined behaviour if `pReserved ` doesn't point to a valid string.\n\n## Building\n\nTo build the library:\n 1. clone the repo from GitHub\n 2. From the repo directory, execute `./bootstrap.sh`\n 3. execute `./configure`. As usual, configure script contains several options that can be useful to better match your environment.\n 4. execute `make`\n 5. optionally, `make install`. The library is named `libpkcs11shim.so` and is deployed by default to `/usr/local/lib`.\n\n## Building with docker\n\nIt is possible to build the library artifacts using docker. there is a script called `./buildx.sh` that can perform multi-arch builds, for the following platforms:\n\n - `oraclelinux:7`, `oraclelinux:8` and `oraclelinux:9` ( RPM and tar.gz )\n - `amazonlinux:2023` ( RPM and tar.gz )\n - `debian:12` (\"bookworm\") ( DEB and tar.gz )\n - `ubuntu:22.04`,`ubuntu24:04` ( DEB and tar.gz )\n - `alpinelinux:3.21` ( APK with a dummy signature and tar.gz )\n\nYou need to have a working docker environment.\n\n - To build ubuntu:24.04 artifacts for the host architecture, use `./buildx.sh ubuntu2404`\n - To build ubuntu:24.04 artifacts in verbose mode, use `./buildx.sh -v ubuntu2404`\n - To build ubuntu:24.04 artifacts in very verbose mode, use `./buildx.sh -v ubuntu2404`\n - To build ubuntu:24.04 artifacts for amd64, use `./buildx.sh ubuntu2404/amd64` (you must have docker configured properly if this is not your host architecture)\n - To build ubuntu:24.04 artifacts for arm64, use `./buildx.sh ubuntu2404/arm64` (you must have docker configured properly if this is not your host architecture)\n - To build ubuntu:24.04 artifacts for arm64 and amd64, use `./buildx.sh ubuntu2404/all` (you must have docker configured properly if this is not your host architecture)\n - execute the script without arguments for further help.\n \n\n## Output format\n\n### Fields description\n\n- `[cnt]`: a unique counter that is monolithically and atomically increased for every use, followed by the API being invoked.\n- `[pid]`: process ID of the calling process\n- `[ppd]`: parent process ID of the calling process. This can be helpful when the application uses `fork()`; in which case, each process results in the creation of a separate log file.\n- `[tid]`: thread ID (platform-specific)\n- `[tic]`: timestamp when the PKCS\\#11 function is invoked (resolution: microsecond)\n- `[in ]`: input parameters to the API call. Please refer to the PKCS#11 standard for a description of the fields.\n- `[out]`: output parameters of the API call. Please refer to the PKCS#11 standard for a description of the fields.\n- `[toc]`: timestamp when the API call is returned (resolution: microsecond)\n- `[lap]`: elapsed time, in microseconds (i.e., `[toc] - [tic]`)\n- `[ret]`: the return code of the API call.\n\n### Samples\nEvery log entry looks like the following:\n```\n[cnt] 0000000000000020 - C_GetAttributeValue\n[pid] 230885\n[ppd] 230878\n[tid] 230885\n[tic] 2023-06-28 16:32:50.903681\n[in ] hSession = 0x8cb\n[in ] hObject = 0x470\n[in ] pTemplate[1]: \n      CKA_CLASS             0000000000000000 / 0\n[out] pTemplate[1]: \n      CKA_CLASS             0000000000000000 / 8\n[toc] 2023-06-28 16:32:50.903695\n[lap] 0.000014\n[ret] 0 CKR_OK\n```\n\nDepending on the content, `[in ]` and `[out]` may be enriched with additional information. In the following sample, one can see that for every template entry, `type` is displayed, as well as `ulValueLen` and `pLen`; in the response received, the value `-1` for `ulValueLen` is interpreted as `CK_UNAVALABLE_INFORMATION`.\n\n```\n[cnt] 0000000000000022 - C_GetAttributeValue\n[pid] 230885\n[ppd] 230878\n[tid] 230885\n[tic] 2023-06-28 16:32:50.903702\n[in ] hSession = 0x8cb\n[in ] hObject = 0x470\n[in ] pTemplate[29]: \n      CKA_TOKEN             0000000000000000 / 0\n      CKA_PRIVATE           0000000000000000 / 0\n      CKA_MODIFIABLE        0000000000000000 / 0\n      CKA_LABEL             0000000000000000 / 0\n      CKA_KEY_TYPE          0000000000000000 / 0\n      CKA_ID                0000000000000000 / 0\n      CKA_START_DATE        0000000000000000 / 0\n      CKA_END_DATE          0000000000000000 / 0\n      CKA_DERIVE            0000000000000000 / 0\n      CKA_DERIVE_TEMPLATE   0000000000000000 / 0\n      CKA_LOCAL             0000000000000000 / 0\n      CKA_KEY_GEN_MECHANISM 0000000000000000 / 0\n      CKA_ALLOWED_MECHANISMS  0000000000000000 / 0\n      CKA_ENCRYPT           0000000000000000 / 0\n      CKA_DECRYPT           0000000000000000 / 0\n      CKA_SIGN              0000000000000000 / 0\n      CKA_VERIFY            0000000000000000 / 0\n      CKA_WRAP              0000000000000000 / 0\n      CKA_WRAP_TEMPLATE     0000000000000000 / 0\n      CKA_UNWRAP            0000000000000000 / 0\n      CKA_UNWRAP_TEMPLATE   0000000000000000 / 0\n      CKA_SENSITIVE         0000000000000000 / 0\n      CKA_ALWAYS_SENSITIVE  0000000000000000 / 0\n      CKA_EXTRACTABLE       0000000000000000 / 0\n      CKA_NEVER_EXTRACTABLE 0000000000000000 / 0\n      CKA_CHECK_VALUE       0000000000000000 / 0\n      CKA_TRUSTED           0000000000000000 / 0\n      CKA_WRAP_WITH_TRUSTED  0000000000000000 / 0\n      CKA_VALUE_LEN         0000000000000000 / 0\n[out] pTemplate[29]: \n      CKA_TOKEN             0000000000000000 / 1\n      CKA_PRIVATE           0000000000000000 / 1\n      CKA_MODIFIABLE        0000000000000000 / 1\n      CKA_LABEL             0000000000000000 / 25\n      CKA_KEY_TYPE          0000000000000000 / 8\n      CKA_ID                0000000000000000 / 15\n      CKA_START_DATE        0000000000000000 / 8\n      CKA_END_DATE          0000000000000000 / 8\n      CKA_DERIVE            0000000000000000 / 1\n      CKA_DERIVE_TEMPLATE   0000000000000000 / -1 (CK_UNAVALABLE_INFORMATION)\n      CKA_LOCAL             0000000000000000 / 1\n      CKA_KEY_GEN_MECHANISM 0000000000000000 / 8\n      CKA_ALLOWED_MECHANISMS  0000000000000000 / 0\n      CKA_ENCRYPT           0000000000000000 / 1\n      CKA_DECRYPT           0000000000000000 / 1\n      CKA_SIGN              0000000000000000 / 1\n      CKA_VERIFY            0000000000000000 / 1\n      CKA_WRAP              0000000000000000 / 1\n      CKA_WRAP_TEMPLATE     0000000000000000 / 96\n      CKA_UNWRAP            0000000000000000 / 1\n      CKA_UNWRAP_TEMPLATE   0000000000000000 / 144\n      CKA_SENSITIVE         0000000000000000 / 1\n      CKA_ALWAYS_SENSITIVE  0000000000000000 / 1\n      CKA_EXTRACTABLE       0000000000000000 / 1\n      CKA_NEVER_EXTRACTABLE 0000000000000000 / 1\n      CKA_CHECK_VALUE       0000000000000000 / -1 (CK_UNAVALABLE_INFORMATION)\n      CKA_TRUSTED           0000000000000000 / 1\n      CKA_WRAP_WITH_TRUSTED  0000000000000000 / 1\n      CKA_VALUE_LEN         0000000000000000 / 8\n[toc] 2023-06-28 16:32:50.903757\n[lap] 0.000055\n[ret] 0 CKR_OK\n```\n\nThe following sample contains even more information, as the template is returned populated by the PKCS\\#11 library:\n\n```\n[cnt] 0000000000000023 - C_GetAttributeValue\n[pid] 230885\n[ppd] 230878\n[tid] 230885\n[tic] 2023-06-28 16:32:50.903759\n[in ] hSession = 0x8cb\n[in ] hObject = 0x470\n[in ] pTemplate[29]: \n      CKA_TOKEN             00000000018b7150 / 1\n      CKA_PRIVATE           00000000018b6630 / 1\n      CKA_MODIFIABLE        00000000018a82a0 / 1\n      CKA_LABEL             00000000018b9150 / 25\n      CKA_KEY_TYPE          00000000018a8260 / 8\n      CKA_ID                00000000018a8280 / 15\n      CKA_START_DATE        00000000018a81c0 / 8\n      CKA_END_DATE          00000000018a8120 / 8\n      CKA_DERIVE            00000000018adf30 / 1\n      CKA_DERIVE_TEMPLATE   0000000000000000 / 0\n      CKA_LOCAL             00000000018ade90 / 1\n      CKA_KEY_GEN_MECHANISM 00000000018addb0 / 8\n      CKA_ALLOWED_MECHANISMS  00000000018add10 / 0\n      CKA_ENCRYPT           00000000018adc30 / 1\n      CKA_DECRYPT           00000000018a8fa0 / 1\n      CKA_SIGN              00000000018a31b0 / 1\n      CKA_VERIFY            00000000018a3110 / 1\n      CKA_WRAP              00000000018a3030 / 1\n      CKA_WRAP_TEMPLATE     00000000018b89b0 / 96\n      CKA_UNWRAP            00000000018a2f90 / 1\n      CKA_UNWRAP_TEMPLATE   00000000018a3900 / 144\n      CKA_SENSITIVE         00000000018a8f80 / 1\n      CKA_ALWAYS_SENSITIVE  00000000018a8ee0 / 1\n      CKA_EXTRACTABLE       00000000018a8e00 / 1\n      CKA_NEVER_EXTRACTABLE 00000000018a8de0 / 1\n      CKA_CHECK_VALUE       0000000000000000 / 0\n      CKA_TRUSTED           00000000018a8d40 / 1\n      CKA_WRAP_WITH_TRUSTED  00000000018a8d20 / 1\n      CKA_VALUE_LEN         00000000018b9050 / 8\n[out] pTemplate[29]: \n      CKA_TOKEN             True\n      CKA_PRIVATE           True\n      CKA_MODIFIABLE        True\n      CKA_LABEL             00000000018b9150 / 25\n      74657374 2D32322D 6175672D 30335F61 65735772 61704B65 79\n       t e s t  - 2 2 -  a u g -  0 3 _ a  e s W r  a p K e  y\n      CKA_KEY_TYPE          CKK_AES            \n      CKA_ID                00000000018a8280 / 15\n      00000000  61 65 73 32 35 36 2D 31 36 36 30 32 36 37 38     aes256-16602678 \n      CKA_START_DATE        00000000018a81c0 / 8\n      00000000  30 30 30 30 30 30 30 30                          00000000        \n      CKA_END_DATE          00000000018a8120 / 8\n      00000000  30 30 30 30 30 30 30 30                          00000000        \n      CKA_DERIVE            False\n      CKA_DERIVE_TEMPLATE   0000000000000000 / -1 (CK_UNAVALABLE_INFORMATION)\n      CKA_LOCAL             True\n      CKA_KEY_GEN_MECHANISM True\n      CKA_ALLOWED_MECHANISMS  00000000018add10 / 0\n      CKA_ENCRYPT           False\n      CKA_DECRYPT           False\n      CKA_SIGN              False\n      CKA_VERIFY            False\n      CKA_WRAP              True\n      CKA_WRAP_TEMPLATE     00000000018b89b0 / 96\n      00000000  01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................\n      00000010  01 00 00 00 00 00 00 00 02 00 00 00 00 00 00 00  ................\n      00000020  00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00  ................\n      00000030  07 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................\n      00000040  01 00 00 00 00 00 00 00 05 01 00 00 00 00 00 00  ................\n      00000050  00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00  ................\n      CKA_UNWRAP            True\n      CKA_UNWRAP_TEMPLATE   00000000018a3900 / 144\n      00000000  03 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................\n      00000010  01 00 00 00 00 00 00 00 62 01 00 00 00 00 00 00  ........b.......\n      00000020  00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00  ................\n      00000030  01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................\n      00000040  01 00 00 00 00 00 00 00 02 00 00 00 00 00 00 00  ................\n      00000050  00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00  ................\n      00000060  07 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................\n      00000070  01 00 00 00 00 00 00 00 05 01 00 00 00 00 00 00  ................\n      00000080  00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00  ................\n      CKA_SENSITIVE         True\n      CKA_ALWAYS_SENSITIVE  True\n      CKA_EXTRACTABLE       False\n      CKA_NEVER_EXTRACTABLE True\n      CKA_CHECK_VALUE       0000000000000000 / -1 (CK_UNAVALABLE_INFORMATION)\n      CKA_TRUSTED           False                                     .               \n      CKA_WRAP_WITH_TRUSTED False                                       .               \n      CKA_VALUE_LEN         00000000018b9050 / 8\n      00000000  20 00 00 00 00 00 00 00                           .......        \n[toc] 2023-06-28 16:32:50.903833\n[lap] 0.000074\n[ret] 0 CKR_OK\n```\n\n## Authors\nEric Devolder\n`libpkcs11shim` is forked from `pkcs11-spy` of the [OpenSC project](https://github.com/OpenSC/OpenSC); original authors referred in this project and in relevant source files.\n\n## Licensing and warranty\nLicensed under [LGPL 2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html); please refer to the license terms for details about licensing and warranty.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Flibpkcs11shim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Flibpkcs11shim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Flibpkcs11shim/lists"}