~~NOTOC~~
====== Scenario 8.1: Sign Document ======

<WRAP round info>
**Category:** [[.:start|Digital Signatures]] \\
**Complexity:** ⭐⭐⭐ (Medium) \\
**Prerequisites:** Signature certificate and key \\
**Estimated Time:** 15-20 Minutes
</WRAP>

----

===== Description =====

This scenario describes **digitally signing documents** with Post-Quantum secure algorithms (ML-DSA). Digital signatures ensure:

  * **Authenticity** - Sender is verified
  * **Integrity** - Document has not been altered
  * **Non-Repudiation** - Signature cannot be denied

**Supported Formats:**
  * Detached Signature (separate .sig file)
  * CMS/PKCS#7 (embedded or detached)
  * PDF Digital Signature (PAdES)

----

===== Workflow =====

<mermaid>
flowchart LR
    DOC[Document] --> HASH[SHA-256 Hash]
    HASH --> SIGN[ML-DSA Signature]
    KEY[Private Key] --> SIGN
    SIGN --> SIG[Signature]
    CERT[Certificate] --> CMS[CMS Container]
    SIG --> CMS

    style SIGN fill:#e8f5e9
    style CMS fill:#e3f2fd
</mermaid>

----

===== Code Example: Detached Signature =====

<code csharp>
using WvdS.Security.Cryptography.X509Certificates.Extensions.PQ;
using System.Security.Cryptography;

using var ctx = PqCryptoContext.Initialize();

// Load signing key
var signingKey = ctx.LoadPrivateKey("signing.key.pem", "KeyPassword!");
var signingCert = ctx.LoadCertificate("signing.crt.pem");

// Load document
var document = File.ReadAllBytes("contract.pdf");

// Calculate hash
var hash = SHA256.HashData(document);

// Sign with ML-DSA
var signature = ctx.SignData(
    data: hash,
    privateKey: signingKey,
    hashAlgorithm: HashAlgorithmName.SHA256,
    mode: CryptoMode.Hybrid  // RSA + ML-DSA parallel
);

// Save signature
File.WriteAllBytes("contract.pdf.sig", signature);

// Signature metadata
var sigInfo = new SignatureInfo
{
    Algorithm = "ML-DSA-65 + RSA-PSS (Hybrid)",
    SignedAt = DateTimeOffset.UtcNow,
    Signer = signingCert.Subject,
    DocumentHash = Convert.ToHexString(hash),
    SignatureFile = "contract.pdf.sig"
};

File.WriteAllText("contract.pdf.sig.json",
    JsonSerializer.Serialize(sigInfo, new JsonSerializerOptions { WriteIndented = true }));

Console.WriteLine($"Document signed:");
Console.WriteLine($"  Signer: {signingCert.Subject}");
Console.WriteLine($"  Hash: {Convert.ToHexString(hash).Substring(0, 16)}...");
Console.WriteLine($"  Signature: {signature.Length} Bytes");
</code>

----

===== Code Example: CMS/PKCS#7 Signature =====

<code csharp>
using System.Security.Cryptography.Pkcs;

using var ctx = PqCryptoContext.Initialize();

var signingCert = ctx.LoadCertificate("signing.crt.pem");
var signingKey = ctx.LoadPrivateKey("signing.key.pem", "KeyPassword!");

// Document
var document = File.ReadAllBytes("contract.pdf");

// Create CMS ContentInfo
var contentInfo = new ContentInfo(document);

// Create SignedCms
var signedCms = new SignedCms(contentInfo, detached: false);  // Embedded

// Configure signer info
var signer = new CmsSigner(signingCert)
{
    DigestAlgorithm = new Oid("2.16.840.1.101.3.4.2.1"),  // SHA-256
    IncludeOption = X509IncludeOption.WholeChain
};

// Add signed attributes
signer.SignedAttributes.Add(new Pkcs9SigningTime(DateTimeOffset.UtcNow));

// Sign with PQ extension (Hybrid)
signedCms.ComputeSignature(signer, mode: CryptoMode.Hybrid);

// Export CMS container
var signedData = signedCms.Encode();
File.WriteAllBytes("contract.pdf.p7s", signedData);

Console.WriteLine($"CMS signature created: {signedData.Length} Bytes");
</code>

