====== Scenario 2.1: Create Server CSR ======

<WRAP round info>
**Category:** [[.:start|Certificate Signing Requests (CSR)]] \\
**Complexity:** ** (Medium) \\
**Prerequisites:** Key pair available \\
**Estimated Time:** 5-10 minutes
</WRAP>

----

===== Description =====

This scenario describes creating a **Certificate Signing Request (CSR)** for a TLS server certificate. The CSR contains all information that a CA needs to issue a server certificate.

**What is created:**
  * ML-DSA-65 key pair (or hybrid)
  * CSR with server DN and extensions
  * Subject Alternative Names (SAN) for DNS names

**Use cases:**
  * HTTPS web servers
  * API endpoints
  * Microservices with TLS

----

===== Workflow =====

<mermaid>
flowchart LR
    KEY[Generate key pair] --> DN[Create DN]
    DN --> EXT[Set extensions]
    EXT --> CSR[Create CSR]
    CSR --> SIGN[Sign CSR]
    SIGN --> EXPORT[Export as PEM]

    style CSR fill:#e8f5e9
</mermaid>

----

===== Functions Involved =====

^  Step  ^  FFI Function  ^  Description  ^
| 1 | ''wvds_sec_crypto_x509_keypair_generate_mldsa(65)'' | Generate key pair |
| 2 | ''wvds_sec_crypto_x509_dn_create()'' | Create DN handle |
| 3 | ''wvds_sec_crypto_x509_dn_add_component()'' | Add CN, O, C |
| 4 | ''wvds_sec_crypto_x509_ext_set_san_dns()'' | Add DNS names |
| 5 | ''wvds_sec_crypto_x509_ext_set_key_usage()'' | digitalSignature, keyEncipherment |
| 6 | ''wvds_sec_crypto_x509_ext_set_eku()'' | serverAuth |
| 7 | ''wvds_sec_crypto_x509_csr_create()'' | Create CSR |
| 8 | ''wvds_sec_crypto_x509_csr_sign()'' | Sign CSR with private key |
| 9 | ''wvds_sec_crypto_x509_csr_to_pem()'' | Export as PEM |

----

===== Code Example (C#) =====

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

// 1. Initialize context
using var ctx = PqCryptoContext.Initialize();

// 2. Generate key pair for server
using var serverKey = ctx.GenerateKeyPair(PqAlgorithm.MlDsa65);

// 3. Distinguished Name
var dn = new DnBuilder()
    .AddCN("www.example.com")
    .AddO("Example GmbH")
    .AddOU("IT Department")
    .AddC("DE")
    .AddL("Munich")
    .Build();

// 4. Extensions for server certificate
var extensions = new ExtBuilder()
    .SubjectAlternativeName(new[] {
        "www.example.com",
        "example.com",
        "api.example.com"
    })
    .KeyUsage(KeyUsageFlags.DigitalSignature | KeyUsageFlags.KeyEncipherment)
    .ExtendedKeyUsage(ExtKeyUsage.ServerAuth)
    .Build();

// 5. Create and sign CSR
var csr = ctx.CreateCertificateRequest(serverKey, dn, extensions);

// 6. Save as PEM
File.WriteAllText("server.csr.pem", csr.ToPem());
File.WriteAllText("server.key.pem", serverKey.ToEncryptedPem("SecurePassword123!"));

Console.WriteLine("CSR created: server.csr.pem");
Console.WriteLine($"Subject: {csr.Subject}");
Console.WriteLine($"SANs: {string.Join(", ", csr.SubjectAlternativeNames)}");
</code>

----

===== Parameters =====

==== Subject Alternative Names ====

^  Type  ^  Prefix  ^  Example  ^
| DNS Name | dns: | www.example.com |
| IP Address | ip: | 192.168.1.100 |
| Email | email: | admin@example.com |
| URI | uri: | https://example.com |

==== Key Usage for Server ====

^  Flag  ^  Description  ^  Required  ^
| digitalSignature | Sign TLS handshake | Yes |
| keyEncipherment | RSA key exchange (not for ECDHE) | Optional |
| keyAgreement | ECDH key exchange | Optional |

----

===== Output Files =====

==== server.csr.pem ====

<code>
-----BEGIN CERTIFICATE REQUEST-----
MIICxjCCAi0CAQAwgYExCz... (Base64 DER)
-----END CERTIFICATE REQUEST-----
</code>

^  Field  ^  Value  ^
| Version | 1 (0x00) |
| Subject | CN=www.example.com, O=Example GmbH, C=DE |
| Public Key | ML-DSA-65 (~1,952 bytes) |
| Attributes | Extension Request (SAN, Key Usage, EKU) |
| Signature | ML-DSA-65 (Self-Proof-of-Possession) |

----

===== Common Errors =====

^  Problem  ^  Cause  ^  Solution  ^
| CSR rejected | CN not in SAN | Always add CN as SAN too |
| CA does not accept CSR | Wrong format | Check PEM format |
| Key Usage missing | Extensions not set | Use ExtBuilder |

----

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

^  Relationship  ^  Scenario  ^  Description  ^
| **Next Step** | [[en:int:pqcrypt:szenarien:zertifikate:server_cert|3.1 Server Certificate]] | Have CSR signed by CA |
| **Alternative** | [[.:csr_multi_san|2.3 Multi-SAN CSR]] | Multiple domains |
| **Related** | [[.:csr_client|2.2 Client CSR]] | For client authentication |

----

<< [[.:start|<- CSR Overview]] | [[en:int:pqcrypt:szenarien:start|^ Scenarios]] | [[.:csr_client|2.2 Client CSR ->]] >>

{{tag>scenario csr server tls san ml-dsa}}

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