Provider di chiavi — sgcSign

PROVIDER 1 / 10

`TsgcPFXKeyProvider`

File PFX / PKCS#12. Chiave locale protetta da password. Ideale per sviluppo, deployment di piccole dimensioni e qualsiasi flusso di lavoro in cui il certificato viene distribuito come singolo file .pfx/.p12.

Importato tramite Windows CNG con PKCS12_PREFER_CNG_KSP — la firma SHA-256/384/512 funziona indipendentemente dal CSP originale.
I file .pfx multi-cert vengono percorsi automaticamente finché non viene trovato il certificato con la chiave privata.

pfx.pas

var
  vPFX: TsgcPFXKeyProvider;
begin
  vPFX := TsgcPFXKeyProvider.Create(nil);
  try
    vPFX.FileName := 'certificate.pfx';
    vPFX.Password := 'mypassword';
    vPFX.LoadFromFile;
    // vSigner.KeyProvider := vPFX;
  finally
    vPFX.Free;
  end;
end;

PROVIDER 2 / 10

`TsgcPEMKeyProvider`

File PEM. PKCS#8 cifrato con supporto nativo PBES2 / PBKDF2 / AES-CBC, oltre al formato DEK-Info legacy per chiavi private RSA. Ideale per pipeline basate su OpenSSL.

BEGIN CERTIFICATE, BEGIN RSA PRIVATE KEY, BEGIN PRIVATE KEY, BEGIN ENCRYPTED PRIVATE KEY tutti supportati.
I PEM combinati (cert + chiave in un unico file) vengono rilevati automaticamente — lascia PrivateKeyFile vuoto.

pem.pas

var
  vPEM: TsgcPEMKeyProvider;
begin
  vPEM := TsgcPEMKeyProvider.Create(nil);
  try
    vPEM.CertificateFile := 'cert.pem';
    vPEM.PrivateKeyFile  := 'key.pem';
    vPEM.PrivateKeyPassword := 'secret';
    vPEM.LoadFromFile;
    // vSigner.KeyProvider := vPEM;
  finally
    vPEM.Free;
  end;
end;

PROVIDER 3 / 10

`TsgcWindowsCertStoreProvider`

Archivio certificati di Windows. Archivi della macchina locale e dell'utente corrente. Ideale per app desktop che usano certificati già emessi da AD, o qualsiasi deployment in cui Windows gestisce già il ciclo di vita del certificato.

La firma avviene tramite Windows CNG — la chiave privata non lascia mai l'archivio.
Selezione per sottostringa CN del subject o per thumbprint SHA-1.

winstore.pas

var
  vStore: TsgcWindowsCertStoreProvider;
begin
  vStore := TsgcWindowsCertStoreProvider.Create(nil);
  try
    vStore.StoreName := 'MY';
    vStore.StoreLocation := cslCurrentUser;
    vStore.SelectCertificateBySubject('My Company');
    // vSigner.KeyProvider := vStore;
  finally
    vStore.Free;
  end;
end;

PROVIDER 4 / 10

`TsgcPKCS11Provider`

PKCS#11 / token hardware. Smart card, token USB, HSM — SafeNet, YubiKey, Nitrokey, Thales. Richiesto per le firme elettroniche qualificate nella maggior parte delle giurisdizioni UE.

Meccanismi CKM_RSA_PKCS e CKM_ECDSA_SHA256 supportati.
Helper EnumerateSlots / EnumerateCertificates per scegliere lo slot corretto a runtime.

pkcs11.pas

var
  vTok: TsgcPKCS11Provider;
begin
  vTok := TsgcPKCS11Provider.Create(nil);
  try
    vTok.LibraryPath := 'C:\token\pkcs11.dll';
    vTok.SlotIndex := 0;
    vTok.PIN := '1234';
    vTok.CertificateLabel := 'MyCert';
    vTok.Connect;
    // vSigner.KeyProvider := vTok;
  finally
    vTok.Free;
  end;
end;

PROVIDER 5 / 10

