vault PKI secrets engine quick start intermediate CA setup The PKI secrets engine for Vault generates TLS certificates certificates were issued directly from the root certificate authority layout docs In the first Quick Start guide vault docs secrets pki quick start root ca page title PKI Secrets Engines Quick Start Intermediate CA Setup

layout  docs page title   PKI   Secrets Engines  Quick Start  Intermediate CA Setup  description  The PKI secrets engine for Vault generates TLS certificates         PKI secrets engine   quick start   intermediate CA setup  In the  first Quick Start guide   vault docs secrets pki quick start root ca   certificates were issued directly from the root certificate authority  As described in the example  this is not a recommended practice  This guide builds on the previous guide s root certificate authority and creates an intermediate authority using the root authority to sign the intermediate s certificate        Mount the backend  To add another certificate authority to our Vault instance  we have to mount it at a different path      shell session   vault secrets enable  path pki int pki Successfully mounted  pki  at  pki int             Configure an intermediate CA     shell session   vault secrets tune  max lease ttl 43800h pki int Successfully tuned mount  pki int        That sets the maximum TTL for secrets issued from the mount to 5 years  This value should be less than or equal to the root certificate authority   Now  we generate our intermediate certificate signing request      shell session   vault write pki int intermediate generate internal common name  myvault com Intermediate Authority  ttl 43800h Key Value csr      BEGIN CERTIFICATE REQUEST      MIICsjCCAZoCAQAwLTErMCkGA1UEAxMibXl2YXVsdC5jb20gSW50ZXJtZWRpYXRl IEF1dGhvcml0eTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJU1Qh8l BW16WHAu34Fy92FnSy4219WVlKw1xwpKxjd95xH6WcxXozOs6oHFQ9c592bz51F8 KK3FFJYraUrGONI5Cz9qHbzC1mFCmjnXVXCoeNKIzEBG0Y ehH7MQ1SvDCyvaJPX ItFXaGf6zENiGsApw3Y3lFr0MjPzZDBH1p4Nq3aA6L2BaxvO5vczdQl5tE2ud zs GIdCWnl1ThDEeiX1Ppduos dx3gaZa9ly3iCuDMKIL9yK5XTBTgKB6ALPApekLQB kcUFbOuMzjrDSBe9ytu65yICYp26iAPPA8aKTj5cUgscgzEvQS66rSAVG unrWxb wbl8b7eQztCmp60CAwEAAaBAMD4GCSqGSIb3DQEJDjExMC8wLQYDVR0RBCYwJIIi bXl2YXVsdC5jb20gSW50ZXJtZWRpYXRlIEF1dGhvcml0eTANBgkqhkiG9w0BAQsF AAOCAQEAZA9A1QvTdAd45 Ay55FmKNWnis1zLjbmWNJURUoDei6i6SCJg0YGX1cZ WkD0ibxPYihSsKRaIUwC2bE8cxZM57OSs7ISUmyPQAT2IHTHvuGK72qlFRBlFOzg SHEG7gfyKdrALphyF8wM3u4gXhcnY3CdltjabL3YakZqd3Ey4870 0XXeo5c4k7w   n9M4xED4TnXYCGfLAlu5WWKSeCvu9mHXnJcLo1MiYjX7KGey xYYbfxHSPm4ul tI6Vf59zDRscfNmq37fERD3TiKP0QZNGTSRvnrxrx2RUQGXFywM8l4doG8nS5BxU 2jP20cdv0lJFvHr9663 8B  F5L6Yw        END CERTIFICATE REQUEST           Take the signing request from the intermediate authority and sign it using another certificate authority  in this case the root certificate authority generated in the first example      shell session   vault write pki root sign intermediate csr  pki int csr format pem bundle ttl 43800h Key             Value certificate          BEGIN CERTIFICATE      MIIDZTCCAk2gAwIBAgIUENxQD7KIJi1zE jEiYqAG1VC4NwwDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMTI4MTcwNzIzWhcNMjIx MTI3MTcwNzUzWjAtMSswKQYDVQQDEyJteXZhdWx0LmNvbSBJbnRlcm1lZGlhdGUg QXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5seNV4Yd uCMX0POUUuSzCBiR3Cyf9b9tGsCX7UfvZmjPs Fl X Ovq6UtHM9RuTGlyfFrCWy pflO7mc0H8PBzlvhv1WQet5aRyUOXkG6iYmooG9iobIY8z TZCaCF605pgygfOaS DIlwOdJkfiXxGpQ00pfIwe Y2OK2I5e36u0E2EA6kXvcfexLjQGFPbod H0R29Ro  GwOJ6MpSHqB77mF025x1y08EtqT1z1kFCiDzFSkzNZEZYWljhDS6ZRY9ctzKufm 5CkUwmvCVRI2CivDJvmfhXyv0DRoq4IhYdJHo179RSObq3BY9f9LQ0balNLiM0Ft O8f0urTqUAbySwIDAQABo4GTMIGQMA4GA1UdDwEB wQEAwIBBjAPBgNVHRMBAf8E BTADAQH MB0GA1UdDgQWBBSQgTfcMrKYzyckP6t 0iVQkl0ZBDAfBgNVHSMEGDAW gBRccsCARqs3wQDjW7JMNXS6pWlFSDAtBgNVHREEJjAkgiJteXZhdWx0LmNvbSBJ bnRlcm1lZGlhdGUgQXV0aG9yaXR5MA0GCSqGSIb3DQEBCwUAA4IBAQABNg2HxccY DwRpsJ sxA0BgDyF tYtOlXViVNv6Z nOU0nNhQSCjfzjYWmBg25nfKaFhQSC3b7 fIW e7it FLVrCgaqdysoxljqhR0gXMAy8S ubmskPWjJiKauJB5bfB59Uf2GP6j zimZDu6WjWvvgkKcJqJEbOOS9DWBvCTdmmml1NMXZtcytpod2Y7mxninqNRx3qpx Pst4vgAbyM 3zLSzkyUD MXIyRXwxktFlyEYBHvMd9OoHzLO6WLxk22FyQQ w4by NfXJY4r5pj6a4lJ6pPuqyfBhidYMTdY3AI7w QRGk4qQv1iDmnZspk2AxdbR5Lwe YmChIML f  S      END CERTIFICATE      expiration      1669568873 issuing ca           BEGIN CERTIFICATE      MIIDNTCCAh2gAwIBAgIUdR44qhhyh3CZjnCtflGKQlTI8NswDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMTI4MTYxODA2WhcNMjcx MTI2MTYxODM1WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBANTPnQ2CUkuLrYT4V6 IIK gWFZXFG4lWTmgM5Zh PDquMhLEikZCbZKbupouBI8MOr5i8tycENaTnSs9dBwVEOWAHbLkliVgvCKgLi0F PfPM87FnBoKVctO2ip8AdmYcAt wc096dWBG6eKLVP5xsAe7NcYDtF inHgEZ22q ZjGVEyC6WntIASgULoHGgHakPp1AHLhGm8nL5YbusWY7RgZIlNeGWLVoneG0pxdV 7W1SPO67dsQyq58mTxMIGVUj5YE1q7 C6OhCTnAHc sRm0oUehPfO8kY4NHpCJGv nDRdJi6k6ewk94c0KK2tUUM TN6ZSRfx6ccgfPH8zNcVPVcCAwEAAaN7MHkwDgYD VR0PAQH BAQDAgEGMA8GA1UdEwEB wQFMAMBAf8wHQYDVR0OBBYEFFxywIBGqzfB AONbskw1dLqlaUVIMB8GA1UdIwQYMBaAFFxywIBGqzfBAONbskw1dLqlaUVIMBYG A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQBgvsgpBuVR iKVdXXpFyoQLImuoaHZgaj5tuUDqnMoxOA1XWW6SVlZmGfDQ7 u5NBkp2cGSDRGm ARHJTeURvdZIwdFdGkNqfAZjutRjjQOnXgS65ujZd7AnlZq1v0ZOZqVVk9YEOhOe Rh2MjnHGNuiLBib1YNQHNuRef1mPwIE2Gm Tz z3JPHtkKNIKbn60zHrIIM OT2Z HYjcMUcqXtKGYfNjVspJm3lSDUoyJdaq80Afmy2Ez1Vt9crGG3Dj8mgs59lEhEyo MDVhOP116M5HJfQlRPVd29qS8pFrjBvXKjJSnJNG1UFdrWBJRJ3QrBxUQALKrJlR g5lvTeymHjS       END CERTIFICATE      serial number   10 dc 50 0f b2 88 26 2d 73 13 f8 c4 89 8a 80 1b 55 42 e0 dc      Now set the intermediate certificate authorities signing certificate to the root signed certificate      shell session   vault write pki int intermediate set signed certificate  signed certificate pem Success  Data written to  pki int intermediate set signed      The intermediate certificate authority is now configured and ready to issue certificates        Set URL configuration  Generated certificates can have the CRL location and the location of the issuing certificate encoded  These values must be set manually  but can be changed at any time      shell session   vault write pki int config urls issuing certificates  http   127 0 0 1 8200 v1 pki int ca  crl distribution points  http   127 0 0 1 8200 v1 pki int crl  Success  Data written to  pki int ca urls           Configure a role  The next step is to configure a role  A role is a logical name that maps to a policy used to generate those credentials  For example  let s create an  example dot com  role      shell session   vault write pki int roles example dot com       allowed domains example com       allow subdomains true max ttl 72h Success  Data written to  pki int roles example dot com           Issue certificates  By writing to the  roles example dot com  path we are defining the  example dot com  role  To generate a new certificate  we simply write to the  issue  endpoint with that role name  Vault is now configured to create and manage certificates      shell session   vault write pki int issue example dot com       common name blah example com Key                 Value                           certificate              BEGIN CERTIFICATE      MIIDbDCCAlSgAwIBAgIUPiAyxq nIE6xlWf7hrzLkPQxtvMwDQYJKoZIhvcNAQEL BQAwMzExMC8GA1UEAxMoVmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgU3ViIEF1 dGhvcml0eTAeFw0xNjA5MjcwMDA5MTNaFw0xNjA5MjcwMTA5NDNaMBsxGTAXBgNV BAMTEGJsYWguZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK AoIBAQDJAYB04IVdmSC TimaA6BbXlvgBTZHL5wBUTmO4iHhenL0eDEXVe2Fd7Yq 75LiBJmcC96hKbqh5rwS8KwN9ElZI52 mSMC IvoNlYHAf7shwfsjrVx3q7 bTFg lz6wECn1ugysxynmMvgQD pliRkxTQ7RMh4Qlh75YG3R9BHy9ZddklZp0aNaitts 0uufHnN1UER wxBCZdWTUu34KDL9I6yE7Br0slKKHPdEsGlFcMkbZhvjslZ7DGvO 974S0qtOdKiawJZbpNPg0foGZ3AxesDUlkHmmgzUNes sjknDYTHEfeXM6Uap0j6 XvyhCxqdeahb Vtibg0z9I0IusJbAgMBAAGjgY8wgYwwDgYDVR0PAQH BAQDAgOo MB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU 5oy0rL7 TT0wX7KZK7qcXqgayNwwHwYDVR0jBBgwFoAUgM37P8oXmA972ztLfw b1eIY5now GwYDVR0RBBQwEoIQYmxhaC5leGFtcGxlLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEA CT2vI6 taeLTw6ZulUhLXEXYXWZu1gF8n2COjZzbZXmHxQAoZ3GtnSNwacPHAyIj f3cA9Moo552y39LUtWk wgFtQokWGK7LXglLaveNUBowOHq xk0waiIinJcgTG53 Z qnbJnTjAOG7JwVJplWUIiS1avCksrHt7heE2EGRGJALqyLZ119 PW6ogtCLUv1 X8RCTw UkIF LT sLF0bXWy4Hn38Gjwj1MVv1l76cEGOVSHyrYkN 6AMnAP58L5  IWE9tN3oac4x7jhbuNpfxazIJ8Q6l Up5U5Evfbh6N1DI0 gFCP20fMBkHwkuLfZ 2ekZoSeCgFRDlHGkr7Vv9w        END CERTIFICATE      issuing ca               BEGIN CERTIFICATE      MIIDijCCAnKgAwIBAgIUB28DoGwgGFKL7fbOu9S4FalHLn0wDQYJKoZIhvcNAQEL BQAwLzEtMCsGA1UEAxMkVmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgQXV0aG9y aXR5MB4XDTE2MDkyNzAwMDgyMVoXDTI2MDkxNjE2MDg1MVowMzExMC8GA1UEAxMo VmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgU3ViIEF1dGhvcml0eTCCASIwDQYJ KoZIhvcNAQEBBQADggEPADCCAQoCggEBAOSCiSij4wy1wiMwvZt rtU3IaO6ZTn9 LfIPuGsR5 QSJk37pCZQco1LgoE rTl  xu3bDovyHDmgObghC6rzVOX2Tpi7kD  DOZpqxOsaS8ebYgxB XJTSxyEJuSAcpSNLqqAiZivuQXdaD0N7H3Or0awwmKE9mD I0g8CF4fPDmuuOG0ASn9fMqXVVt5tXtEqZ9yJYfNOXx3FOPjRVOZf kvSc31wCKe i KmR0AQOmToKMzq988nLqFPTi9KZB8sEU20cGFeTQFol m3FTcIru94EPD nLUn xtlLELVspYb PP3VpvRj9b DY8FGJ5nfSJl7Rkje CD4VxJpSadin3kCAwEAAaOB mTCBljAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH BAUwAwEB zAdBgNVHQ4EFgQU gM37P8oXmA972ztLfw b1eIY5nowHwYDVR0jBBgwFoAUj4YAIxRwrBy0QMRKLnD0 kVidIuYwMwYDVR0RBCwwKoIoVmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgU3Vi IEF1dGhvcml0eTANBgkqhkiG9w0BAQsFAAOCAQEAA4buJuPNJvA1kiATLw1dVU2J HPubk2Kp26Mg GwLn7Vz45Ub133JCYfF3 zXLFZZ5Yub9gWTtjScrvNfQTAbNGdQ BdnUlMmIRmfB7bfckhryR2R9byumeHATgNKZF7h8liNHI7X8tTzZGs6wPdXOLlzR TlM3m1RNK8pbSPOkfPb06w9cBRlD8OAbNtJmuypXA6tYyiiMYBhP0QLAO3i4m1ns aAjAgEjtkB1rQxW5DxoTArZ0asiIdmIcIGmsVxfDQIjFlRxAkafMs74v 5U5gbBX wsOledU0fLl8KLq8W3OXqJwhGLK65fscrP0 omPAcFgzXf L4VUADM4XhW6Xyg        END CERTIFICATE      ca chain                  BEGIN CERTIFICATE      MIIDijCCAnKgAwIBAgIUB28DoGwgGFKL7fbOu9S4FalHLn0wDQYJKoZIhvcNAQEL BQAwLzEtMCsGA1UEAxMkVmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgQXV0aG9y aXR5MB4XDTE2MDkyNzAwMDgyMVoXDTI2MDkxNjE2MDg1MVowMzExMC8GA1UEAxMo VmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgU3ViIEF1dGhvcml0eTCCASIwDQYJ KoZIhvcNAQEBBQADggEPADCCAQoCggEBAOSCiSij4wy1wiMwvZt rtU3IaO6ZTn9 LfIPuGsR5 QSJk37pCZQco1LgoE rTl  xu3bDovyHDmgObghC6rzVOX2Tpi7kD  DOZpqxOsaS8ebYgxB XJTSxyEJuSAcpSNLqqAiZivuQXdaD0N7H3Or0awwmKE9mD I0g8CF4fPDmuuOG0ASn9fMqXVVt5tXtEqZ9yJYfNOXx3FOPjRVOZf kvSc31wCKe i KmR0AQOmToKMzq988nLqFPTi9KZB8sEU20cGFeTQFol m3FTcIru94EPD nLUn xtlLELVspYb PP3VpvRj9b DY8FGJ5nfSJl7Rkje CD4VxJpSadin3kCAwEAAaOB mTCBljAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH BAUwAwEB zAdBgNVHQ4EFgQU gM37P8oXmA972ztLfw b1eIY5nowHwYDVR0jBBgwFoAUj4YAIxRwrBy0QMRKLnD0 kVidIuYwMwYDVR0RBCwwKoIoVmF1bHQgVGVzdGluZyBJbnRlcm1lZGlhdGUgU3Vi IEF1dGhvcml0eTANBgkqhkiG9w0BAQsFAAOCAQEAA4buJuPNJvA1kiATLw1dVU2J HPubk2Kp26Mg GwLn7Vz45Ub133JCYfF3 zXLFZZ5Yub9gWTtjScrvNfQTAbNGdQ BdnUlMmIRmfB7bfckhryR2R9byumeHATgNKZF7h8liNHI7X8tTzZGs6wPdXOLlzR TlM3m1RNK8pbSPOkfPb06w9cBRlD8OAbNtJmuypXA6tYyiiMYBhP0QLAO3i4m1ns aAjAgEjtkB1rQxW5DxoTArZ0asiIdmIcIGmsVxfDQIjFlRxAkafMs74v 5U5gbBX wsOledU0fLl8KLq8W3OXqJwhGLK65fscrP0 omPAcFgzXf L4VUADM4XhW6Xyg        END CERTIFICATE       private key              BEGIN RSA PRIVATE KEY      MIIEpgIBAAKCAQEAyQGAdOCFXZkgv04pmgOgW15b4AU2Ry cAVE5juIh4Xpy9Hgx F1XthXe2Ku S4gSZnAveoSm6oea8EvCsDfRJWSOdv5kjAviL6DZWBwH 7IcH7I61 cd6u 20xYJc sBAp9boMrMcp5jL4EA 6ZYkZMU0O0TIeEJYe WBt0fQR8vWXXZJW adGjWorbbNLrnx5zdVBEf8MQQmXVk1Lt Cgy SOshOwa9LJSihz3RLBpRXDJG2Yb 47JWewxrzve EtKrTnSomsCWW6TT4NH6BmdwMXrA1JZB5poM1DXrP7I5Jw2ExxH3 lzOlGqdI l78oQsanXmoW 1bYm4NM SNCLrCWwIDAQABAoIBAQCCbHMJY1Wl8eIJ v5HG2WuHXaaHqVoavo2fXTDXwWryfx1v zz Q0YnQBH3shPAi OQCTOfpw uVWTb dUZul3 wUyfcVmUdXGCLgBY53dWna8Z8e zHwhISsqtDXV TpelUBDCNO324XIIR Cg0TLO4nyzQ ESLo6D Y2DTp8lBjMEkmKTd8CLXR2ycEoVykN98qPZm8keiLGO91 I8K7aRd8uOyQ6HUfJRlzFHSuwaLReErxGTEPI4t wVqh2nP2gGBsn3apiJ0ul6Jz NlYO5PqiwpeDk4ibhQBpicnm1jnEcynH WtGuKgMNB0M4SBRBsEguO7WoKx3o qZ iVIaPWDhAoGBAO05UBvyJpAcz ZNQlaF0EAOhoxNQ3h6 6ZYUE52PgZ DHftyJPI Y JJNclY91wn91Yk3ROrDi8gqhzA 2Lelxo1kuZDu m bpzhVUdJia7tZDNzRIhI 24eP2GdochooOZ0qjvrik4kuX43amBhQ4RHsBjmX5CnUlL5ZULs8v2xnAoGBANjq VLAwiIIqJZEC6BuBvVYKaRWkBCAXvQ3j OqxHRYu3P68PZ58Q7HrhrCuyQHTph2v fzfmEMPbSCrFIrrMRmjUG8wopL7GjZjFl8HOBHFwzFiz CT5DEC IJIRkp4HM8F  PAzjB2wCdRdSjLTD5ph0 xQIg5xfln7D wqU0QHtAoGBAKkLF0 ivaIiNftw0J3x WxXag yErlizYpIGCqvuzII6lLr9YdoViT eJYrmb9Zm0HS9biCu2zuwDijRSBIL RieyF40opUaKoi3 0JMtDwTtO2MCd8qaCH3QfkgqAG0tTuj1Q8 6F2JA myKYamq MMhhpYny9 7rAlemM8ZJIqtvAoGBAKOI3zpKDNCdd98A4v7B7H2usZUIJ7gOTZDo XqiNyRENWb2PK6GNq e6SrxvuclvyKA zFnXULJoYtsj7tAH69lieGaOCc5uoRgZ eBU7 euMj McE6vEO3GgJawaJYCQi3uJMjvA bp7i81 hehOfU5ZfmmbFaZSBoMh u U5Vu3tAoGBANnBIbHfD3E7rqnqdpH1oRRHLA1VdghzEKgyUTPHNDzPJG87RY3c rRqeXepblud3qFjD60xS9BzcBijOvZ4 KHk6VIMpkyqoeNVFCJbBVCw JGMp88 v e9t 2iwryh5 rnq pg6anmgwHldptJc1XEFZA2UUQ89RP7kOGQF6IkIS      END RSA PRIVATE KEY      private key type    rsa serial number       3e 20 32 c6 af a7 20 4e b1 95 67 fb 86 bc cb 90 f4 31 b6 f3      Vault has now generated a new set of credentials using the  example dot com  role configuration  Here we see the dynamically generated private key and certificate  The issuing CA certificate and CA trust chain are returned as well  The CA Chain returns all the intermediate authorities in the trust chain  The root authority is not included since that will usually be trusted by the underlying OS      Tutorial  Refer to the  Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine  guide for a step by step tutorial   Have a look at the  PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki  for more about how to use externally managed keys with PKI      API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details


