Proveedores de claves — sgcSign

PROVEEDOR 1 / 10

`TsgcPFXKeyProvider`

Archivos PFX / PKCS#12. Clave local protegida por contraseña. Ideal para desarrollo, despliegues pequeños y cualquier flujo en el que el certificado se distribuye como un único archivo .pfx/.p12.

Importado vía Windows CNG con PKCS12_PREFER_CNG_KSP — la firma SHA-256/384/512 funciona sea cual sea el CSP original.
Los archivos .pfx con varios certificados se recorren automáticamente hasta encontrar el que contiene la clave privada.

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;

PROVEEDOR 2 / 10

`TsgcPEMKeyProvider`

Archivos PEM. PKCS#8 cifrado con soporte nativo PBES2 / PBKDF2 / AES-CBC, además del formato heredado de clave privada RSA con DEK-Info. Ideal para pipelines basados en OpenSSL.

Compatible con BEGIN CERTIFICATE, BEGIN RSA PRIVATE KEY, BEGIN PRIVATE KEY y BEGIN ENCRYPTED PRIVATE KEY.
Los PEM combinados (cert + clave en un solo archivo) se detectan automáticamente — deja PrivateKeyFile vacío.

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;

PROVEEDOR 3 / 10

`TsgcWindowsCertStoreProvider`

Almacén de certificados de Windows. Almacenes de máquina local y de usuario actual. Ideal para apps de escritorio que usan certificados ya emitidos por AD o cualquier despliegue en el que Windows ya gestiona el ciclo de vida del certificado.

La firma se realiza vía Windows CNG — la clave privada nunca sale del almacén.
Selección por subcadena del CN del subject o por huella 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;

PROVEEDOR 4 / 10

`TsgcPKCS11Provider`

PKCS#11 / tokens hardware. Tarjetas inteligentes, tokens USB, HSM — SafeNet, YubiKey, Nitrokey, Thales. Obligatorio para firmas electrónicas cualificadas en la mayoría de jurisdicciones de la UE.

Compatibilidad con los mecanismos CKM_RSA_PKCS y CKM_ECDSA_SHA256.
Helpers EnumerateSlots / EnumerateCertificates para elegir el slot adecuado en tiempo de ejecución.

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;

PROVEEDOR 5 / 10

`TsgcAzureTrustedSigningProvider`

Azure Trusted Signing. El servicio cualificado de firma de código de Microsoft. Authenticode sin tener que comprar un certificado EV — Microsoft es propietario del certificado y aprovisiona la clave de firma por ti.

Credenciales de cliente OAuth2 — Tenant ID + Client ID + Client Secret.
Las claves privadas residen íntegramente en Azure, nunca en el agente de 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;

PROVEEDOR 6 / 10

`TsgcAWSKMSKeyProvider`

AWS Key Management Service. El servicio de custodia de claves de Amazon respaldado por HSM. Combínalo con un certificado emitido por AWS para firmar en la nube sin exponer la clave privada.

Autenticación AWS Signature Version 4 calculada en proceso.
KeyId acepta ID de clave, ARN de clave o ARN de alias.

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;

PROVEEDOR 7 / 10

`TsgcGCloudKMSKeyProvider`

Google Cloud KMS. Mismo modelo operativo que AWS KMS. El archivo JSON de cuenta de servicio se autentica mediante intercambio JWT por un access token OAuth2 y luego firma a través de la API de Cloud KMS.

ProjectId + Location + KeyRing + Key + Version — replica 1:1 la jerarquía de recursos de GCP.
Solo claves KMS asimétricas — respaldadas por HSM cuando está disponible, protegidas por software en caso contrario.

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;

PROVEEDOR 8 / 10

`TsgcHashiCorpVaultKeyProvider`

HashiCorp Vault. El motor de secretos Transit de Vault realiza la firma. Ideal para custodia de claves autoalojada y gobernada por políticas, cuando Vault ya forma parte de la pila.

El motor Transit gestiona solo la clave — suministra el certificado mediante SetCertificateFromFile.
Autenticación por token; el mount path por defecto es '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;

PROVEEDOR 9 / 10

`TsgcCertumSimplySignProvider`

Certum SimplySign. QTSP polaco. Firmas electrónicas cualificadas mediante PIN autorizado por app móvil, sin necesidad de token USB. Elección habitual para los flujos polacos de KSeF y ZUS.

Credenciales de cliente OAuth2 + usuario/contraseña de la cuenta SimplySign + PIN.
ListCertificates expone todos los certificados disponibles en la cuenta.

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;

PROVEEDOR 10 / 10

`TsgcCSCKeyProvider`

Cloud Signature Consortium API v2. Interfaz genérica para cualquier QTSP que implemente CSC v2 — Universign, D-Trust sign-me, A-Trust, FNMT Cl@ve Firma, Evrotrust, Intesi Group. El proveedor guarda la clave cualificada en un QSCD remoto; sgcSign solo envía el hash del documento.

Tres modos de autenticación: cscBasic, cscOAuth2 y cscOTP (contraseña de un solo uso para doble factor).
Invoca credentials/authorize + signatures/signHash según la spec 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;

INTERFAZ COMÚN

Cambia con una línea

Todos los proveedores implementan IsgcKeyProvider. El código del firmador nunca sabe si la clave vive en disco, en un token, en Azure o detrás de una API CSC v2.

Un firmador, diez proveedores

Desarrolla con un PFX local. Prueba con el almacén de Windows. Despliega en Azure Trusted Signing.
Perfiles por país, niveles de firma, OCSP, sellos de tiempo — todo lo demás permanece igual.
sgcSign Server utiliza los mismos proveedores internamente — centraliza primero en local y escala más tarde con 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;

// Caller picks the provider; signer doesn't care.
SignWithAnyProvider(vPFX, vXML);
SignWithAnyProvider(vAzure, vXML);
SignWithAnyProvider(vCSC, vXML);

Trae tu propia clave — 10 proveedores