Builder

Namespace: Com\Tecnick\Pdf\Sign\Cms

final class Builder

Source: src/Cms/Builder.php:50

Native builder for a detached CAdES-BES CMS SignedData, suitable for a PAdES B-B signature (/SubFilter /ETSI.CAdES.detached). It assembles the SignerInfo with the mandatory signed attributes (content-type, message-digest, signing-time, and the ESS signing-certificate-v2 that plain openssl_pkcs7_sign() cannot add), signs the DER SET OF signed attributes with openssl_sign(), and encodes the ContentInfo. RSA and ECDSA keys are supported with SHA-256/384/512.

sign() covers the case where the private key is available in this process. When it is not, or when the content is too large to hold as a string, the two halves are available on their own: signaturePayload() returns the bytes a signer has to sign for a given SigningRequest, and buildFromSignature() turns those plus the signature into the CMS. sign() is implemented over both.

Methods

__construct()

public __construct(?Asn1 $asn1 = null, ?Certificate $certificate = null)

Parameters:

• $asn1 (?Asn1)
• $certificate (?Certificate)

Source: src/Cms/Builder.php:69

buildFromSignature()

Produce the CMS from a request and the signature over its signaturePayload().

The second half of sign(), for a signature produced elsewhere. The signature AlgorithmIdentifier is read from the signing certificate rather than from a private key, since there may be none in this process.

The signature is verified against the certificate before anything is emitted, so a signature over the wrong bytes, from the wrong key, or in the wrong encoding fails at the call.

public buildFromSignature(
    SigningRequest $request,
    string $signature,
    list<string> $chainCertsDer = [],
    callable|null $signatureTimestamp = null,
    string|SignatureEncoding $signatureEncoding = \Com\Tecnick\Pdf\Sign\Cms\SignatureEncoding::Der
): string

Parameters:

• $request (SigningRequest): The same request passed to signaturePayload().
• $signature (string): Signature over $this->signaturePayload($request).
• $chainCertsDer (list<string>): Additional certificates to embed, each as PEM or as DER.
• $signatureTimestamp (callable|null): Optional provider that receives the raw SignerInfo signature bytes and returns a DER-encoded RFC 3161 timestamp token (ContentInfo). When supplied, the token is embedded as the id-aa-signatureTimeStampToken unsigned attribute (PAdES B-T).
• $signatureEncoding (string|SignatureEncoding): Encoding of $signature. An ECDSA signature returned as the fixed-width r || s concatenation is converted to the DER form CMS requires when this is P1363.

Returns: string: DER-encoded CMS ContentInfo.

Throws:

• Exception: If the digest or certificate key type is unsupported, if the signature is empty, malformed, or does not verify, or if encoding fails.

Source: src/Cms/Builder.php:187

sign()

Produce a detached CAdES-BES CMS SignedData over the given content.

public sign(
    string $data,
    string $signerCertDer,
    OpenSSLAsymmetricKey $privateKey,
    list<string> $chainCertsDer,
    string|DigestAlgorithm $digestAlgorithm,
    int $signingTime,
    callable|null $signatureTimestamp = null,
    bool $includeSigningTime = true,
    array<array-key,string> $extraSignedAttributes = []
): string

Parameters:

• $data (string): Detached content bytes (the signed data).
• $signerCertDer (string): DER of the signing certificate.
• $privateKey (OpenSSLAsymmetricKey): Signing private key (RSA or EC).
• $chainCertsDer (list<string>): Additional certificates to embed, each as PEM or as DER. Every entry is parsed.
• $digestAlgorithm (string|DigestAlgorithm): Digest algorithm name or enum case.
• $signingTime (int): Unix timestamp for the signing-time attribute.
• $signatureTimestamp (callable|null): Optional provider that receives the raw SignerInfo signature bytes and returns a DER-encoded RFC 3161 timestamp token (ContentInfo). When supplied, the token is embedded as the id-aa-signatureTimeStampToken unsigned attribute (PAdES B-T).
• $includeSigningTime (bool): Whether to add the CMS signing-time signed attribute. The legacy (ISO 32000-1) profile includes it; PAdES-BASELINE forbids it (ETSI EN 319 142-1) and carries the time in the /M signature dictionary entry instead.
• $extraSignedAttributes (array<array-key,string>): Additional signed attributes as OID => DER-encoded attribute value, for a profile that requires one such as the CAdES signature-policy-identifier.

Returns: string: DER-encoded CMS ContentInfo.

Throws:

• Exception: If the digest or key is unsupported, or signing fails.

Source: src/Cms/Builder.php:101

signaturePayload()

Produce the bytes a signer has to sign.

The first half of sign() on its own, for a signer whose private key this process cannot reach: a hardware token, a smart card, or a remote signing service. It also serves a signer that holds the key but not the content, since the request carries the message digest rather than the content.

The result is the DER SET OF signed attributes defined by RFC 5652 section 5.4, which is what the signature covers. It is a pure function of the request, so buildFromSignature() derives the same bytes again rather than taking them from the caller.

public signaturePayload(SigningRequest $request): string

Parameters:

• $request (SigningRequest): Validated inputs for the signed attributes.

Returns: string: DER SET OF signed attributes, ready to be signed.

Throws:

• Exception: If the digest is unsupported or encoding fails.

Source: src/Cms/Builder.php:155