Questa pagina può contenere testo tradotto automaticamente.

Come firmare PDF con token USB e dispositivi HSM in C# e VB.NET

Le autorità di certificazione attendibili non consentono più il download delle chiavi private per i certificati di firma dei documenti. Le chiavi private devono invece essere archiviate in hardware sicuro come token USB, smart card o HSM basati su cloud.

È possibile utilizzare la libreria Docotic.Pdf per firmare documenti PDF in .NET utilizzando dispositivi HSM. Questo articolo descrive le integrazioni con Azure Key Vault, AWS KMS e hardware conforme a PKCS#11.

Libreria Docotic.Pdf 9.7.18373 Test di regressione Ne sono passati 15,244 Download totali di NuGet 5,976,723

Puoi ottenere la libreria e una chiave di licenza gratuita a tempo limitato dalla pagina Scarica la libreria PDF C# .NET.

Firma PDF esterna

Prerequisiti

Gli esempi di codice in questo articolo utilizzano certificati autofirmati per firmare documenti PDF. Per impostazione predefinita, i visualizzatori PDF non considerano attendibili queste firme. I certificati autofirmati devono essere utilizzati solo a scopo di test, non in ambienti di produzione. Per generare firme PDF attendibili, utilizzare certificati di firma dei documenti emessi da Autorità di Certificazione terze.

Ottieni il certificato giusto

Preferisci i certificati di aziende elencate nell'Adobe Approved Trust List (AATL). Adobe Acrobat considera attendibili i certificati di tali aziende per impostazione predefinita e non segnalerà l'avviso "Validità del certificato sconosciuta".

Per creare documenti conformi allo standard UE (eIDAS), è necessario utilizzare certificati qualificati emessi da provider elencati nelle European Union Trusted Lists (EUTL).

Scopri come utilizzare il tuo certificato in .NET

Quando si ordina un certificato per la firma di documenti, in genere si riceve l'accesso a un dispositivo HSM. Potrebbe trattarsi di un token USB fisico o di una soluzione HSM basata su cloud.

Dovresti quindi imparare a firmare i dati con questo HSM. Questa è solitamente la parte più complessa, perché ogni provider di crittografia è diverso. Dovresti seguire la documentazione del tuo token USB o dell'API cloud.

Idealmente, dovresti trovare un SDK .NET corrispondente. O almeno un SDK nativo e utilizzarlo tramite interoperabilità in .NET.

Il tuo obiettivo è ottenere codice C# o VB.NET in grado di firmare qualsiasi byte utilizzando il tuo certificato.

PDF API per la firma esterna

Una volta che puoi firmare qualsiasi byte con il tuo dispositivo HSM, sei pronto per firmare documenti PDF con Docotic.Pdf. Per farlo, implementa l'interfaccia IPdfSigner e utilizzala per la firma.

Implementare l'interfaccia IPdfSigner

IPdfSigner dichiara due membri. La proprietà SignatureAlgorithm restituisce l'algoritmo utilizzato per la firma. In genere, si utilizzano algoritmi RSA o ECDSA.

Il metodo Sign è la parte fondamentale del flusso di firma esterna. Docotic.Pdf fornisce a questo metodo il digest dei byte di un documento PDF. È necessario firmare questo digest con il dispositivo HSM e restituire i byte di una firma digitale. Si noti che in questo caso non è necessario restituire un oggetto PKCS#7. È sufficiente generare e restituire la firma crittografica.

Docotic.Pdf richiama il metodo Sign due volte per ogni firma. La prima chiamata serve a calcolare lo spazio necessario per la firma. La seconda chiamata serve a firmare effettivamente il documento.

Crea PdfSigningOptions per la firma esterna

Utilizza il costruttore PdfSigningOptions(IPdfSigner, X509Certificate2[]) per firmare i documenti PDF con l'implementazione di IPdfSigner. Ottieni una catena di certificati e forniscila come secondo argomento. È richiesto almeno un certificato e il certificato di firma deve essere il primo.

L'ultimo pezzo del puzzle è la proprietà PdfSigningOptions.DigestAlgorithm. Il valore di questa proprietà deve essere allineato con IPdfSigner.SignatureAlgorithm e con l'implementazione di IPdfSigner.Sign.

Vediamo come firmare i PDF con firme esterne in scenari comuni.

Firmare documenti PDF utilizzando il driver PKCS#11 in C#

Se il token USB crittografico o la smart card sono dotati di un driver PKCS#11, è possibile utilizzare le librerie Pkcs11Interop.X509Store o Pkcs11Interop in .NET. Pkcs11Interop è compatibile con le smart card Atos CardOS, YubiKey PIV, SmartCard-HSM, SafeNet ProtectServer HSM e altri HSM.

