Signing Integration Guide

include(FetchContent)
FetchContent_Declare(
    LibreMiddleware
    GIT_REPOSITORY https://github.com/LibreSCRS/LibreMiddleware.git
    GIT_TAG        4.0.0
)
FetchContent_MakeAvailable(LibreMiddleware)

target_link_libraries(MyApp PRIVATE
    LibreSCRS::Signing
    LibreSCRS::Trust
    LibreSCRS::Plugin
    LibreSCRS::SmartCard
    LibreSCRS::Auth
)

cmake -B build -DFETCHCONTENT_SOURCE_DIR_LIBREMIDDLEWARE=/path/to/LibreMiddleware

#include <LibreSCRS/Auth/CredentialProvider.h>
#include <LibreSCRS/Plugin/CardPluginService.h>
#include <LibreSCRS/Secure/String.h>
#include <LibreSCRS/Signing/SigningRequest.h>
#include <LibreSCRS/Signing/SigningResult.h>
#include <LibreSCRS/Signing/SigningService.h>
#include <LibreSCRS/Signing/TsaProvider.h>
#include <LibreSCRS/SmartCard/CardSession.h>
#include <LibreSCRS/SmartCard/MonitorService.h>
#include <LibreSCRS/Trust/TrustConfig.h>
#include <LibreSCRS/Trust/TrustStoreService.h>

#include <iostream>

namespace lsc = LibreSCRS;

int main()
{
    // 1. Build the trust store. The factory is noexcept and returns a
    //    usable service even when the network is unreachable — bundled
    //    and (optionally) system anchors are available immediately while
    //    eager Trusted-List fetches run on internal worker threads.
    lsc::Trust::TrustConfig trustConfig;
    trustConfig.cacheDirectory = "/var/cache/myapp/tl-cache";
    // trustConfig.sources.push_back({...});   // optional EU LOTL / national TLs

    auto trustResult = lsc::Trust::TrustStoreService::create(std::move(trustConfig));
    if (!trustResult) {
        std::cerr << "Trust store init failed: "
                  << trustResult.error().userMessage.defaultText << '\n';
        return 1;
    }
    std::shared_ptr<lsc::Trust::TrustStoreService> trust = *trustResult;

    // 2. Construct the SigningService. The TsaProvider is invoked at
    //    sign time for B-T / B-LT / B-LTA levels; staticTsa() is a
    //    convenience factory that always returns the same URL with no
    //    authentication. Pass a default-constructed TsaProvider{} to
    //    disable TSA — B-B signing still works, higher levels then fail
    //    with Status::TsaUnreachable.
    auto tsa = lsc::Signing::staticTsa("http://timestamp.digicert.com");
    auto signingService = std::make_shared<lsc::Signing::SigningService>(trust, std::move(tsa));

    // 3. Discover a card plugin + open a session. CardPluginService scans
    //    the configured plugin directory; MonitorService observes PC/SC
    //    events. Real apps subscribe to MonitorService and look up a
    //    plugin via findPluginForCard(atr) once a card has arrived; the
    //    helpers below collapse that flow into a single app-specific
    //    bootstrap step.
    lsc::Plugin::CardPluginService plugins{"/usr/local/lib/librescrs/plugins"};
    lsc::SmartCard::MonitorService monitor;
    auto session = openFirstSession(monitor, plugins);   // app-specific helper
    if (!session) {
        std::cerr << "No card available\n";
        return 1;
    }
    auto atr = session->atr();                            // std::span<const std::uint8_t>
    auto cardPlugin = plugins.findPluginForCard(atr);
    if (!cardPlugin) {
        std::cerr << "No plugin matches this card's ATR\n";
        return 1;
    }

    // 4. Build the signing request. The engine reads from inputFile and
    //    writes the signed payload to outputFile — there is no
    //    byte-buffer ingestion seam on the public API.
    auto request = lsc::Signing::SigningRequest::Builder{}
                       .inputFile("document.pdf")
                       .outputFile("document-signed.pdf")
                       .format(lsc::Signing::SignatureFormat::Pades)
                       .level(lsc::Signing::SignatureLevel::B_T)
                       .build();

    // 5. PIN provider — invoked by the service when the card requires it.
    //    The provider receives an AuthRequirement describing what to
    //    collect and returns a CredentialResult. In a GUI host this
    //    typically pops a PIN dialog; in batch tools it reads from a
    //    secure prompt or an env var.
    lsc::Auth::CredentialProvider pinProvider =
        [](const lsc::Auth::AuthRequirement&) {
            lsc::Secure::String pin{"1234"};  // host-collected, cleansed on dtor
            return lsc::Auth::CredentialResult::ok({{"pin", std::move(pin)}});
        };

    // 6. Sign. The call blocks for the duration of the operation (PIN
    //    verify + card APDU sign + optional TSA round-trip). GUI hosts
    //    run this on a worker thread.
    auto result = signingService->sign(request, std::move(pinProvider), cardPlugin, session);

    if (result.status != lsc::Signing::SigningResult::Status::Ok) {
        std::cerr << "Signing failed: "
                  << result.userMessage.defaultText << '\n';
        return 1;
    }

    // 7. Success — the signed document is on disk at the path the engine
    //    wrote to (i.e. the outputFile() the request was built with).
    std::cout << "Signed: " << result.outputPath->string() << '\n';
    return 0;
}

SigningService(std::shared_ptr<Trust::TrustStoreService> trustService,
               TsaProvider tsa);

SigningResult sign(const SigningRequest& request,
                   Auth::CredentialProvider credentialProvider,
                   std::shared_ptr<Plugin::CardPlugin> cardPlugin,
                   std::shared_ptr<SmartCard::CardSession> session);

auto result = signingService->sign(request, pinProvider, cardPlugin, session);
if (result.status != LibreSCRS::Signing::SigningResult::Status::Ok) {
    using S = LibreSCRS::Signing::SigningResult::Status;
    switch (result.status) {
        case S::TrustStoreUnavailable:  /* TL fetch / config rejected     */ break;
        case S::InvalidRequest:         /* null plugin/session, empty cb  */ break;
        case S::UserCancelled:          /* provider returned cancel       */ break;
        case S::PinVerificationFailed:  /* wrong PIN                      */ break;
        case S::CardBlocked:            /* signing PIN blocked by card    */ break;
        case S::TsaUnreachable:         /* B-T+ requested, TSA failed     */ break;
        case S::SigningEngineError:     /* libresign / APDU pipeline      */ break;
        default: break;                 // append-only enum; keep default
    }
    log(result.userMessage.defaultText);
    if (result.diagnosticDetail) {
        log(*result.diagnosticDetail);
    }
}