`TsgcAzureTrustedSigningProvider`

Azure Trusted Signing. Il servizio di firma del codice qualificato di Microsoft. Authenticode senza acquistare un certificato EV — Microsoft possiede il certificato e fornisce la chiave di firma.

Credenziali OAuth2 client — Tenant ID + Client ID + Client Secret.
Le chiavi private risiedono interamente in Azure, mai sull'agente di build.

azure-ts.pas

var
  vAzure: TsgcAzureTrustedSigningProvider;
begin
  vAzure := TsgcAzureTrustedSigningProvider.Create(nil);
  try
    vAzure.TenantId := 'your-tenant-id';
    vAzure.ClientId := 'your-client-id';
    vAzure.ClientSecret := 'your-client-secret';
    vAzure.AccountName := 'mySigningAccount';
    vAzure.CertificateProfileName := 'default';
    vAzure.Connect;
    // vSigner.KeyProvider := vAzure;
  finally
    vAzure.Free;
  end;
end;

PROVIDER 6 / 10

`TsgcAWSKMSKeyProvider`

AWS Key Management Service. Il servizio di custodia delle chiavi di Amazon supportato da HSM. Abbinalo a un certificato emesso da AWS per firmare in cloud senza esporre la chiave privata.

Autenticazione AWS Signature Version 4, calcolata in-process.
KeyId accetta key ID, key ARN o alias ARN.

aws-kms.pas

var
  vAWS: TsgcAWSKMSKeyProvider;
begin
  vAWS := TsgcAWSKMSKeyProvider.Create(nil);
  try
    vAWS.AccessKeyId := 'AKIAIOSFODNN7EXAMPLE';
    vAWS.SecretAccessKey := 'wJalrXUtnFEMI/K7MDENG/...';
    vAWS.Region := 'us-east-1';
    vAWS.KeyId := 'arn:aws:kms:us-east-1:...:key/my-key';
    vAWS.Connect;
    // vSigner.KeyProvider := vAWS;
  finally
    vAWS.Free;
  end;
end;

PROVIDER 7 / 10

`TsgcGCloudKMSKeyProvider`

Google Cloud KMS. Stesso modello operativo di AWS KMS. Il file JSON del service account autentica tramite scambio JWT per ottenere un token di accesso OAuth2, poi firma tramite l'API Cloud KMS.

ProjectId + Location + KeyRing + Key + Version — corrisponde 1:1 alla gerarchia delle risorse GCP.
Solo chiavi KMS asimmetriche — supportate da HSM quando disponibile, altrimenti protette via software.

gcloud-kms.pas

var
  vGCloud: TsgcGCloudKMSKeyProvider;
begin
  vGCloud := TsgcGCloudKMSKeyProvider.Create(nil);
  try
    vGCloud.ProjectId := 'my-project';
    vGCloud.LocationId := 'global';
    vGCloud.KeyRingId := 'my-key-ring';
    vGCloud.KeyId := 'my-signing-key';
    vGCloud.KeyVersion := '1';
    vGCloud.ServiceAccountJSON := 'C:\keys\sa.json';
    vGCloud.Connect;
    // vSigner.KeyProvider := vGCloud;
  finally
    vGCloud.Free;
  end;
end;

PROVIDER 8 / 10

`TsgcHashiCorpVaultKeyProvider`

HashiCorp Vault. Il motore Transit di Vault esegue la firma. Ideale per la custodia delle chiavi self-hosted basata su policy quando Vault è già parte dello stack.

Il motore Transit gestisce solo la chiave — fornisci il certificato tramite SetCertificateFromFile.
Autenticazione tramite token; il mount path predefinito è 'transit'.

vault.pas

var
  vVault: TsgcHashiCorpVaultKeyProvider;