L'esempio di codice Firma documenti PDF utilizzando i driver PKCS#11 mostra come firmare documenti PDF con un token USB o una smart card. Sarà necessario personalizzare queste righe:

string pkcsLibraryPath = @"C:\Program Files\SoftHSM2\lib\softhsm2-x64.dll";
ulong slotId = 1743347971;
string alias = "YOUR-ALIAS";
string certLabel = "YOUR-CERTIFICATE";
string pin = "YOUR-PIN";
var digestAlgorithm = PdfDigestAlgorithm.Sha512;

La nostra configurazione di esempio utilizza SoftHSM2 come emulatore di un token USB. Nelle applicazioni reali, SoftHSM2 non è necessario. Si consiglia invece di utilizzare il driver fornito con il token USB.

Firmare documenti PDF utilizzando Azure Key Vault

Microsoft Azure Key Vault archivia in modo sicuro certificati e chiavi. È necessario effettuare le seguenti operazioni preliminari:

  1. Creare un account Azure.
  2. Creare un utente Azure.
  3. Creare un Key Vault.
  4. Consentire l'accesso al Key Vault all'utente Azure selezionato.
  5. Aggiungere un certificato di firma del documento al Key Vault. È possibile importare certificati da Autorità di certificazione integrate.

Quindi, utilizzare il pacchetto NuGet Azure.Security.KeyVault.Keys per l'accesso in .NET. Esempio di codice C# per la firma con una chiave di Azure Key Vault:

var vaultUrl = new Uri("https://YOUR-VAULT.vault.azure.net/");
var credential = new DefaultAzureCredential();

var keyClient = new KeyClient(vaultUrl, credential);
KeyVaultKey key = keyClient.GetKey("YOUR-KEY");
var cryptoClient = new CryptographyClient(key.Id, credentials);
byte[] messageToSign = ..;
byte[] signature = cryptoClient.SignData(SignatureAlgorithm.RS512, messageToSign).Signature;

Un'implementazione correlata di IPdfSigner potrebbe apparire così:

class AzureSigner : IPdfSigner
{
    private readonly CryptographyClient m_client;
    private readonly AzureSignatureAlgorithm m_signingAlgorithm;

    public AzureSigner(CryptographyClient client, AzureSignatureAlgorithm signingAlgorithm)
    {
        m_client = client;
        m_signingAlgorithm = signingAlgorithm;
    }

    public PdfSignatureAlgorithm SignatureAlgorithm
    {
        get
        {
            if (m_signingAlgorithm == AzureSignatureAlgorithm.RS256 ||
                m_signingAlgorithm == AzureSignatureAlgorithm.RS384 ||
                m_signingAlgorithm == AzureSignatureAlgorithm.RS512)
                return PdfSignatureAlgorithm.Rsa;

            throw new NotSupportedException($"Unsupported {nameof(SignatureAlgorithm)} value: {m_signingAlgorithm}");
        }
    }

    public PdfDigestAlgorithm DigestAlgorithm
    {
        get
        {
            if (m_signingAlgorithm == AzureSignatureAlgorithm.RS256)
                return PdfDigestAlgorithm.Sha256;

            if (m_signingAlgorithm == AzureSignatureAlgorithm.RS384)
                return PdfDigestAlgorithm.Sha384;

            if (m_signingAlgorithm == AzureSignatureAlgorithm.RS512)
                return PdfDigestAlgorithm.Sha512;

            throw new NotSupportedException($"Unsupported {nameof(SignatureAlgorithm)} value: {m_signingAlgorithm}");
        }
    }

    public byte[] Sign(byte[] message)
    {
        return m_client.SignData(m_signingAlgorithm, message).Signature;
    }
}

Infine, utilizza questa classe AzureSigner per firmare i documenti PDF:

CryptographyClient cryptoClient = ..;
using X509Certificate2 cert = ..
var signer = new AzureSigner(cryptoClient, SignatureAlgorithm.RS512);

using var pdf = new PdfDocument();

PdfPage page = pdf.Pages[0];
PdfSignatureField field = page.AddSignatureField(50, 50, 200, 200);

var options = new PdfSigningOptions(signer, new[] { cert })
{
    DigestAlgorithm = signer.DigestAlgorithm,
    Field = field,
};

pdf.SignAndSave(options, ..);

Esplora l'esempio di codice completo Firma documenti PDF utilizzando Azure Key Vault su GitHub.

Firmare documenti PDF utilizzando AWS KMS

