Šablony certifikátů¶

Návrh projektových šablon certifikátů — vysvětlení každého parametru

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-06-30

1. Dva systémy šablon¶

MazeVault nabízí dva odlišné, vzájemně se doplňující systémy šablon. Pochopení rozdílu je zásadní — nacházejí se na různých místech a slouží různým účelům.

Systém	Kde	Účel
Konfigurační šablony	Certifikáty → Šablony (katalog PKI pro celou organizaci)	Znovupoužitelné profily certifikátů na úrovni organizace, navázané přímo na CA. Používají se při ad‑hoc žádosti o certifikát.
Projektové šablony	Projekt → Nastavení → Šablony	Šablony omezené na jeden projekt. Projektová šablona má kategorii (`secrets`, `certificates` nebo `keys`) a podtyp. Projektová šablona kategorie certificates řídí vydávání certifikátů pro daný projekt.

graph TD
    A["Projektová šablona<br/>category = certificates"] -->|"protocol_config.certificate_template_id"| B["Šablona certifikátu<br/>(podřízený záznam)"]
    B --> C["Vydávací engine<br/>(SignCSR)"]
    C --> D["Vydaný X.509 certifikát"]

    classDef proj fill:#EBF5FB,stroke:#2196F3,stroke-width:2px,color:#1565C0
    classDef cert fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px,color:#2E7D32
    class A proj
    class B,C,D cert

Když vytvoříte projektovou šablonu kategorie certificates, MazeVault na pozadí vytvoří podřízenou šablonu certifikátu a propojí ji přes protocol_config.certificate_template_id. Pole popsaná zde jsou klíče protocol_config této projektové šablony; deserializují se do podřízené šablony certifikátu, kterou spotřebovává vydávací engine.

2. Odkud pochází Subject¶

Subject certifikátu (Common Name, Organization, OU, Email, Locality, State, Country) a jeho Subject Alternative Names nejsou pevně dané v kroku Nastavení certifikátu. Jsou řízeny krokem Proměnné šablony.

V kroku Proměnné definujete proměnné jako COMMON_NAME, ORGANIZATION, ORGANIZATIONAL_UNIT, EMAIL, LOCALITY, STATE, COUNTRY a SAN_DNS. Ty se vyhodnocují pro každou žádost, což umožňuje znovu používat jedinou šablonu pro mnoho konkrétních certifikátů. Krok Nastavení certifikátu proto konfiguruje pouze politiku vydávání a kryptografické parametry — nikdy doslovné hodnoty subjektu.

Jediný přepínač související se subjektem, který se nachází v Nastavení certifikátu, je Přidat Common Name do SAN (add_cn_to_san), protože řídí chování SAN, nikoli hodnotu subjektu.

3. Nastavení certifikátu — referenční přehled parametrů¶

Krok Nastavení certifikátu je rozdělen do orámovaných karet. Každé pole odpovídá klíči protocol_config. Sloupec Kde se uplatní uvádí, kdy hodnota nabývá účinku:

Vydaný certifikát — hodnota se zapíše do vydaného X.509 certifikátu.
Validace / brána — hodnota omezuje nebo podmiňuje žádosti, ale nezapisuje se do certifikátu.
Generování CSR — hodnota je výchozí, použitá pouze když MazeVault generuje pár klíčů a CSR (nepřepisuje CSR dodané zákazníkem).
Rotace — hodnota řídí automatickou obnovu/rotaci.
Směrování — hodnota volí vydávající autoritu.

Identita a záměr¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`code`	Kód šablony	string	odvozeno z názvu	unikátní v rámci org	Metadata	`web-server-tls`
`cert_type`	Typ certifikátu	enum	`""` (Auto)	jedna z hodnot katalogu, nebo prázdné pro odvození z podtypu	Metadata / záměr vydání	`ssl_tls`

