Skip to content

windows_certificate

Experimental. A certificate file on a Windows host, imported into a certificate store: a CA’s .cer into Root, or a server’s .pfx, with its private key, into My for IIS.

Experimental. New, and tested on GitHub’s Windows Server 2022 and 2025 runners, not yet on an Azure server. See Windows readiness.

Use windows_certificate to import a certificate file into one of a Windows host’s certificate stores: your internal CA’s certificate into Root, or a web server’s .pfx, private key and all, into My for IIS. It’s the Import-Certificate or Import-PfxCertificate you’d otherwise run by hand, and a plan shows whether the certificate is still there.

Trust an internal CA on every server:

step "corp_ca" {
windows_certificate {
path = "C:\\certs\\corp-root-ca.cer"
store_name = "Root"
}
}

A server certificate with its private key, for IIS. Give the password from an ephemeral variable, so it stays out of state and plan files:

step "web_cert" {
windows_certificate {
path = "C:\\certs\\www.pfx"
store_name = "My"
password_wo = "use-an-ephemeral-variable-here"
}
}

Put the file on the host first, with a windows_file step.

Name Type Required Description
on_remove string No What happens on the host when this resource is removed: “forget” (default) leaves the certificate in the store, “delete” takes it out. The file stays either way.
password_wo string No Write-only: a .pfx’s password, never kept in state or plan files.
path string Yes The file on the host, ending in .cer, .crt, .der, .pfx or .p12, such as C:\certs\web.pfx. A .pfx or .p12 is imported with its private key.
state string No “present” (default), or “absent” to take the certificate out of the store.
store_location string No “LocalMachine” (default) or “CurrentUser”, the account Conn3x logs in as.
store_name string Yes The store, such as My (personal, where IIS looks), Root, CA, TrustedPeople or WebHosting.

Conn3x sets these; reference them as conn3x_windows_certificate.<circuit>__<step>["<host>"].<name>.

Name Type Description
file_sha256 string The file’s SHA-256 at the import. A different file at path, such as a renewed certificate, plans a new import.
in_sync bool Whether the store had the certificate, and the file was still the one imported, at the last refresh.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.
thumbprint string The imported certificate’s thumbprint, which a refresh looks for in the store. For a .pfx with its chain, the one with the private key.

A step lowers to the conn3x_windows_certificate resource, one instance per host, and connects with its circuit’s ssh block.

Applying. Conn3x imports the file into store_location and store_name: a .pfx or .p12 with Import-PfxCertificate, its private key marked not exportable, and anything else with Import-Certificate. It records the certificate’s thumbprint and the file’s file_sha256. For a .pfx that brings its chain with it, the thumbprint is the certificate with the private key.

The password. password_wo goes to the host on standard input, never on a command line, and never into state or a plan file. A wrong password fails the step without repeating it.

Reading. On every plan, Conn3x looks for the recorded thumbprint in the store, and hashes the file if it’s still there. in_sync is true when the certificate is in the store, with its private key for a .pfx, and the file is the one imported. Removing the file after the import, as many do with a .pfx, is fine.

Renewal. Put the renewed file at the same path, and the next plan sees a different file and imports it. The old certificate stays in the store, since a site may still be bound to it; take it out once nothing uses it.

Changes. Changing state updates the store in place. Changing path, store_location or store_name replaces the step.

on_remove = "forget", the default, leaves the certificate in the store. on_remove = "delete" takes it out by its thumbprint. The file stays either way.