AWS Key Management Service (KMS) è un altro sistema di archiviazione sicuro per chiavi crittografiche. La preparazione segue gli stessi passaggi di Azure Key Vault:

  1. Creare un account AWS.
  2. Creare un utente IAM.
  3. Aggiungere una chiave di firma.
  4. Consentire l'accesso alle chiavi all'utente IAM selezionato.

Per AWS, è necessario utilizzare il pacchetto NuGet AWSSDK.KeyManagementService in .NET. Il codice di esempio per la firma PDF è molto simile allo scenario di Azure:

using var pdf = new PdfDocument();

PdfPage page = pdf.Pages[0];
PdfSignatureField field = page.AddSignatureField(50, 50, 200, 200);

var signingAlgorithm = SigningAlgorithmSpec.RSASSA_PSS_SHA_512;
var signer = new AwsSigner("arn:aws:kms:YOUR-id", signingAlgorithm)
var options = new PdfSigningOptions(signer, new[] { cert })
{
    DigestAlgorithm = signer.DigestAlgorithm,
    Field = field,
};

pdf.SignAndSave(options, ..);


class AwsSigner : IPdfSigner
{
    private readonly string m_keyId;
    private readonly SigningAlgorithmSpec m_signingAlgorithm;

    public AwsSigner(string keyId, SigningAlgorithmSpec signingAlgorithm)
    {
        m_keyId = keyId;
        m_signingAlgorithm = signingAlgorithm;
    }

    public PdfSignatureAlgorithm SignatureAlgorithm
    {
        get
        {
            if (m_signingAlgorithm == SigningAlgorithmSpec.RSASSA_PKCS1_V1_5_SHA_256 ||
                m_signingAlgorithm == SigningAlgorithmSpec.RSASSA_PKCS1_V1_5_SHA_384 ||
                m_signingAlgorithm == SigningAlgorithmSpec.RSASSA_PKCS1_V1_5_SHA_512)
                return PdfSignatureAlgorithm.Rsa;

            throw new NotSupportedException($"Unsupported {nameof(SigningAlgorithmSpec)} value: {m_signingAlgorithm}");
        }
    }

    public PdfDigestAlgorithm DigestAlgorithm
    {
        get
        {
            string alg = m_signingAlgorithm.Value;
            if (alg.EndsWith("256"))
                return PdfDigestAlgorithm.Sha256;

            if (alg.EndsWith("384"))
                return PdfDigestAlgorithm.Sha384;

            if (alg.EndsWith("512"))
                return PdfDigestAlgorithm.Sha512;

            throw new NotSupportedException($"Unsupported {nameof(SigningAlgorithmSpec)} value: {m_signingAlgorithm}");
        }
    }

    public byte[] Sign(byte[] message)
    {
        using var kmsClient = new AmazonKeyManagementServiceClient();
        using var stream = new MemoryStream(message);
        var signRequest = new SignRequest()
        {
            SigningAlgorithm = m_signingAlgorithm,
            KeyId = m_keyId,
            MessageType = MessageType.RAW,
            Message = stream,
        };
        SignResponse signResponse = kmsClient.SignAsync(signRequest).GetAwaiter().GetResult();
        return signResponse.Signature.ToArray();
    }
}

L'esempio di codice completo Firma documenti PDF utilizzando AWS KMS è disponibile anche su GitHub.

Conclusione

Sfrutta la libreria Docotic.Pdf per firmare documenti PDF utilizzando token USB, smart card o HSM basati su cloud. Per ottenere questo risultato, implementa l'interfaccia IPdfSigner in codice C# o VB.NET.

Scarica e prova esempi di codice per firme digitali in PDF da GitHub. Consulta gli articoli correlati per ulteriori informazioni:

Domande frequenti

Come si firma un PDF utilizzando un token USB o una smart card?

Utilizzare le librerie .NET Docotic.Pdf e Pkcs11Interop per firmare i PDF con token o smart card. Per maggiori dettagli, consultare la sezione Firmare documenti PDF utilizzando il driver PKCS#11 in C#.

Come si usa SoftHSM con il token USB o la smart card?

SoftHSM simula un dispositivo HSM reale. Non è necessario SoftHSM se si dispone di un token USB o di una smart card. In alternativa, utilizzare il driver PKCS#11 fornito con il dispositivo HSM.

Come si firma un documento PDF con una firma esterna?

Consultare le sezioni Firmare documenti PDF utilizzando Azure Key Vault e Firmare documenti PDF utilizzando AWS KMS. La firma PDF esterna con altri HSM basati su cloud segue una procedura simile.

Come si usa Azure Key Vault in .NET?

Utilizzare il pacchetto NuGet Azure.Security.KeyVault.Keys. Provare l'esempio di codice Firma documenti PDF utilizzando Azure Key Vault da GitHub.