opencie-pkcs11

Imported from M0Rf30/opencie-pkcs11 (AGENTS.md). Install upstream with npx skills add M0Rf30/opencie-pkcs11. Copyright stays with the author.

Repository Guidelines

Project Overview

OpenCIE-PKCS11 is a cross-platform C++20 shared library implementing the PKCS#11 v2.40 cryptographic token interface for the Italian CIE (Carta d'Identita Elettronica) smart card. It also provides a signing SDK for PDF (CAdES/PAdES), XAdES XML, and PKCS#7/CMS signatures with RFC 3161 timestamping.

Single output artifact: libopencie-pkcs11.so (or .dll/.dylib), assembled from three internal static libraries. License: LGPL-3.0-or-later.

Architecture & Data Flow

Module Layering

libopencie-pkcs11 (shared)
  ├── pkcs11/    ← PKCS#11 C API surface + CIE card service provider
  ├── sign-sdk/  ← PDF/XAdES/CAdES signing + verification (static)
  └── shared/    ← crypto, PC/SC, IAS protocol, utilities (static)

All three are statically linked into the single shared library. Symbol visibility is controlled by linker scripts (linker/libopencie-pkcs11.map on Linux/Android, .exp on macOS) — only C_* PKCS#11 functions and cie_* extensions are exported. Everything else (OpenSSL, PoDoFo, libxml2 internals) is hidden to prevent symbol collisions with host applications.

Call Flow: PKCS#11 API to Smart Card

C_* function (pkcs11_functions.cpp)
  → pkcs11_guard (exception→CK_RV)
    → CSession → CSlot → CCardTemplate callbacks (TemplateFuncList)
      → CIEtemplate* implementations (cie_p11_template.cpp)
        → IAS protocol (shared/src/csp/ias.cpp) — PACE, Secure Messaging, APDU construction
          → PC/SC layer (safeConnection/safeTransaction → CToken → SmartCardTransport)
            → physical card (SCardTransmit)

Signing Flow

• PDF: bytes → PoDoFo PdfMemDocument → PdfSignature field placed → CIEPdfSigner::ComputeSignature() → CSignatureGenerator::Generate() → PKCS#7 embedded in /Contents
• XAdES: XML → libxml2 parse → QualifyingProperties + SignedInfo → C14N canonicalize → RSA sign → ds:Signature element
• CAdES: data → CSignatureGenerator::Generate() → SignerInfo + SignedData + optional TimeStampToken (RFC 3161)

Thread Safety

A single global p11Mutex (std::mutex) guards every C_* entry point. A background monitor thread watches PC/SC readers for card insertion/removal, acquiring the same mutex for slot updates. No session-level locking — per PKCS#11 spec, the application serializes per-session access.

Key Directories

Development Commands

# Configure (default: tests=true, portable=false)
meson setup build

# Build
meson compile -C build

# Run all tests
meson test -C build
# or directly:
./build/tests/opencie-tests

# Run tests by tag
./build/tests/opencie-tests "[base64]"
./build/tests/opencie-tests "[cache]"

# Run with sanitizers (as CI does)
meson setup build-asan -Db_sanitize=address,undefined -Db_lundef=false
meson test -C build-asan

# Cross-compile for aarch64
meson setup build-arm64 --cross-file toolchains/cross-aarch64.ini
meson compile -C build-arm64

# Cross-compile for Windows (MinGW)
meson setup build-win --cross-file toolchains/cross-clang-mingw.ini
meson compile -C build-win

# Cross-compile for Android arm64
meson setup build-android --cross-file toolchains/cross-android-arm64.ini
meson compile -C build-android

# Portable build (static libstdc++/libgcc)
meson setup build-portable -Dportable=true

# Clean
rm -rf build

Code Conventions & Common Patterns

Formatting

Google-style via .clang-format: 80-column limit, 2-space indent, BreakBeforeBraces: Attach, PointerAlignment: Left, IncludeBlocks: Regroup. Enforced by pre-commit hook (clang-format v19.1.7).

Naming

Error Handling

std::runtime_error
  └── logged_error        ← logs via LOG_ERR on construction (util_exception.h)
        ├── scard_error   ← carries ISO 7816 StatusWord (0x9000, 0x6300, etc.)
        └── windows_error ← wraps HRESULT

• PKCS#11 layer: p11_error(CK_RV) caught by pkcs11_guard → converted to CK_RV return code
• Assertion macro: ER_ASSERT(condition, message) throws logged_error on false
• Sign-SDK: __TRY/__CATCH macros catch multiple types, return CIE_SIGN_ERROR_UNEXPECTED
• Never throw raw integers. Legacy throw -1 was removed; use std::runtime_error or logged_error.

Memory & Buffer Patterns

• ByteArray: non-owning view (pointer + size), zero-copy slicing. Defined in shared/src/util/array.h.
• ByteDynArray: owning heap buffer (new[]/delete[]), RAII. Deep-copy on construction/assignment, move semantics supported.
• OpenSSL cleanup: OPENSSL_cleanse() on keys, IVs, PINs, session keys. EVP contexts freed via EVP_*_CTX_free() on all paths.
• RAII wrappers: std::unique_ptr<X509, decltype(&X509_free)> for OpenSSL objects, PinCleanser for PIN buffers, safeConnection/safeTransaction for PC/SC handles.
• ASN.1 trees: unique_ptr<CASNTag> ownership in CASNTagArray.

Platform Abstractions

• #ifdef _WIN32 / #else for: symbol export (__declspec(dllexport) vs __attribute__((visibility))), DllMain, WinSCard vs libpcsclite, user directories, process spawning
• #ifdef __ANDROID__: NFC transport via JNI, logcat logging
• Toolchain .ini files handle cross-compilation flags (-DNOMINMAX, -fpermissive for MinGW)

Include Conventions

• #pragma once (no #ifndef guards)
• Order: system/OpenSSL headers first, then project headers ("crypto/", "util/", "csp/")
• Headers are self-contained (include their own dependencies)

Key Typedefs

Important Files

Runtime/Tooling Preferences

Cross-Compilation Targets

Testing & QA

• Framework: Catch2 v3.14.0 (with Meson subproject fallback)
• Test executable: tests/opencie-tests
• Test files (11): test_array, test_tlv, test_crypto, test_cache_lib, test_md5, test_asn_parser, test_padding, test_ini_settings, test_properties, test_util, test_crypto_util
• Run: meson test -C build or ./build/tests/opencie-tests
• Tags: ./build/tests/opencie-tests "[base64]", "[cache]", "[crypto]", etc.
• CI sanitizers: AddressSanitizer + UBSan (-Db_sanitize=address,undefined), with lsan-suppressions.txt
• CI static analysis: clang scan-build, cppcheck, CodeQL, Semgrep (p/default + p/c rulesets)

Writing Tests

• Tests live in tests/test_*.cpp, one file per module
• Use Catch2 TEST_CASE + SECTION structure with descriptive string tags
• Test the shared library's internal units directly (crypto, cache, parsing) — no smart card hardware needed
• Follow existing patterns: #include <catch2/catch_test_macros.hpp>, CHECK/REQUIRE assertions
• RAII test fixtures preferred; no global test state

CI Matrix