Skip to main content
Video tutorial · 0:58

Import (bring-your-own)

Import a certificate that was issued outside CertAutoPilot — a vendor wildcard, an enterprise/offline CA, or a partner-supplied cert — and manage it like any other certificate for everything except issuance and renewal. Once imported it can be distributed and bound to targets, downloaded (PEM/PFX/JKS/DER), and shows up in risk scoring, the timeline, and expiry views.

There is no CA behind an imported certificate, so it is exempt from every renewal-automation path. "Renewal" is you re-importing a fresh certificate — the old version is kept in history.

What you provide​

Bring the certificate and its key in whichever form you have them. The import page offers three:

You haveWhat to provide
PEM textPaste the leaf (a full-chain bundle or a PEM PKCS#7 bundle is accepted too), the optional chain, and the private key.
Certificate + key filesA certificate file in PEM, DER (.cer / .der) or PKCS#7 (.p7b) — the leaf, optionally with its intermediates — and the private-key file (PEM).
A PFX / P12 fileThe PKCS#12 export alone: it carries the certificate, its chain and the private key. Enter its password (leave it empty when the file has none). Modern (AES) and legacy (3DES / RC2) files are both read.
FieldRequiredNotes
Certificate (leaf)YesPEM, DER or PKCS#7 — or inside the PKCS#12 file.
Chain / intermediatesRecommendedPEM text (a PEM PKCS#7 block is read too). Needed so chain-dependent targets validate. The root CA is excluded from the served chain automatically if you include it.
Private keyYesPEM — or inside the PKCS#12 file — and it must match the leaf. A passphrase-protected key is accepted: enter its passphrase (PKCS#8 ENCRYPTED PRIVATE KEY and the older Proc-Type / DEK-Info form).
Name / Owner / DescriptionName requiredMetadata only.

The PKCS#12 password and the key passphrase are used once, to open the upload, and are never stored. The private key is stored unencrypted under CertAutoPilot's envelope encryption, like every other key, so download and distribution behave exactly as for a pasted PEM key. Uploads are limited to about 700 KB per file, and to about 1 MB for all files of one import together.

Chain handling​

Classification is leaf-order-independent — paste the blocks in any order:

  • The leaf is the certificate whose public key matches the uploaded private key.
  • Intermediates are the non-leaf CA certificates, re-ordered leaf → up.
  • A self-signed root, if present, is excluded from the distributed chain (trust anchors belong in the client's trust store, not the served chain). Its expiry is parsed, but it is not stored or scored today — the certificate risk score has no expired-root factor (that signal exists only in the risk scoring of discovered certificates).
  • Leaf-only uploads are accepted with a warning — some targets are fine with a leaf-only chain; chain-dependent ones need the intermediates.

How to import​

  1. Certificates → Import (button beside Issue Certificate).
  2. Choose how you bring it (Paste PEM, Certificate + key files or PFX / P12 file), add the files or text, and give it a name.
  3. Submit. The certificate is stored and becomes active immediately (synchronous — no job, no CA round-trip), tagged Imported.

You can also POST /api/v1/projects/{projectId}/certificates/import with a JSON body: name, owner?, description?, chain_pem? and one of

  • cert_pem (text) or cert_file_base64 (the file bytes, base64 — PEM, DER or PKCS#7), plus key_pem and key_passphrase?;
  • pkcs12_base64 (the .pfx / .p12 bytes, base64) plus pkcs12_password? — then cert_pem, cert_file_base64, key_pem and key_passphrase must be absent.

Requires the Admin role and consumes a certificate license slot.

Why Admin, not Operator

Import makes a certificate active and distributes it immediately, without going through the issuance-approval workflow. Requiring Admin prevents a non-privileged operator from using import to bypass a project's approval policy for issuance.

Refreshing — re-import​

When the certificate nears expiry (you still get expiry notifications), open its detail page and click Re-import, or POST …/certificates/{id}/reimport with a fresh certificate and key in any of the shapes above (Admin role). This creates a new current version; the previous version is retained in the certificate's history (subject to the history-retention setting), and distribution targets are re-triggered automatically. Re-import only works on an already-imported certificate.

The domains, primary domain, and key type are re-derived from the new leaf on every re-import, so a refresh whose SANs or key algorithm changed stays accurate.

Re-importing with different domains + templated paths

If you re-import a certificate whose domains differ from the original and its SSH/WinRM distribution uses a ${{ CAP_PRIMARY_DOMAIN }} / ${{ CAP_DOMAIN_SLUG }} variable inside a file path, the new domain renders a new path: the file is written there and the old-path file is left behind (these two modules don't reconcile old paths). Auto-named object modules (F5/NetScaler/Vault/Kubernetes) are unaffected — they reconcile the rename via per-certificate state. For a same-domain refresh (the normal case) nothing changes.

What is exempt​

Imported certificates are deliberately excluded from CA-driven automation:

  • No auto-renew — auto_renew is forced off and the renewal/rescue/ARI scheduler sweeps skip them.
  • Manual Renew / Re-issue / Revoke are rejected (there is no CA to renew or revoke against). Use Delete to retire an imported certificate, and Re-import to refresh it.
  • Certificate policy is not evaluated on import — an import records an external fact rather than requesting issuance.

What still applies: it flips to expired when it passes its notAfter, expiring-soon notifications fire (prompting a re-import), and distribution, download, risk, and timeline all work unchanged.

Corner cases​

  • Key does not match the leaf, malformed PEM, or a missing key → rejected (422).
  • Encrypted key without its passphrase → rejected (422, "enter its passphrase"); a wrong passphrase or PKCS#12 password → rejected with "wrong password" (the password is never echoed). A passphrase sent for a key that is not encrypted → rejected, so a mix-up is not silently ignored.
  • Old PKCS#5 v1 key encryption (openssl pkcs8 -v1 …) → rejected; re-export it with openssl pkcs8 -topk8 -v2 aes256.
  • PKCS#7 file in BER encoding (indefinite lengths, written by some Windows tools) → rejected; convert it with openssl pkcs7 -in file.p7b -outform DER -out file-der.p7b.
  • PKCS#12 file without a private key, or written without an integrity MAC (openssl pkcs12 -export -nomac) with a password → rejected. A file without a MAC and without a password is accepted (it is not protected either way).
  • The same certificate twice (a leaf pasted and also inside the .p7b that came with it) → treated as one certificate.
  • Already-expired leaf → rejected (distribution needs an active cert; re-import is the refresh path).
  • Expired intermediate in the chain → rejected — the served chain would be broken; re-bundle the current intermediate.
  • Too many certificates in the upload (more than 16, counting the certificates inside a PKCS#7 bundle) → rejected; provide only the leaf and its intermediates.
  • Weak/non-standard key (e.g. RSA-1024) → accepted (policy is skipped); it surfaces through risk scoring instead.
  • Ed25519 key → accepted, but stored with a non-standard key-type label the UI/policy don't recognize; public CAs don't issue Ed25519 TLS certs, so it's outside the supported set.

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Import an Existing Certificate (PFX) and Re-import a New VersionYouTube ↗