Una guida completa da un progetto VCL nuovo a un envelope XAdES firmato. Funziona da Delphi 7 a RAD Studio 13 e con C++Builder.
Servono solo due cose — sgcSign installato nell'IDE e un certificato PFX con cui firmare.
# Non hai ancora un PFX? Genera un certificato di test autofirmato con OpenSSL:
openssl req -x509 -newkey rsa:2048 \
-keyout key.pem -out cert.pem \
-days 365 -nodes \
-subj "/CN=sgcSign Test"
openssl pkcs12 -export \
-inkey key.pem -in cert.pem \
-out test.pfx \
-password pass:secret
# Ora hai test.pfx con password "secret".Avvia un'applicazione VCL Forms nel tuo IDE. Inserisci due memo e un pulsante sulla form — questa è l'intera UI.
TMemo, incolla qui l'XML non firmato.
TMemo, l'XML firmato appare qui dopo il clic sul pulsante.
TButton, collegato al gestore OnClick nel passo 2.
object Form1: TForm1
Caption = 'Guida rapida sgcSign'
ClientWidth = 800
ClientHeight = 600
object memoXML: TMemo
Left = 8
Top = 8
Width = 784
Height = 240
end
object memoSigned: TMemo
Left = 8
Top = 288
Width = 784
Height = 300
end
object btnSign: TButton
Left = 8
Top = 256
Caption = 'Firma XML'
end
endCarica un provider PFX, collegagli un document signer con il profilo VeriFactu e chiama SignXML.
TsgcPFXKeyProvider importa il file .pfx tramite Windows CNG — la firma moderna SHA-256 funziona indipendentemente dal CSP originale.
TsgcDocumentSigner sceglie il livello XAdES corretto in base al profilo.
spVeriFactu seleziona VeriFactu dell'AEAT spagnola — XAdES-EPES, B-B, RSA-SHA256, C14N esclusiva.
procedure TForm1.btnSignClick(Sender: TObject);
var
vKeyProvider: TsgcPFXKeyProvider;
vSigner: TsgcDocumentSigner;
begin
vKeyProvider := TsgcPFXKeyProvider.Create(nil);
try
vKeyProvider.FileName := 'certificate.pfx';
vKeyProvider.Password := 'secret';
vKeyProvider.LoadFromFile;
vSigner := TsgcDocumentSigner.Create(nil);
try
vSigner.KeyProvider := vKeyProvider;
vSigner.Profile := spVeriFactu;
memoSigned.Text := vSigner.SignXML(memoXML.Text);
finally
vSigner.Free;
end;
finally
vKeyProvider.Free;
end;
end;__finally garantisce il rilascio dei provider anche se la firma genera un'eccezione.
UnicodeString è utilizzato end-to-end — nessuna conversione ANSI/UTF-8 di cui preoccuparsi.
void __fastcall TForm1::btnSignClick(TObject *Sender)
{
TsgcPFXKeyProvider *vKeyProvider = new TsgcPFXKeyProvider(NULL);
try {
vKeyProvider->FileName = "certificate.pfx";
vKeyProvider->Password = "secret";
vKeyProvider->LoadFromFile();
TsgcDocumentSigner *vSigner = new TsgcDocumentSigner(NULL);
try {
vSigner->KeyProvider = vKeyProvider;
vSigner->Profile = spVeriFactu;
memoSigned->Text = vSigner->SignXML(memoXML->Text);
} __finally {
delete vSigner;
}
} __finally {
delete vKeyProvider;
}
}Due unit nella tua clausola uses — il provider PFX e il document signer.
uses DelphiOgni provider di chiavi vive nella sua unit, così paghi solo ciò a cui fai riferimento. sgcSign_DocumentSigner include il livello di routing che sceglie XAdES, PAdES o CAdES in base all'input.
uses
Classes, SysUtils, Forms, StdCtrls, Controls,
// sgc
sgcSign_KeyProvider_PFX,
sgcSign_DocumentSigner;Stesse unit, esposte come header .hpp. Il linker di C++ Builder risolve automaticamente le librerie statiche sottostanti.
#include "sgcSign_KeyProvider_PFX.hpp"
#include "sgcSign_DocumentSigner.hpp"Premi F9, incolla una fattura nel memo in alto, fai clic su Firma XML. L'envelope firmato appare nel memo in basso.
Premi F9 nell'IDE. La form si apre con due memo e un pulsante. Nessuna eccezione, nessuna unit mancante.
Inserisci qualsiasi XML di fattura (o qualsiasi XML ben formato) in memoXML. Il signer lo normalizza internamente in UTF-8.
memoSigned ora contiene il tuo XML con un elemento enveloped <ds:Signature> aggiunto. Salvalo, eseguilo con qualsiasi verificatore XAdES — oppure utilizza direttamente TsgcSignatureVerifier.
Su Delphi 7, string è AnsiString. Usa gli overload WideString per preservare senza perdita caratteri polacchi, cirillici o greci.
Su Delphi 7 l'overload string passa attraverso l'ACP del sistema. I caratteri diacritici in 'Jarosław' vengono preservati solo se l'ACP di sistema è CP1250. Se l'ACP è CP1252, i caratteri vengono corrotti nell'XML firmato.
Gli overload WideString bypassano completamente l'ACP — da UTF-16 a UTF-8 tramite WideCharToMultiByte con CP_UTF8. Su Delphi 2009+ entrambi gli overload sono equivalenti; UnicodeString è già UTF-16.
var
Doc: IXMLDocument; // MSXML6
XML, Signed: WideString; // = MSXML6 DOMString
Sign: TsgcXAdESSigner;
begin
Doc.SaveToXML(XML); // WideString in uscita, nessun passaggio ACP
Signed := Sign.SignXML(XML); // risolve all'overload WideString
// I caratteri polacchi, cirillici e greci vengono preservati senza perdita
end;Tutti i timestamp X.509 / CRL / OCSP / TSA sono memorizzati come valori TDateTime in UTC, in linea con le specifiche ASN.1 sottostanti.
Per le visualizzazioni all'utente finale, utilizza le proprietà *Local su ogni componente (ad es. vCert.NotAfterLocal) oppure converti manualmente con sgcUTCToLocal della unit sgcSign_Time.
Questo è in linea con RFC 5280 (X.509), RFC 3161 (TSA) e RFC 6960 (OCSP), che specificano tutti UTC. L'helper sgcUTCNow restituisce il TDateTime UTC corrente per il codice che deve confrontare timestamp.
uses sgcSign_Time;
// Mostra la validità del certificato in ora locale
Memo1.Lines.Add('Cert scade: ' +
DateTimeToStr(vCert.NotAfterLocal));
Memo1.Lines.Add('Ora (UTC): ' +
DateTimeToStr(sgcUTCNow));
// Oppure converti manualmente
vLocal := sgcUTCToLocal(vCert.NotAfter);XAdES è solo l'inizio. PAdES, CAdES, profili, provider di chiavi e il server centralizzato sono a un clic di distanza.
Scopri l'intera superficie API XAdES, PAdES, CAdES e l'infrastruttura di supporto per timestamp + OCSP.
Leggi di più →VeriFactu, FatturaPA, KSeF, FACTUR-X, più 9 profili per contratti di lavoro UE. Cambio di giurisdizione in una sola riga.
Leggi di più →PFX, PEM, archivio Windows, PKCS#11, Azure Trusted Signing, AWS KMS, Google KMS, Vault, Certum, CSC v2.
Leggi di più →Centralizza la firma sull'intera build farm. API REST, admin web, GitHub Actions, Azure DevOps, Jenkins, Docker.
Leggi di più →