Vydávající CA¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`ca_account_id`	CA účet	uuid	žádný	musí odkazovat na nakonfigurovaný CA účet	Směrování	`550e8400-…`
`ca_product_id`	CA produkt	uuid	žádný	vyžaduje CA účet	Směrování	`550e8400-…`
`signature_algorithm`	Algoritmus podpisu	enum	`""` (výchozí CA)	odpovídá názvům Go `x509.SignatureAlgorithm`	Vydaný certifikát	`SHA256WithRSA`
`dcv_method`	Metoda ověření domény	enum	`""` (výchozí poskytovatele/účtu)	`email`, `dns`, `file`; zobrazuje se jen u poskytovatelů, kteří ověřují domény	Objednávka u CA (komerční CA)	`dns`
`order_years`	Délka předplatného (roky)	int	žádný (= 1 rok)	1–6, omezeno `max_years` produktu; zobrazuje se jen u CA s předplatným (SSLMarket)	Objednávka u CA — délka placené objednávky, ne certifikátu	`2`
`tech_contact`	Technický kontakt	objekt	žádný (výchozí z účtu CA)	klíče `title`, `firstname`, `lastname`, `email`, `tel`	Objednávka u CA (komerční CA); žádost může přepsat	`{"email": "pki@example.com"}`
`challenge_type`	Politika ACME výzvy	enum	`auto`	`auto`, `dns-01`, `http-01`; zobrazuje se jen u ACME vydavatelů (vč. SSLMarket v režimu ACME — pouze `http-01`)	Objednávka u CA (ACME)	`http-01`

Pole označená „zobrazuje se jen…“ řídí deklarované schopnosti vydávajícího CA účtu (template_form), ne pevně zadrátované seznamy poskytovatelů. Žádost může přepsat dcv_method, ca_product_id, order_years, tech_contact a voucher tam, kde to poskytovatel dovoluje; hodnota ze šablony je výchozí, kterou žádost dědí.

Klíč a algoritmus¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`key_algorithm`	Algoritmus klíče	enum	`RSA`	`RSA`, `ECDSA`, `Ed25519`	Generování CSR	`ECDSA`
`key_size`	Výchozí velikost klíče	integer	`2048`	platná velikost pro algoritmus (RSA: 2048/3072/4096; ECDSA: 256/384/521; Ed25519: 256)	Generování CSR	`3072`
`allowed_key_sizes`	Povolené velikosti klíče	integer[]	`[]` (libovolná)	podmnožina platných velikostí pro algoritmus	Validace / brána (vynuceno při vydání)	`[2048, 4096]`

Povolené velikosti klíče se vynucují při odeslání i při podpisu

Když je allowed_key_sizes neprázdné, nahrané CSR, jehož bitová délka veřejného klíče není v seznamu, je odmítnuto už při odeslání požadavku — ještě před kontaktováním CA — a interní CA kontrolu zopakuje při podpisu. Prázdný seznam znamená, že je přijata libovolná velikost platná pro daný algoritmus. Systémové šablony (mTLS agentů a gateway) jsou vyjmuty.

Politika Subject Alternative Names (SAN)¶

JSON klíč	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`allow_additional_sans`	Povolit další SAN	boolean	`true`	—	Validace / brána (pouze generované CSR)	`false`
`max_san_count`	Max. počet SAN	integer	`100`	> 0	Validace / brána (generované CSR; pro nahrané CSR použijte `san_config.max_san_count`)	`10`
`san_config.allowed_san_types`	Povolené typy SAN	string[]	`["dns"]`	podmnožina `dns`, `ip`, `email`, `uri`	Validace / brána (generované i nahrané CSR)	`["dns","ip"]`
`san_config.san_validation_pattern`	Validační vzor SAN	regex	—	platný regulární výraz Go	Validace / brána (generované i nahrané CSR)	`^[a-z0-9.-]+\.example\.com$`
`san_config.max_san_count`	Max. počet SAN (nahrané CSR)	integer	—	> 0	Validace / brána (nahrané CSR)	`5`
`san_config.require_san`	Vyžadovat SAN	boolean	`false`	—	Validace / brána (nahrané CSR)	`true`

Nahrané CSR se validují pouze proti explicitním klíčům v san_config

Šablony bez san_config nadále přijímají každé nahrané CSR, takže existující šablony nezačnou odmítat IP nebo URI SAN. Jakmile šablona v san_config deklaruje allowed_san_types, san_validation_pattern, max_san_count nebo require_san, musí nahrané CSR tato pravidla splnit. Sloupce allow_additional_sans a max_san_count na nejvyšší úrovni platí pouze pro požadavky generované MazeVaultem. require_san = true odmítne CSR pouze s CN bez SAN, které moderní TLS klienti odmítají; používejte ho pro šablony TLS serverů.

Platnost¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`validity_days`	Platnost (dny)	integer	`365`	> 0	Vydaný certifikát (`NotAfter = NotBefore + validity_days`)	`90`
`min_validity_days`	Min. platnost (dny)	integer	`30`	≤ `max_validity_days`	Validace / brána	`30`
`max_validity_days`	Max. platnost (dny)	integer	`825`	≥ `min_validity_days`	Validace / brána	`825`

