{"id":16883017,"url":"https://github.com/tsaarni/certyaml","last_synced_at":"2026-02-28T10:11:55.805Z","repository":{"id":37001264,"uuid":"232423626","full_name":"tsaarni/certyaml","owner":"tsaarni","description":"Declarative way to create x509 certificates for test environments.","archived":false,"fork":false,"pushed_at":"2024-09-10T17:19:30.000Z","size":148,"stargazers_count":13,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-14T16:09:53.253Z","etag":null,"topics":["certificate","certificates","go","golang","pki","testing","x509"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsaarni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-07T21:48:02.000Z","updated_at":"2024-09-10T17:19:34.000Z","dependencies_parsed_at":"2023-12-20T12:42:20.921Z","dependency_job_id":"dee188f9-4217-490f-891c-82b85143b060","html_url":"https://github.com/tsaarni/certyaml","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fcertyaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fcertyaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fcertyaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsaarni%2Fcertyaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsaarni","download_url":"https://codeload.github.com/tsaarni/certyaml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243847062,"owners_count":20357317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["certificate","certificates","go","golang","pki","testing","x509"],"created_at":"2024-10-13T16:10:01.789Z","updated_at":"2026-02-28T10:11:55.797Z","avatar_url":"https://github.com/tsaarni.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# certyaml\n\nDeclarative way to create x509 certificates for test environments.\nNo more storing test certificates and private keys in the repository!\n\n![](https://github.com/tsaarni/certyaml/workflows/unit-tests/badge.svg)\n[![Go Reference](https://pkg.go.dev/badge/github.com/tsaarni/certyaml.svg)](https://pkg.go.dev/github.com/tsaarni/certyaml)\n\n## Table of Contents\n\n- [Description](#description)\n- [Using certyaml](#using-certyaml)\n- [Installing](#installing)\n- [YAML Syntax](#yaml-syntax)\n- [Go API](#go-api)\n\n## Description\n\nCertyaml is a command line tool and a Go API for issuing certificates.\nIt is similar to `openssl` or `cfssl` which can also be used for issuing certificates, but certyaml provides simpler way to define complete PKI hierarchies with a compact [YAML syntax](#YAML-syntax) or directly from Go code with a simple API.\n\nCertyaml is targeted for developers who need to set up a private PKI for test environments.\nIt cannot be used for production environments where publicly trusted certificates are needed.\n\nIf you program in other languages, check out following projects:\n\n- [java-certy](https://github.com/tsaarni/java-certy)\n- [python-certy](https://github.com/tsaarni/python-certy)\n\n## Using certyaml\n\n```\nUsage: certyaml [-d destination] [certs.yaml]\n\nCreates certificates and keys according to manifest file in YAML format.\nBy default it reads `certs.yaml` as a manifest file and creates files\nin current directory.\n\n  -d string\n        Short for --destination\n  -destination string\n        Destination directory where to create the certificates and keys\n```\n\n### Installing\n\n**Release builds**\n\nRelease builds are available for download in [releases page](https://github.com/tsaarni/certyaml/releases).\n\n**Compiling from source code**\n\nGo compiler is required to build `certyaml` binary\n\n```bash\ngo install github.com/tsaarni/certyaml/cmd/certyaml@latest\n```\n\nThe executable will be stored in the go path, by default `~/go/bin/certyaml`.\n\nAlternatively, you can run the tool without installing it:\n\n```bash\ngo run github.com/tsaarni/certyaml/cmd/certyaml@latest\n```\n\n\n### Using certyaml\n\nCreate a YAML manifest file which describes the wanted PKI hierarchy and end-entity certificates\n\n```console\n$ cat \u003ecerts.yaml \u003c\u003cEOF\nsubject: cn=server-root-ca\n---\nsubject: cn=intermediate-ca\nissuer: cn=server-root-ca\nca: true\n---\nsubject: cn=myserver\nissuer: cn=intermediate-ca\nsans:\n- DNS:myserver.example.com\n- DNS:foo\n---\nsubject: cn=selfsigned-server\nca: false\nkey_usages:\n- KeyEncipherment\n- DigitalSignature\n---\nsubject: cn=fixedtime\nissuer: cn=intermediate-ca\nnot_before: 2020-01-01T09:00:00Z\nnot_after: 2020-02-01T10:10:10Z\n---\nsubject: cn=shortlived\nissuer: cn=intermediate-ca\nexpires: 1m\n---\nsubject: cn=client-root-ca\n---\nsubject: CN=John Doe,OU=People,O=Company\nfilename: clientcert\nissuer: cn=client-root-ca\nEOF\n```\n\nGenerate the certificates\n\n```console\n$ certyaml\nLoading manifest: certs.yaml\nReading state: certs.state\nWriting: server-root-ca.pem server-root-ca-key.pem\nWriting: intermediate-ca.pem intermediate-ca-key.pem\nWriting: myserver.pem myserver-key.pem\nWriting: selfsigned-server.pem selfsigned-server-key.pem\nWriting: fixedtime.pem fixedtime-key.pem\nWriting: shortlived.pem shortlived-key.pem\nWriting: client-root-ca.pem client-root-ca-key.pem\nWriting: clientcert.pem clientcert-key.pem\nWriting state: certs.state\n\n$ ls -l\ntotal 72\n-rw-r--r-- 1 tsaarni tsaarni  483 Jun 15 17:08 certs.state\n-rw-rw-r-- 1 tsaarni tsaarni  588 Jun 15 17:07 certs.yaml\n-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 clientcert-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1062 Jun 15 17:08 clientcert.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 client-root-ca-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 client-root-ca.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 fixedtime-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1017 Jun 15 17:08 fixedtime.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 intermediate-ca-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 intermediate-ca.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1679 Jun 15 17:08 myserver-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1066 Jun 15 17:08 myserver.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 selfsigned-server-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1029 Jun 15 17:08 selfsigned-server.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 server-root-ca-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1046 Jun 15 17:08 server-root-ca.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1675 Jun 15 17:08 shortlived-key.pem\n-rw-rw-r-- 1 tsaarni tsaarni 1017 Jun 15 17:08 shortlived.pem\n```\n\nYou can change parameters of the certificates in the YAML manifest or remove generated certificate files from the filesystem and then run `certyaml` again.\nOnly changed or missing certificates will be regenerated.\n\n```console\n$ rm myserver*\n$ certyaml\nLoading manifest: certs.yaml\nReading state: certs.state\nNo changes in manifest: skipping server-root-ca\nNo changes in manifest: skipping intermediate-ca\nWriting: myserver.pem myserver-key.pem\nNo changes in manifest: skipping selfsigned-server\nNo changes in manifest: skipping fixedtime\nNo changes in manifest: skipping shortlived\nNo changes in manifest: skipping client-root-ca\nNo changes in manifest: skipping clientcert\nWriting state: certs.state\n```\n\n### YAML syntax\n\n| tag | description | examples |\n| --- | ----------- | -------- |\n| subject | Distinguished name for the certificate. `subject` is the only mandatory field and it must be unique. | `CN=Joe` |\n| sans | List of values for x509 Subject Alternative Name extension. | `DNS:www.example.com`, `IP:1.2.3.4`, `URI:https://www.example.com`, `email:user@example.com` |\n| key_type | Certificate key algorithm. Default value is `EC` (elliptic curve). | `EC`, `RSA` or `ED25519` |\n| key_size | The key length in bits. Default value is 256 if `key_size` is not defined. | For key_type EC: `256`, `384`, `521`. For key_type RSA: `1024`, `2048`, `4096`. For key_type ED25519: `256`. |\n| expires | Certificate NotAfter field is calculated by adding duration defined in `expires` to current time. Default value is 8760h (one year) if `expires` is not defined. `not_after` takes precedence over `expires`. | `1s`, `10m`, `1h` |\n| key_usages | List of values for x509 key usage extension. If `key_usages` is not defined, `CertSign` and `CRLSign` are set for CA certificates, `KeyEncipherment` and `DigitalSignature` are set for end-entity certificates. | `DigitalSignature`, `ContentCommitment`, `KeyEncipherment`, `DataEncipherment`, `KeyAgreement`, `CertSign`, `CRLSign`, `EncipherOnly`, `DecipherOnly` |\n| ext_key_usages | List of values for x509 extended key usage extension. Not set by default. | `Any`, `ServerAuth`, `ClientAuth`, `CodeSigning`, `EmailProtection`, `IPSECEndSystem`, `IPSECTunnel`, `IPSECUser`. `TimeStamping`, `OCSPSigning`, `MicrosoftServerGatedCrypto`, `NetscapeServerGatedCrypto`, `MicrosoftCommercialCodeSigning`, `MicrosoftKernelCodeSigning` |\n| issuer | Distinguished name of the issuer. Issuer must be declared as a certificate in the manifest file before referring to it as issuer. Self-signed certificate is generated if `issuer` is not defined. | `CN=myca` |\n| filename | The basename of the generated certificate and private key files. The files created to destination directory will be [filename].pem and [filename]-key.pem will. If `filename` is not defined, CN field value from subject will be used as filename. | `clientcert` |\n| ca | Set certificate is / is not CA. If `ca` is not defined, `true` is set by default for self-signed certificates. | `true` or  `false` |\n| not_before | Certificate is not valid before this time ([RFC3339 timestamp](https://tools.ietf.org/html/rfc3339)). | `2020-01-01T09:00:00Z` |\n| not_after | Certificate is not valid after this time ([RFC3339 timestamp](https://tools.ietf.org/html/rfc3339)). | `2020-01-01T09:00:00Z` |\n| serial | Serial number for the certificate. Default value is current time in nanoseconds. | `123` |\n| revoked | When `true` the serial number of the certificate will be written in `[issuer]-crl.pem`.  Default value is `false`. The file will be written only if at least one certificate is revoked. CRL `ThisUpdate` is set to current time and `NextUpdate` one week after. Self-signed certificates cannot be revoked. | `true`, `false` |\n| crl_distribution_points | List of URLs for X509 CRL Distribution Points extension. | `http://example.com/crl.pem` |\n| ocsp | List of URLs for X509 OCSP responder (Authority Information Access extension). | `http://ocsp.example.com` |\n\n## Go API\n\nFor using certyaml in Go applications, see [API documentation](https://pkg.go.dev/github.com/tsaarni/certyaml).\n\nFor examples on how to use the API use, see [`examples/go-api`](examples/go-api) and [`certificate_test.go`](certificate_test.go).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsaarni%2Fcertyaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsaarni%2Fcertyaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsaarni%2Fcertyaml/lists"}