begin
  vVault := TsgcHashiCorpVaultKeyProvider.Create(nil);
  try
    vVault.VaultAddress := 'https://vault.example.com:8200';
    vVault.Token := 's.myVaultToken';
    vVault.MountPath := 'transit';
    vVault.KeyName := 'my-signing-key';
    vVault.Connect;
    vVault.SetCertificateFromFile('C:\certs\signing-cert.pem');
    // vSigner.KeyProvider := vVault;
  finally
    vVault.Free;
  end;
end;

PROVIDER 9 / 10

`TsgcCertumSimplySignProvider`

Certum SimplySign. QTSP polacco. Firme elettroniche qualificate tramite PIN autorizzato da app mobile, nessun token USB richiesto. Scelta comune per i flussi polacchi KSeF e ZUS.

Credenziali OAuth2 client + username/password dell'account SimplySign + PIN.
ListCertificates espone ogni certificato disponibile nell'account.

certum.pas

var
  vCertum: TsgcCertumSimplySignProvider;
begin
  vCertum := TsgcCertumSimplySignProvider.Create(nil);
  try
    vCertum.ClientId := 'your-client-id';
    vCertum.ClientSecret := 'your-client-secret';
    vCertum.Username := 'user@example.com';
    vCertum.Password := 'account-password';
    vCertum.PIN := '123456';
    vCertum.BaseURL := 'https://cloudsign.certum.pl';
    vCertum.Connect;
    // vSigner.KeyProvider := vCertum;
  finally
    vCertum.Free;
  end;
end;

PROVIDER 10 / 10

`TsgcCSCKeyProvider`

Cloud Signature Consortium API v2. Interfaccia generica verso qualsiasi QTSP che implementa CSC v2 — Universign, D-Trust sign-me, A-Trust, FNMT Cl@ve Firma, Evrotrust, Intesi Group. Il provider conserva la chiave qualificata in un QSCD remoto; sgcSign invia solo l'hash del documento.

Tre modalità di autenticazione: cscBasic, cscOAuth2, cscOTP (password monouso per autenticazione a due fattori).
Chiama credentials/authorize + signatures/signHash secondo la specifica CSC v2.

csc-v2.pas

var
  vCSC: TsgcCSCKeyProvider;
  vCreds: TStringArray;
begin
  vCSC := TsgcCSCKeyProvider.Create(nil);
  try
    vCSC.BaseURL := 'https://api.qtsp.example/csc/v2';
    vCSC.AuthMethod := cscBasic;
    vCSC.Username := 'alice';
    vCSC.Password := 'secret';
    vCreds := vCSC.ListCredentials;
    vCSC.CredentialID := vCreds[0];
    vCSC.PIN := '123456';
    vCSC.OTP := '987654';
    vCSC.LoadCredentialInfo;
    // vSigner.KeyProvider := vCSC;
  finally
    vCSC.Free;
  end;
end;

INTERFACCIA COMUNE

Cambia con una sola riga

Ogni provider implementa IsgcKeyProvider. Il codice del signer non sa mai se la chiave risiede su disco, su un token, in Azure o dietro un'API CSC v2.

Un signer, dieci provider

Sviluppa con un PFX locale. Testa con l'archivio Windows. Distribuisci su Azure Trusted Signing.
Profili per paese, livelli di firma, OCSP, timestamp — tutto il resto rimane invariato.
Il server sgcSign utilizza internamente gli stessi provider — centralizza prima localmente, poi scala a un daemon.

swap-providers.pas

function SignWithAnyProvider(
  aProvider: IsgcKeyProvider; const aXML: string): string;
var
  vSigner: TsgcXAdESSigner;
begin
  vSigner := TsgcXAdESSigner.Create(nil);
  try
    vSigner.KeyProvider := aProvider;
    vSigner.Profile.LoadProfile(spEmploymentDE);
    Result := vSigner.SignXML(aXML);
  finally
    vSigner.Free;
  end;
end;

// Il chiamante sceglie il provider; al signer non importa.
SignWithAnyProvider(vPFX, vXML);
SignWithAnyProvider(vAzure, vXML);
SignWithAnyProvider(vCSC, vXML);

Bring Your Own Key — 10 provider