365 business PDF

Pdf - Sign

Codeunit 5523677 bdev.Pdf - Sign signs a PDF document digitally. A signature proves who issued the document and that nobody changed it afterwards - which is what makes a PDF invoice acceptable where a wet signature used to be required.

Version

bdev.Pdf - Sign has been introduced with 365 business PDF 20.6. Before that, signing from AL was only available on the obsolete bdev.Pdf API, although its obsoletion message already named Pdf - Sign as the replacement.

Code
    pdfSign: Codeunit "bdev.Pdf - Sign";

There are two ways to state which certificate to sign with:

a PDF Signing Configuration, which holds the certificate and its PIN inside Business Central. The certificate is maintained once, by whoever is allowed to, and your code never touches it.
a certificate of your own, passed as a Temp Blob together with its PIN.

Prefer the configuration. It keeps the certificate out of your code and out of your extension's data, and it is the same configuration a report selection uses, so a document you sign yourself carries the same signature as one the app signed during printing.

SignDocument(Codeunit, Record)

Signs a document with the certificate of a PDF Signing Configuration.

Code
    procedure SignDocument(var document: Codeunit "Temp Blob"; pdfSigningConfig: Record "bdev.Pdf Signing Config.")

Parameter	Type	Description
`document`	Codeunit "Temp Blob"	The PDF document. It is replaced by the signed document.
`pdfSigningConfig`	Record "bdev.Pdf Signing Config."	The signing configuration holding the certificate.

Example

Code
    procedure SignContract(var document: Codeunit "Temp Blob")
    var
        pdfSigningConfig: Record "bdev.Pdf Signing Config.";
        mySetup: Record "My Setup";
        pdfSign: Codeunit "bdev.Pdf - Sign";
    begin
        mySetup.Get();
        mySetup.TestField("Signing Configuration Code");
        pdfSigningConfig.Get(mySetup."Signing Configuration Code");

        pdfSign.SignDocument(document, pdfSigningConfig);
    end;

SignDocument(Codeunit, Code)

Signs a document with the certificate of the PDF Signing Configuration with the given code.

Code
    procedure SignDocument(var document: Codeunit "Temp Blob"; pdfSigningConfigCode: Code[20])

Parameter	Type	Description
`document`	Codeunit "Temp Blob"	The PDF document. It is replaced by the signed document.
`pdfSigningConfigCode`	Code[20]	Code of the signing configuration.

An unknown configuration leaves the document unsigned

When no signing configuration exists for the code, the document is returned unchanged and no error is raised - the same behavior the app shows during report processing, where a missing configuration must not break the print. Where the signature is the point of the operation, test it with SigningConfigExists first.

SignDocument(Codeunit, Codeunit, Text)

Signs a document with a certificate of your own.

Code
    procedure SignDocument(var document: Codeunit "Temp Blob"; certificate: Codeunit "Temp Blob"; certificatePin: Text)

Parameter	Type	Description
`document`	Codeunit "Temp Blob"	The PDF document. It is replaced by the signed document.
`certificate`	Codeunit "Temp Blob"	The certificate file.
`certificatePin`	Text	The PIN of the certificate.

Code
    procedure SignWithOwnCertificate(var document: Codeunit "Temp Blob")
    var
        mySetup: Record "My Setup";
        pdfSign: Codeunit "bdev.Pdf - Sign";
        certificate: Codeunit "Temp Blob";
    begin
        mySetup.Get();

        certificate.FromRecord(mySetup, mySetup.FieldNo("Certificate File"));

        pdfSign.SignDocument(document, certificate, mySetup."Certificate PIN");
    end;

The certificate leaves Business Central

The certificate and its PIN are sent to the PDF service to perform the signature. That is true for both ways of signing, but a certificate stored in a signing configuration at least never passes through your extension. Keep a certificate of your own out of ordinary fields - and out of your telemetry.

SigningConfigExists(Code)

States whether a PDF Signing Configuration exists for the code.

Code
    procedure SigningConfigExists(pdfSigningConfigCode: Code[20]): Boolean

Parameter	Type	Description
`pdfSigningConfigCode`	Code[20]	Code of the signing configuration.

Returns true when the configuration exists.

Use it to turn the silent no-op above into an error of your own, with a message that names your setup field rather than ours:

Code
    if (not pdfSign.SigningConfigExists(mySetup."Signing Configuration Code")) then
        Error(SigningConfigurationMissingErr, mySetup."Signing Configuration Code", mySetup.FieldCaption("Signing Configuration Code"));

Signing during report processing

You do not need this codeunit to sign a printed report: a signing configuration on the report selection does that. Two properties of the report path are worth knowing when you compare the two.

The app does not sign when the print intent is Print. A signature on a document that goes to a printer serves no purpose, and the app skips it. This codeunit signs whatever you hand it.
The report path signs after stationery, concatenation and document attachments have been applied, so that the signature covers the finished document. When you sign yourself, sign last for the same reason - any change after the signature invalidates it.