----

===== Code Example: Verify Signature =====

<code csharp>
using var ctx = PqCryptoContext.Initialize();

// Load document and signature
var document = File.ReadAllBytes("contract.pdf");
var signature = File.ReadAllBytes("contract.pdf.sig");

// Load signer certificate
var signerCert = ctx.LoadCertificate("signing.crt.pem");

// Calculate hash
var hash = SHA256.HashData(document);

// Verify signature
bool isValid = ctx.VerifyData(
    data: hash,
    signature: signature,
    certificate: signerCert,
    hashAlgorithm: HashAlgorithmName.SHA256,
    mode: CryptoMode.Hybrid
);

Console.WriteLine($"Signature valid: {isValid}");

if (isValid)
{
    // Validate certificate chain
    var chain = new X509Chain();
    chain.ChainPolicy.RevocationMode = X509RevocationMode.Online;
    bool chainValid = chain.Build(signerCert);

    Console.WriteLine($"Certificate valid: {chainValid}");
    Console.WriteLine($"  Signer: {signerCert.Subject}");
    Console.WriteLine($"  Valid until: {signerCert.NotAfter:yyyy-MM-dd}");
}
</code>

----

===== Batch Signing =====

<code csharp>
public class BatchSigner
{
    private readonly AsymmetricAlgorithm _signingKey;
    private readonly X509Certificate2 _signingCert;
    private readonly PqCryptoContext _ctx;

    public BatchSigner(string certPath, string keyPath, string password)
    {
        _ctx = PqCryptoContext.Initialize();
        _signingCert = _ctx.LoadCertificate(certPath);
        _signingKey = _ctx.LoadPrivateKey(keyPath, password);
    }

    public async Task<IEnumerable<SignatureResult>> SignBatch(IEnumerable<string> filePaths)
    {
        var results = new List<SignatureResult>();

        foreach (var filePath in filePaths)
        {
            try
            {
                var document = await File.ReadAllBytesAsync(filePath);
                var hash = SHA256.HashData(document);

                var signature = _ctx.SignData(
                    hash,
                    _signingKey,
                    HashAlgorithmName.SHA256,
                    CryptoMode.Hybrid
                );

                var sigPath = filePath + ".sig";
                await File.WriteAllBytesAsync(sigPath, signature);

                results.Add(new SignatureResult
                {
                    FilePath = filePath,
                    SignaturePath = sigPath,
                    Success = true,
                    SignedAt = DateTimeOffset.UtcNow
                });
            }
            catch (Exception ex)
            {
                results.Add(new SignatureResult
                {
                    FilePath = filePath,
                    Success = false,
                    Error = ex.Message
                });
            }
        }

        return results;
    }
}
</code>

----

===== Signature Formats =====

^  Format  ^  Standard  ^  Usage  ^  Embedded  ^
| Detached | Proprietary | Simple cases | No |
| PKCS#7/CMS | RFC 5652 | E-Mail, Documents | Optional |
| PAdES | ETSI TS 103 172 | PDF signatures | Yes |
| XAdES | ETSI TS 101 903 | XML signatures | Optional |
| JAdES | ETSI TS 119 182 | JSON signatures | Optional |

----

===== Industry-Specific Requirements =====

^  Industry  ^  Standard  ^  Format  ^  Special Feature  ^
| **eIDAS** | Qualified Signature | PAdES-LTA | Long-term archival |
| **Healthcare** | DiGAV | CMS | Patient documentation |
| **Financial** | PSD2 | JAdES | API signatures |
| **Government** | eGovG | XAdES | Administrative documents |

----

===== Related Scenarios =====

^  Relationship  ^  Scenario  ^  Description  ^
| **Related** | [[.:code_signieren|8.2 Sign Code]] | Sign executables |
| **Related** | [[.:timestamp|8.3 Timestamp]] | Long-term validity |
| **Next Step** | [[.:signatur_verifizieren|8.4 Verify Signature]] | Validation |

----

<< [[.:start|← Signatures Overview]] | [[en:int:pqcrypt:szenarien:start|↑ Scenarios]] | [[.:code_signieren|8.2 Sign Code →]] >>

{{tag>scenario signature document cms pkcs7 ml-dsa}}

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Post-Quantum Cryptography Professional//