Repository navigation
Description
This is part of #8335.
Important
Blocked by:
This issue should integrate the real prepare/complete API provided by signerphp/pdf-signer. It must not create a competing LibreSign-specific PDF/CMS/PAdES implementation.
LibreSign currently completes PDF digital signing in one operation where the signing implementation has direct access to the private key.
External signing requires a different lifecycle:
prepare PDF/PAdES signature
-> produce the cryptographic input required by the signer
-> perform the private-key operation outside LibreSign
-> receive the signature result
-> finalize the PDF/PAdES signature
The private-key operation may later be performed by a CSC provider, an ICP-Brasil PSC provider, an HSM integration or a local-device bridge.
This issue integrates that lifecycle into LibreSign using the prepare/complete capability provided by signerphp/pdf-signer.
It must not add production interfaces or value objects that are used only by tests or reserved only for future work.
Goal
Implement a real external-signing lifecycle for PDF documents where:
- LibreSign prepares a PDF/PAdES signature without having the private key;
- the prepared result exposes the cryptographic input and algorithm information required by an external signer;
- an externally produced signature result can be returned to the PDF/PAdES implementation;
- LibreSign finalizes the document with that signature;
- the resulting PDF can be validated as a correctly signed document.
The private key must never be passed to the PDF/PAdES preparation/finalization component.
Architecture
The intended responsibility boundary is:
sequenceDiagram
participant L as LibreSign
participant E as PDF/PAdES signing engine
participant S as External signer
L->>E: Prepare external signature
E-->>L: Prepared signing operation
L->>S: Cryptographic signing input
S-->>L: Signature result
L->>E: Finalize prepared operation
E-->>L: Signed PDF
PDF/PAdES signing engine owns
- PDF signature preparation;
- incremental PDF updates;
ByteRange;- CMS/PAdES structures;
- signed attributes;
- use of the public signer certificate and certificate chain;
- algorithm information required by the signature format;
- state required to finalize the prepared operation;
- application of the returned cryptographic signature;
- finalization of the signed PDF.
External signer owns
- access to the private key;
- credential discovery;
- authorization required to use the key;
- the private-key cryptographic operation;
- returning the resulting signature.
The external signer must not need PDF/PAdES knowledge.
The PDF/PAdES implementation must not contain CSC, ICP-Brasil PSC, OAuth or provider-specific behavior.
Production code must have a real consumer
Any interface or value object introduced by this issue must be used by the production external PDF signing integration added by the same issue.
Do not add:
- a production interface with only test implementations;
- a value object used only by tests;
- a fake production or reusable test implementation;
- abstractions that exist only for a possible future provider.
Create only the abstractions required by the real integration with the signerphp/pdf-signer prepare/complete lifecycle.
Tests may use PHPUnit mocks, anonymous classes or other test-local doubles where necessary.
Public certificate information
The prepare operation must receive the public signer certificate information required to construct the PDF/PAdES signature.
The private key must not be included.
LibreSign should use the certificate representation required by the real signerphp/pdf-signer API.
Do not introduce a parallel LibreSign-specific certificate model unless LibreSign has a concrete application-level responsibility that requires it.
Do not store:
- private keys;
- PKCS#12/PFX credentials;
- passwords;
- provider credentials;
- OAuth tokens;
- provider secrets.
Signing algorithms
LibreSign should consume the cryptographic information exposed by the real signerphp/pdf-signer prepare operation.
Do not introduce a separate arbitrary signatureAlgorithm model in LibreSign unless the integration requires additional application-level information.
The external signing flow must preserve the algorithm information required by both:
- the PDF/CMS/PAdES preparation; and
- the external private-key operation.
This may include separate digest and signature algorithm information and, when required, algorithm parameters.
Provider capability negotiation remains outside this issue.
Prepared signing state
The prepare operation must return everything required to:
- perform the external cryptographic operation; and
- later finalize the same prepared PDF signature.
The prepared state must support the fact that preparation and finalization may happen in different HTTP requests or PHP processes.
It must therefore not depend on keeping runtime-only objects alive.
Do not store objects such as:
- service instances;
- PHP resources;
- closures;
- provider clients;
- other process-local state.
The internal finalization state must remain opaque outside the PDF/PAdES implementation.
The caller must not need to understand ByteRange, CMS, PDF objects or other PDF/PAdES internals.
LibreSign should persist or transport the prepared state using the representation exposed by signerphp/pdf-signer rather than reconstructing PDF/CMS state itself.
This issue does not define the database model that will later persist an external signing session.
External signing result
The result returned by the external private-key operation must be passed back using the format expected by the signerphp/pdf-signer prepare/complete lifecycle.
Do not introduce a LibreSign wrapper class only for architectural symmetry.
Create a value object only if LibreSign has a concrete application-level need for more than one value to safely represent the result.
Relationship with the current signing flow
The existing signing methods must continue working without behavior changes.
Do not migrate all current signing methods to the new lifecycle in this issue.
The existing synchronous flow may continue to use:
ISignEngineHandler
-> sign()
-> File
External signing introduces an additional path for PDF signing.
The implementation must not require existing signing methods to use the external lifecycle.
Relationship with SignerPHP
The generic external-signing prepare/complete lifecycle is tracked in:
signerphp/pdf-signer is responsible for the PDF/CMS/PAdES preparation and finalization logic.
LibreSign should consume that real API instead of implementing its own PDF/PAdES external-signing engine.
Implementation of this issue should wait until the upstream prepare/complete API is available.
Do not duplicate or wrap the upstream API unless LibreSign has a concrete application-level responsibility that requires it.
Tests
Tests must cover the real external PDF signing lifecycle through the signerphp/pdf-signer integration.
At minimum:
- prepare a PDF signature using a controlled test certificate;
- obtain the real cryptographic input returned by the signing library;
- perform the private-key operation using a controlled test key;
- return the resulting signature to the finalize operation;
- finalize the PDF;
- validate that the resulting PDF contains a valid digital signature.
Also verify that:
- the private key is not provided to the prepare/finalize component;
- existing PDF signatures are preserved when another signature is added;
- the prepared operation can be resumed without keeping the original PHP process alive;
- algorithm information used during preparation matches the external private-key operation;
- no network or real external signing provider is required by the automated tests;
- existing LibreSign signing behavior remains unchanged.
Do not duplicate low-level signerphp/pdf-signer unit tests in LibreSign.
Prefer DataProviders where multiple relevant integration cases can be covered without duplicating tests.
Do not add standalone fake engine classes only to satisfy the test suite.
Scope boundaries
Please keep this issue focused on integrating the real PDF/PAdES external-signing lifecycle.
Do not:
- implement CSC;
- implement ICP-Brasil PSC;
- add OAuth or provider authorization;
- add provider configuration;
- add provider assignment;
- add signing-session persistence;
- change frontend behavior;
- add controllers or public API routes;
- add a browser/native bridge;
- add PKCS#11 or hardware integration;
- migrate all existing signing methods;
- reimplement PDF, CMS or PAdES prepare/finalize logic in LibreSign;
- create speculative abstractions without a production consumer.
If the real integration requires a LibreSign contract or value object, add it only for a concrete application-level responsibility and cover it through the real lifecycle tests.
Why this helps #8335
This provides the first functional LibreSign integration required by external digital signing.
After this issue, LibreSign will be able to use the signing library to prepare a PDF/PAdES signature, delegate only the private-key operation and later finalize the document.
Future provider work can then focus on:
prepared cryptographic input
-> provider authorization
-> private-key operation
-> signature result
without implementing PDF/PAdES logic.
This keeps provider protocols and document-signing internals independent.
Done when
- LibreSign integrates the real
signerphp/pdf-signerprepare/complete lifecycle. - LibreSign can prepare a PDF/PAdES signature without access to the private key.
- The exact cryptographic input required by the signing library can be passed to an external signer.
- A returned signature value can be used to finalize the signed PDF.
- Public signer certificate information is provided as required by the signing library.
- Digest, signature algorithm and required algorithm parameters are preserved correctly through the integration.
- Prepared state can cross a PHP request/process boundary.
- PDF/PAdES internals remain hidden from the future provider layer.
- A controlled test key can perform the external private-key operation between prepare and finalize.
- The resulting PDF validates with a valid digital signature.
- Existing signatures are preserved when adding another signature.
- Existing LibreSign signing behavior remains unchanged.
- Automated tests require no real remote provider or network access.
- LibreSign does not duplicate PDF/CMS/PAdES prepare/finalize logic already provided by
signerphp/pdf-signer. - No production abstraction exists only for tests or hypothetical future use.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Start date
Target date
Projects
- StatusShow more project fields0. Backlog
Activity
[-]Add the external signing lifecycle contract[/-][+]Implement the external PDF signing lifecycle[/+][-]Implement the external PDF signing lifecycle[/-][+]Define the remote signing provider architecture[/+][-]Define the remote signing provider architecture[/-][+]Implement the external PDF signing lifecycle[/+]lfals commentedon Sep 17, 2026
Can I work on this?
vitormattos commentedon Sep 19, 2026
@lfals I need to think more about because have blocks to this issue.
vitormattos commentedon Sep 19, 2026
@lfals I reviewed this and made a few small changes to the description to make the blocker more explicit.
feat(signature): add internal resumable external PDF signing service