SetSignProcessCNGKey

Security and signatures

Description

Attaches a named NCrypt private key and its DER-encoded X.509 certificate to a PDF signing process

The key is opened directly from the requested key storage provider, enabling TPM-backed, hardware-token, cloud KSP, and other CNG-only signing identities without exporting the private key

Syntax

Delphi

Function TPDFlib.SetSignProcessCNGKey(SignProcessID: Integer; Const CertificateDER: AnsiString; Const ProviderName, KeyName: WideString; UseMachineKey, AllowUI: Boolean): Integer;

ActiveX

Function PDFlib::SetSignProcessCNGKey(SignProcessID As Long, CertificateDER As Variant, ProviderName As String, KeyName As String, UseMachineKey As Long, AllowUI As Long) As Long

DLL

int DLSetSignProcessCNGKey(int InstanceID, int SignProcessID, const char* CertificateDER, int CertificateLength, const wchar_t* ProviderName, const wchar_t* KeyName, int UseMachineKey, int AllowUI);

Parameters

SignProcessID	Value returned by a `NewSignProcessFrom*` function
CertificateDER	Complete DER-encoded RSA or ECDSA X.509 certificate corresponding to the private key
ProviderName	Windows key storage provider name, or an empty string for `Microsoft Software Key Storage Provider`
KeyName	Persistent key name understood by the provider
UseMachineKey	True or nonzero to open the key from machine scope
AllowUI	True or nonzero to permit PIN, consent, or cloud-approval user interfaces from the provider

Return values

1	The identity configuration was attached to the process
0	The process id, certificate, or key name was invalid

Remarks

The key is opened when the sign process executes, and no private-key bytes enter library memory

When AllowUI is false, NCRYPT_SILENT_FLAG is applied to key opening and signing

The generated CMS signature is verified against CertificateDER before it is accepted, so a same-algorithm but mismatched key is rejected

ActiveX accepts a byte-array variant, and the DLL uses an explicit certificate length so embedded zero bytes are retained