vault page title Certificate Issuance External Policy CIEPS PKI Secrets Engines Vault PKI Secrets Engine when communicating with the Certificate Issuance PKI secrets engine Certificate Issuance External Policy Service CIEPS EnterpriseAlert inline true An overview of the Certificate Issuance External Policy CIEPS protocol layout docs This document covers high level architecture and service APIs used by the

Answer:
---
layout: docs
page_title: Certificate Issuance External Policy (CIEPS) | PKI - Secrets Engines
description: An overview of the Certificate Issuance External Policy (CIEPS) protocol
---

# PKI secrets engine - Certificate Issuance External Policy Service (CIEPS) <EnterpriseAlert inline="true" />

This document covers high-level architecture and service APIs used by the
Vault PKI Secrets Engine when communicating with the Certificate Issuance
External Policy Service (CIEPS) <EnterpriseAlert inline="true" />.

## What is Certificate Issuance External Policy Service (CIEPS)?

Hashicorp Vault's PKI Secrets Engine has a mechanism for issuing leaf
certificates with arbitrary structure: [`/pki/sign-verbatim`](/vault/api-docs/secret/pki#sign-verbatim).
This requires an organization to run an application/user-accessible service
for authenticating, authorizing, and validating certificate issuance requests
(potentially handling key pair generation as well), before asking PKI to sign
the resulting CSR and leaf certificate with its own highly-privileged Vault
token. If any attribute is missing from the original requester's CSR, the
original service must reject the request as `sign-verbatim` does not give the
controlling service the ability to modify the request.

The Certificate Issuance External Policy Service (CIEPS) <EnterpriseAlert inline="true" />
protocol solves this by placing the validation and certificate templating
gated behind the PKI, solving:

 1. **Auditing**, so the original requester is still identified and both the
    original request and subsequent response are tracked.
 2. **Central access**, so applications only need to use a new URL for
    requesting certificates.
 3. **Certificate modification**, so customization of the requester's
    submission can be exposed to this external service.
 4. **External validation**, when compared to the Role-based system, as the
    CIEPS implementation can reach out to customer-defined external systems
    for validation.

Either of these two mechanisms allow an organization to leverage the Vault
PKI Secrets Engine to build their own flexible issuance control architecture,
leveraging Vault as a PKI-as-a-Service platform. However, CIEPS grants far
greater control to the organization than the `sign-verbatim` approach.

### Custom policy with `sign-verbatim`

With `sign-verbatim`, the policy validation service must sit in front of
Vault, processing requests from the user (which cannot use Vault
authentication and needs to authenticate themselves separately to this
service). This RA service then handles its own authentication to Vault,
which provides the signing capabilities via the PKI plugin.

When the application retains control over its own key material by providing
a CSR, the policy service cannot modify the requested CSR and thus cannot
modify the resulting certificate. It can only approve or deny requests
without allowing operators to hide implementation details from calling
applications. This is because PKI's `sign-verbatim` endpoint lacks the
ability for the Vault API caller (in this case, the fronting policy service)
to modify the certificate independent of the provided CSR.

If, however, the policy service can control key material (and this is an
acceptable risk to the organization), the policy service could modify requests
on behalf of the calling application. However, this still requires the
external application to know how to authenticate to this external policy
service.

Additionally, to ensure compatibility with Vault, this policy service (and its
developers) would need to add support for the ACME protocol. For any new
protocols Vault supports in the future, this service would also need to
implement support to retain compatibility.

### Custom policy with Certificate Issuance External Policy Service (CIEPS)

With CIEPS, users still authenticate to Vault and use the normal request
workflow to sign and issue certificates, including via ACME. However,
Vault's PKI Engine reaches out to the configured CIEPS implementation to
validate and template the requested certificate, transparently from the
calling application.

Notably, the application can opt to either retain full control over its key
material or delegate key creation to the trusted Vault service, with no impact
on the functionality CIEPS can provide. The CIEPS service can be scoped to
respond to requests from either a single PKI mount or multiple, getting
information about the requesting user and the Vault PKI instance from the
CIEPS messages.

Because the CIEPS service only needs knowledge of validating requests and
templating the final certificate structure, its developers need only be
concerned with the business policy logic and not broader PKI concerns (such
as generating key material or re-implementing support for other issuance
protocols).

## Certificate Issuance External Policy Service (CIEPS) webhook format

The CIEPS protocol is a REST-based, optionally mTLS protected webhook. The
external service configuration specifies the single URL that Vault will POST
the formatted CIEPS request to. When the CIEPS service is unavailable (either
due to misconfiguration or outage), Vault will reject the request and it is
up to the client to retry the request at a later time.

For convenience, Go versions of these structs are available [from the Vault
SDK](https://github.com/hashicorp/vault/blob/main/sdk/helper/certutil/cieps.go).

### Vault to CIEPS request format

This document outlines CIEPS request/response version 1.

Using the `application/json` content type, Vault will post the following
request body as a JSON object:

 - `request_version` `(int: 1)` - The version of the CIEPS request sent by
   Vault; a compatible response format is expected.

 - `request_uuid` `(string)` - A random UUID which serves to identify this
   request. This value must be sent in the response.

 - `synchronous` `(bool: true)` - A boolean indicating whether the request is
   synchronous or not. Presently set to true; no asynchronous response is
   understood.

 - `user_request_key_values` `(map[string]interface{})` - The unvalidated
   request parameters sent by the user. It is up to the CIEPS service to
   validate these prior to using them. The following fields may be present,
   including any other fields submitted by the user:

   - `csr` `(string)` - A PEM format CSR submitted either by the client (
     in the case of `/sign` or ACME requests) or on the client's behalf
     (in the case of `/issue` requests, where key material is generated
     by Vault).

 - `identity_request_key_values` `(map[string]interface{})` - Values related
   to the user's identity. When the request type is ACME, this value is not
   populated. These are:

   - `entity_id` `(string)` - The entity identifier from the request after
     authentication.

   - `entity` `(map[string]interface{})` - The entire resolved `logical.Entity`
     of the user after authentication; subject to change by the
     `entity_jmsepath` parameter in the configuration.

   - `groups` `([]map[string]interface{})` - The set of resolved
     `logical.Groups` of the user after authentication; subject to change by
     the `group_jmsepath` parameter in the configuration.

   ~> **Note**: in the event that the direct token backend or a root token is
      used, entity information may not exist. In either case,
      `identity_request_key_values` will be omitted.

 - `acme_request_key_values` `(map[string]interface{})` - Values related to
   ACME authorizations challenges attached to the finished order. Only present
   when the request type is ACME. These are:

   - `authorizations` `(map[string]interface{})` - Authorizations and
     challenges solved by the client to move this order to the finalization
     state.

   - `account` `(map[string]interface{})` - Information related to the ACME
     account issuing the request. These are:

     - `id` `(string)` - The UUID of the ACME account.

     - `directory` `(string)` - The path to the ACME directory requested by
       this account.

     - `contact` `([]string)` - Unverified contact information submitted by
       the requesting ACME account on creation.

     - `created_date` `(string: RFC 3999 format)` - Timestamp when the account
       was created.

     - `eab` `(map[string]interface{}, optional)` - When present, the details
       of the EAB used to authorize this account via Vault authentication. If
       not present, this ACME account was created without EAB bindings.

       - `key_id` `(string)` - Identifier of the EAB binding used by this
         account.

       - `key_type` `(string)` - Key type of the EAB binding used by this
         account.

       - `created_date` `(string: RFC 3999 format)` - Timestamp when the
         account was created.

 - `vault_request_values` `(map[string]interface{})` - Request value validated
   or created by Vault. These have higher trust than the unvalidated
   `user_request_key_values`. These are:

   - `policy_name` `(string: "")` - The optional policy name specified by the
     requester. When the issuance mode is not ACME (or if it was ACME and EAB
     was enforced), this has been validated by Vault's ACL system.

   - `mount` `(string)` - The request's mount path as known by the PKI plugin.

   - `namespace` `(string)` - The request's namespace the mount path exists
     within as known by the PKI plugin.

   - `vault_is_performance_standby` `(bool)` - Asserted when this requesting
     node is a standby node. When the service indicates storage is required in
     its response, Vault will forward the user's HTTP request up to an active
     node, requiring it to re-submit the CIEPS request. In this case, if the
     service knows it must always store certificates and sees a request from
     a standby node, it can skip policy and template evaluation or cache the
     results for a second pass.

   - `vault_is_performance_secondary` `(bool)` - Asserted when this requesting
      node is from a performance secondary versus the primary cluster.

   - `issuance_mode` `(string: "sign", "issue", "ica", or "acme")` - The type
     of the request: whether a REST call to `/external-policy/sign(/:policy)`,
     to `/external-policy/issue(/:policy)`, `/external-policy/sign-intermediate(/:policy)`,
     or an ACME request, respectively.

   - `vault_generated_private_key` `(bool)` - Whether or not Vault generated
     the key material behind this request. Set to true when
     `issuance_mode="issue"` only presently.

   - `requested_issuer_name` `(string)` - Name of the user's requested issuer;
     can be changed by modifying the response `issuer_ref` value.

   - `requested_issuer_id` `(string)` - UUID of the user's requested issuer;
     can be changed by modifying the response `issuer_ref` value.

   - `requested_issuer_cert` `(string)` - PEM format certificate of the user's
     requested issuer; can be changed by modifying the response `issuer_ref`
     value.

   - `requested_issuance_config` `(map[string]interface{})` - Configuration
     used for leaf certificate issuance. These are:

     - `aia_values` `(map[string]interface{})` - AIA values (CA, CRL, and
       OCSP) for the suggested issuer. These may differ from the actual values
       used for issuance of this request if `issuer_ref` is set on the response.

     - `leaf_not_after_behavior` `(string: "err", "truncate", or "permit")` - leaf
       validity period behavior for the suggested issuer.

     - `mount_default_ttl` `(string)` - Suggested default TTL set on mount tuning.

     - `mount_max_ttl` `(string)` - Suggested maximum TTL set on the mount tuning.

### CIEPS to Vault response format

The CIEPS engine must reply to this POST response with a `200 OK` status,
regardless of whether a certificate should be issued or not. Redirects will
not be followed by Vault; any proxy or load balancing functionality should be
strictly transparent to the caller. Any verbatim message returned by a non-200
status code will not be returned, either in Vault server logs or to the user.

In the response to the above request, only one of the `certificate` or `error`
fields should be specified. In the event both `certificate` and `error` are
present, the `error` will be appended to the returned `warnings` and the
`certificate` will be issued.

Using the `application/json` content type, the server should reply with the
following JSON object:

 - `request_uuid` `(string)` - The random UUID which the server used to
   identify this request.

 - `error` `(string, optional)` - The error message to be returned to the
   user about why their request failed. Only one of the `error` or
   `certificate` response parameters should be specified.

 - `warnings` `([]string, optional)` - Optional warnings to be returned to the user
   about minor issues with their request.

 - `certificate` `(string, optional)` - A PEM format certificate to be signed
   by the Vault service. Only one of the `error` or `certificate` response
   parameters should be specified.

 - `issuer_ref` `(string)` - The issuer reference to use to sign this request.
   If the user's issuer choice (in `requested_issuer_id`) is OK, this must
   be set in this field.

 - `store_certificate` `(bool: false)` - Whether or not to store the signed
   certificate.

 - `generate_lease` `(bool: false)` - Whether or not Vault should generate an
   associated lease for the certificate. Note that to generate a lease,
   `store_certificate` also needs to be set to `true`, otherwise no lease
   will be generated.

The certificate's signature will be ignored and replaced by a signature created
by the specified issuer. If a signature algorithm compatible with this issuer
is specified on the certificate, it will be preserved; otherwise, the default
signature algorithm for this issuer's key type will be used.

The certificate's AIA information will be replaced by the information from the
specified issuer, if present, else the global AIA URLs will be set, replacing
the AIA URIs and CRL distribution point extensions. Additionally, the
Authority Key Identifier extension will be replaced by the issuer's Subject
Key Identifier extension value as mandated by RFC 5280.

## Tutorial

Refer to the following tutorials for PKI secrets engine usage examples:

- [Build Your Own Certificate Authority (CA)](/vault/tutorials/secrets-management/pki-engine)
- [Build Certificate Authority (CA) in Vault with an offline Root](/vault/tutorials/secrets-management/pki-engine-external-ca)
- [Enable ACME with PKI secrets engine](/vault/tutorials/secrets-management/pki-acme-caddy)
- [PKI Secrets Engine with Managed Keys](/vault/tutorials/enterprise/managed-key-pki)
- [PKI Unified CRL and OCSP With Cross Cluster
  Revocation](/vault/tutorials/secrets-management/pki-unified-crl-ocsp-cross-cluster)
- [Configure Vault as a Certificate Manager in Kubernetes with
  Helm](/vault/tutorials/kubernetes/kubernetes-cert-manager)
- [Generate mTLS Certificates for Nomad using
  Vault](/vault/tutorials/secrets-management/vault-pki-nomad)

## API

The PKI secrets engine has a full HTTP API. Please see the
[PKI secrets engine API](/vault/api-docs/secret/pki) for more
details.

layout  docs page title  Certificate Issuance External Policy  CIEPS    PKI   Secrets Engines description  An overview of the Certificate Issuance External Policy  CIEPS  protocol        PKI secrets engine   Certificate Issuance External Policy Service  CIEPS   EnterpriseAlert inline  true      This document covers high level architecture and service APIs used by the Vault PKI Secrets Engine when communicating with the Certificate Issuance External Policy Service  CIEPS   EnterpriseAlert inline  true          What is Certificate Issuance External Policy Service  CIEPS    Hashicorp Vault s PKI Secrets Engine has a mechanism for issuing leaf certificates with arbitrary structure     pki sign verbatim    vault api docs secret pki sign verbatim   This requires an organization to run an application user accessible service for authenticating  authorizing  and validating certificate issuance requests  potentially handling key pair generation as well   before asking PKI to sign the resulting CSR and leaf certificate with its own highly privileged Vault token  If any attribute is missing from the original requester s CSR  the original service must reject the request as  sign verbatim  does not give the controlling service the ability to modify the request   The Certificate Issuance External Policy Service  CIEPS   EnterpriseAlert inline  true     protocol solves this by placing the validation and certificate templating gated behind the PKI  solving    1    Auditing    so the original requester is still identified and both the     original request and subsequent response are tracked   2    Central access    so applications only need to use a new URL for     requesting certificates   3    Certificate modification    so customization of the requester s     submission can be exposed to this external service   4    External validation    when compared to the Role based system  as the     CIEPS implementation can reach out to customer defined external systems     for validation   Either of these two mechanisms allow an organization to leverage the Vault PKI Secrets Engine to build their own flexible issuance control architecture  leveraging Vault as a PKI as a Service platform  However  CIEPS grants far greater control to the organization than the  sign verbatim  approach       Custom policy with  sign verbatim   With  sign verbatim   the policy validation service must sit in front of Vault  processing requests from the user  which cannot use Vault authentication and needs to authenticate themselves separately to this service   This RA service then handles its own authentication to Vault  which provides the signing capabilities via the PKI plugin   When the application retains control over its own key material by providing a CSR  the policy service cannot modify the requested CSR and thus cannot modify the resulting certificate  It can only approve or deny requests without allowing operators to hide implementation details from calling applications  This is because PKI s  sign verbatim  endpoint lacks the ability for the Vault API caller  in this case  the fronting policy service  to modify the certificate independent of the provided CSR   If  however  the policy service can control key material  and this is an acceptable risk to the organization   the policy service could modify requests on behalf of the calling application  However  this still requires the external application to know how to authenticate to this external policy service   Additionally  to ensure compatibility with Vault  this policy service  and its developers  would need to add support for the ACME protocol  For any new protocols Vault supports in the future  this service would also need to implement support to retain compatibility       Custom policy with Certificate Issuance External Policy Service  CIEPS   With CIEPS  users still authenticate to Vault and use the normal request workflow to sign and issue certificates  including via ACME  However  Vault s PKI Engine reaches out to the configured CIEPS implementation to validate and template the requested certificate  transparently from the calling application   Notably  the application can opt to either retain full control over its key material or delegate key creation to the trusted Vault service  with no impact on the functionality CIEPS can provide  The CIEPS service can be scoped to respond to requests from either a single PKI mount or multiple  getting information about the requesting user and the Vault PKI instance from the CIEPS messages   Because the CIEPS service only needs knowledge of validating requests and templating the final certificate structure  its developers need only be concerned with the business policy logic and not broader PKI concerns  such as generating key material or re implementing support for other issuance protocols       Certificate Issuance External Policy Service  CIEPS  webhook format  The CIEPS protocol is a REST based  optionally mTLS protected webhook  The external service configuration specifies the single URL that Vault will POST the formatted CIEPS request to  When the CIEPS service is unavailable  either due to misconfiguration or outage   Vault will reject the request and it is up to the client to retry the request at a later time   For convenience  Go versions of these structs are available  from the Vault SDK  https   github com hashicorp vault blob main sdk helper certutil cieps go        Vault to CIEPS request format  This document outlines CIEPS request response version 1   Using the  application json  content type  Vault will post the following request body as a JSON object       request version    int  1     The version of the CIEPS request sent by    Vault  a compatible response format is expected       request uuid    string     A random UUID which serves to identify this    request  This value must be sent in the response       synchronous    bool  true     A boolean indicating whether the request is    synchronous or not  Presently set to true  no asynchronous response is    understood       user request key values    map string interface       The unvalidated    request parameters sent by the user  It is up to the CIEPS service to    validate these prior to using them  The following fields may be present     including any other fields submitted by the user         csr    string     A PEM format CSR submitted either by the client        in the case of   sign  or ACME requests  or on the client s behalf       in the case of   issue  requests  where key material is generated      by Vault        identity request key values    map string interface       Values related    to the user s identity  When the request type is ACME  this value is not    populated  These are         entity id    string     The entity identifier from the request after      authentication         entity    map string interface       The entire resolved  logical Entity       of the user after authentication  subject to change by the       entity jmsepath  parameter in the configuration         groups      map string interface       The set of resolved       logical Groups  of the user after authentication  subject to change by      the  group jmsepath  parameter in the configuration           Note    in the event that the direct token backend or a root token is       used  entity information may not exist  In either case         identity request key values  will be omitted       acme request key values    map string interface       Values related to    ACME authorizations challenges attached to the finished order  Only present    when the request type is ACME  These are         authorizations    map string interface       Authorizations and      challenges solved by the client to move this order to the finalization      state         account    map string interface       Information related to the ACME      account issuing the request  These are           id    string     The UUID of the ACME account           directory    string     The path to the ACME directory requested by        this account           contact      string     Unverified contact information submitted by        the requesting ACME account on creation           created date    string  RFC 3999 format     Timestamp when the account        was created           eab    map string interface    optional     When present  the details        of the EAB used to authorize this account via Vault authentication  If        not present  this ACME account was created without EAB bindings             key id    string     Identifier of the EAB binding used by this          account             key type    string     Key type of the EAB binding used by this          account             created date    string  RFC 3999 format     Timestamp when the          account was created       vault request values    map string interface       Request value validated    or created by Vault  These have higher trust than the unvalidated     user request key values   These are         policy name    string         The optional policy name specified by the      requester  When the issuance mode is not ACME  or if it was ACME and EAB      was enforced   this has been validated by Vault s ACL system         mount    string     The request s mount path as known by the PKI plugin         namespace    string     The request s namespace the mount path exists      within as known by the PKI plugin         vault is performance standby    bool     Asserted when this requesting      node is a standby node  When the service indicates storage is required in      its response  Vault will forward the user s HTTP request up to an active      node  requiring it to re submit the CIEPS request  In this case  if the      service knows it must always store certificates and sees a request from      a standby node  it can skip policy and template evaluation or cache the      results for a second pass         vault is performance secondary    bool     Asserted when this requesting       node is from a performance secondary versus the primary cluster         issuance mode    string   sign    issue    ica   or  acme      The type      of the request  whether a REST call to   external policy sign   policy         to   external policy issue   policy      external policy sign intermediate   policy         or an ACME request  respectively         vault generated private key    bool     Whether or not Vault generated      the key material behind this request  Set to true when       issuance mode  issue   only presently         requested issuer name    string     Name of the user s requested issuer       can be changed by modifying the response  issuer ref  value         requested issuer id    string     UUID of the user s requested issuer       can be changed by modifying the response  issuer ref  value         requested issuer cert    string     PEM format certificate of the user s      requested issuer  can be changed by modifying the response  issuer ref       value         requested issuance config    map string interface       Configuration      used for leaf certificate issuance  These are           aia values    map string interface       AIA values  CA  CRL  and        OCSP  for the suggested issuer  These may differ from the actual values        used for issuance of this request if  issuer ref  is set on the response           leaf not after behavior    string   err    truncate   or  permit      leaf        validity period behavior for the suggested issuer           mount default ttl    string     Suggested default TTL set on mount tuning           mount max ttl    string     Suggested maximum TTL set on the mount tuning       CIEPS to Vault response format  The CIEPS engine must reply to this POST response with a  200 OK  status  regardless of whether a certificate should be issued or not  Redirects will not be followed by Vault  any proxy or load balancing functionality should be strictly transparent to the caller  Any verbatim message returned by a non 200 status code will not be returned  either in Vault server logs or to the user   In the response to the above request  only one of the  certificate  or  error  fields should be specified  In the event both  certificate  and  error  are present  the  error  will be appended to the returned  warnings  and the  certificate  will be issued   Using the  application json  content type  the server should reply with the following JSON object       request uuid    string     The random UUID which the server used to    identify this request       error    string  optional     The error message to be returned to the    user about why their request failed  Only one of the  error  or     certificate  response parameters should be specified       warnings      string  optional     Optional warnings to be returned to the user    about minor issues with their request       certificate    string  optional     A PEM format certificate to be signed    by the Vault service  Only one of the  error  or  certificate  response    parameters should be specified       issuer ref    string     The issuer reference to use to sign this request     If the user s issuer choice  in  requested issuer id   is OK  this must    be set in this field       store certificate    bool  false     Whether or not to store the signed    certificate       generate lease    bool  false     Whether or not Vault should generate an    associated lease for the certificate  Note that to generate a lease      store certificate  also needs to be set to  true   otherwise no lease    will be generated   The certificate s signature will be ignored and replaced by a signature created by the specified issuer  If a signature algorithm compatible with this issuer is specified on the certificate  it will be preserved  otherwise  the default signature algorithm for this issuer s key type will be used   The certificate s AIA information will be replaced by the information from the specified issuer  if present  else the global AIA URLs will be set  replacing the AIA URIs and CRL distribution point extensions  Additionally  the Authority Key Identifier extension will be replaced by the issuer s Subject Key Identifier extension value as mandated by RFC 5280      Tutorial  Refer to the following tutorials for PKI secrets engine usage examples      Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine     Build Certificate Authority  CA  in Vault with an offline Root   vault tutorials secrets management pki engine external ca     Enable ACME with PKI secrets engine   vault tutorials secrets management pki acme caddy     PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki     PKI Unified CRL and OCSP With Cross Cluster   Revocation   vault tutorials secrets management pki unified crl ocsp cross cluster     Configure Vault as a Certificate Manager in Kubernetes with   Helm   vault tutorials kubernetes kubernetes cert manager     Generate mTLS Certificates for Nomad using   Vault   vault tutorials secrets management vault pki nomad       API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details