Enums, contracts and exceptions

A lookup page. Everything here is named somewhere else in the guide, in the place where it matters; this is where to come when you know the name and want the shape.

Enums

A closed set of values is an enum here rather than a string validated on every call, and every entry point that takes one also takes its backing value, so configuration can stay as plain strings and never has to import anything.

->profile(SignatureProfile::PadesBT)
->profile('pades-b-t')          // the same thing

The ones you pass in

Enum	Cases	Used by
SignatureProfile	legacy, pades-b-b, pades-b-t, pades-b-lt, pades-b-lta	Profiles
DigestAlgorithm	sha256, sha384, sha512	Configuration
CertificationLevel	no-changes, form-filling, annotations	Certification
FieldLockAction	all, include, exclude	Certification, behind Data\FieldLock
SealPage	first, last	Seals
FontSize	small, medium, large	Seals
ImageDriver	gd, imagick	Seals

The ones you read back

Enum	Cases	Reported by
ValidationFinding	sixteen, listed in Verifying signatures	$report->findings()
RevocationStatus	good, revoked, unknown	$signature->revocation
RevisionChange	signature-added, timestamp-added, security-store-written, annotations, form-fields, pages, catalog, actions, other	$signature->changesAfter
SigningEvent	signature.applied, timestamp.received, validation-material.skipped, validation.completed, validation.failed	Audit trail
ExtendExitCode	the status signet extend exits with	Command line

The ones that describe a format

Asn1Tag, CmsAttribute, Cipher, DigestOid, EncryptionAlgorithm, SealEncoding and StreamFilter name what a specification defines rather than a choice a caller makes. They are public because the classes returning them are, and there is rarely a reason to reach for one.

Contracts

Fourteen interfaces, and nothing binds them: Signet wires the default graph by hand and its constructor is where a replacement goes.

Contract	Replacing it buys
SignatureTransport	the TSA, OCSP and CRL calls, which is your SSRF surface
ProcessRunner	the only seam that starts a process
PdfSigner	the signer itself, which is how Testing\FakePdfSigner is installed
CertificateReader	how a certificate is parsed
SealRenderer	a seal of your own: a logo, a QR code, any layout
Encrypter	the key management and cipher the vault seals with
PdfSource	documents that are not local files
PdfDestination	somewhere to write that is not a path
SignatureValidator	the validator behind Signet::validate()
SignatureProducer	who makes the CMS, which is how a key on a token, in an HSM or behind a cloud service is used (two-phase signing)
SignatureVerifier	which implementation decides that a signature matches its bytes: the openssl binary by default, or Validation\NativeSignatureVerifier, which needs no process
DigestSignatureProducer	the same as SignatureProducer, taking the digest of the covered bytes rather than the bytes, which is what keeps a large document from being copied to be signed (0122)
SigningKey	where the private key is when it is not in the certificate: a token, an HSM, a cloud service. It is handed the signed attributes and answers with a raw signature (0120)
SecurityStoreContributor	what a signature policy adds to the Document Security Store beyond what PAdES defines. IcpBrasil\PolicyArtifacts is the one that ships (0132)

$signet = new Signet(
    config: $config,
    processes: $processRunner,
    transport: $transport,
    signer: $signer,
    certificateReader: $reader,
    verifier: $verifier,
    signingKey: $key,
    storeContributor: $contributor,
);

Seven of them are Signet constructor arguments, as above. SealRenderer, Encrypter, SignatureProducer and DigestSignatureProducer are constructor arguments of the classes holding them instead. PdfSource and PdfDestination are implemented and passed per call rather than substituted, and SignatureValidator is built inside Signet, so replacing it means building the graph yourself, which is what the boundary rules exist to allow (0100).

Exceptions

Twenty classes, one per failure mode, and every one implements Exceptions\SignetException, which extends Throwable. Catch the interface to handle the package's failures as a group.

Raised by	Class
Certificates	InvalidCertificatePasswordException, InvalidCertificateContentException, InvalidPFXException, InvalidPemContentException, InvalidX509PrivateKeyException, CertificateOutputNotFoundException
Documents	InvalidPdfFileException, FileNotFoundException, HasNoSignatureOrInvalidPkcs7Exception
Signing	SealPlacementException, SignatureFieldException, CertificationException, FieldLockException
Verifying	VerificationUnsupportedException, raised by the native verifier for a signature algorithm it cannot express rather than reporting the signature bad
The environment	MissingBinaryException, ProcessUnavailableException, ProcessRunTimeException
Network and storage	SignatureTransportException, EncryptionException
The interface itself	SignetException

InvalidCertificatePasswordException extends InvalidCertificateContentException, the class it used to arrive as, so code catching the general failure still works while code that wants to say "wrong password, ask again" can.

What each one means in practice, and what to do about it, is Troubleshooting.

Documents in and out

Class
Io\FileSource	a path
Io\StringSource	bytes in memory
Io\StreamSource	an open handle
Io\FileDestination	a directory or path to write to
Io\StreamDestination	an open handle to write to

What comes back

Class	Returned by
Data\SignedPdf	sign(), and complete()
Data\SigningReceipt	$signed->receipt(), carrying the digests, the sizes, the /ID and who signed. It holds no PDF, so it is what goes in a column
Data\SkippedMaterial	$receipt->skipped, one per piece of revocation evidence that was looked for and not embedded, with the reason
Data\PreparedSignature	prepare(), carrying the document, the byte range and the digest to be signed
Data\SignatureReport	validate()
Data\SignatureDetails	$report->latest(), and each entry of the report
Data\Signer	$report->signers(), and each link of a chain
Data\SignatureField	signatureFields()
Data\EncryptedCertificate	encryptCertificate(), carrying certificate, password and hash
Data\Certificate	the certificate readers
Data\RevisionDiff	$signature->changesAfter
Data\SecurityStore	$report->securityStore
Data\SecurityStoreEntry	what a Contracts\SecurityStoreContributor answers with, one per named entry the store carries beyond /Certs, /OCSPs and /CRLs
Data\SignaturePolicy	$signature->signaturePolicy, when the signer declared one
IcpBrasil\Data\Identity	$signer->icpBrasil
IcpBrasil\Data\Report	icpBrasil()

All of them are final readonly, so what you receive is what was measured.