Použití klíče a rozšířené použití klíče¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`key_usage`	Použití klíče	string[]	`[]`	podmnožina 9 bitů dle RFC 5280 §4.2.1.3	Vydaný certifikát	`["digitalSignature","keyEncipherment"]`
`extended_key_usage`	Rozšířené použití klíče	string[]	`[]`	podmnožina 6 podporovaných EKU OID	Vydaný certifikát	`["serverAuth","clientAuth"]`
`add_cn_to_san`	Přidat CN do SAN	boolean	`true`	—	Generování CSR (chování SAN)	`true`

Hodnoty Použití klíče: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly.

Hodnoty Rozšířeného použití klíče: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, ocspSigning.

Omezení a politiky CA¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`is_ca`	Vydat jako CA certifikát	boolean	`false`	—	Vydaný certifikát (Basic Constraints)	`false`
`max_path_length`	Max. délka cesty	integer	`0`	smysluplné pouze když je `is_ca` true	Vydaný certifikát (pathLenConstraint)	`0`
`policy_identifiers`	Identifikátory politik	string[]	`[]`	OID v tečkovém zápisu	Vydaný certifikát (certificate policies)	`["1.3.6.1.4.1.311.21.10"]`
`certificate_policies`	Politiky certifikátu	string[]	`[]`	OID v tečkovém zápisu	Vydaný certifikát (sloučeno s `policy_identifiers`, deduplikováno)	`["2.23.140.1.2.1"]`

Délka cesty CA a zpracování politik

Když je is_ca true a max_path_length je 0, certifikát je omezen na pathlen:0 (může vydávat koncové certifikáty, ale ne další CA). policy_identifiers a certificate_policies se slučují a deduplikují; neplatné OID řetězce se přeskočí s varováním, místo aby přerušily vydání.

Obnova a rotace¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`auto_renewal_enabled`	Automatická obnova	boolean	`true`	—	Rotace	`true`
`renewal_days_before_expiry`	Dnů před vypršením pro obnovu	integer	`30`	> 0	Rotace	`30`
`renewal_key_policy`	Politika klíče při obnově	enum	`regenerate`	`regenerate` nebo `reuse`	Rotace	`regenerate`

Přednost politiky klíče při obnově

Šablona, která pevně nastaví regenerate (generovat nový pár klíčů při obnově), přepíše volnější organizační politiku znovupoužití klíče. reuse zachová stávající soukromý klíč. Když není v šabloně nastavena žádná hodnota, uplatní se organizační politika obnovy.

Governance¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`require_approval`	Vyžadovat schválení před vydáním	boolean	`false`	—	Validace / brána	`false`

Integrace s externí CA¶

Klíč JSON	Popisek v UI	Typ	Výchozí	Omezení	Kde se uplatní	Příklad
`external_template_name`	Název externí šablony	string	`""`	použito pouze s externí CA (např. ADCS)	Směrování (externí CA)	`WebServerV2`
`external_template_oid`	OID externí šablony	string	`""`	OID v tečkovém zápisu	Směrování (externí CA)	`1.3.6.1.4.1.311.21.8.1`

4. Co se zapíše do vydaného certifikátu¶

Pro rychlou orientaci zde je rozdělení každého řízeného pole:

Zapsáno do vydaného certifikátu: validity_days, key_usage, extended_key_usage, is_ca, max_path_length, policy_identifiers, certificate_policies, signature_algorithm.
Pouze validace / brána (není v certifikátu): allowed_key_sizes, min_validity_days, max_validity_days, require_approval.
Chování rotace: auto_renewal_enabled, renewal_days_before_expiry, renewal_key_policy.
Pouze výchozí hodnoty pro generování CSR: key_algorithm, key_size, add_cn_to_san. Uplatní se, když MazeVault generuje pár klíčů a CSR; nepřepisují CSR dodané zákazníkem (s výjimkou allowed_key_sizes, které se vynucuje při podpisu pro všechny CSR).
Směrování / výběr: ca_account_id, ca_product_id, external_template_name, external_template_oid.

5. Související příručky¶

Správa certifikátů — žádost, odvolání, import a export certifikátů.
Automatizace certifikátů ACME — automatické vydávání přes ACME.