POST Certificates/CheckPolicy

Returns the policy and a compliance assessment for a Certificate Signing Request (CSR).

You can also call this method to determine the status of the private key prior to enrollment. Certificates/CheckPolicy:

  • Determines whether the private key is already in use.
  • Determines whether the policy folder allows a certificate to reuse the same private key.

Requirements

  • Permissions:  The caller must have Read permission and Private Key Read permission to the Certificate object.
  • Token scope:  Certificate:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description
PolicyDN The Distinguished Name (DN) of the policy folder.
PKCS10 (Optional) The CSR to use to verify its contents with the Trust Protection Platform policy. Each new line requires a new line escape character (/n).

Returns

The response contains CSR compliance details, the Enrollable result, any errors, and policy information from the Policy DN. The response also includes information about errors or a certificate that is currently in the enrollment process. For example, this collapsed set of return values shows you basic information from the Certificates/CheckPolicy response:

Summary of Certificates/CheckPolicy return values

Certificates/CheckPolicy:

  • Returns a HTTP 200 message and the message body contains data in the Details and Policy fields.
  • Returns a HTTP 400 Bad Request for errors and the reason appears in the Error field of the message body.
  • Returns a HTTP 403 Unauthorized for requests that lack authorization from Trust Protection Platform.
Response description

Name

Description

HTTP 200

For valid requests, this call returns a HTTP 200 message and the following data in the message body:

CSR: Information about the Certificate Signing Request (CSR):

  • A Details node that shows compliance results based on the comparison between the Policy DN and corresponding CSR. If the request did not include a PKCS10 certificate, CSR return values are omitted.

    • City: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • Common Name:Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • Country:Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • EllipticCurve:Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • KeyAlgorithm: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • KeySize: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • Organization: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • OrganizationalUnit: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • PrivateKeyReused: Compliant:

      • false: No matching private key is present in Trust Protection Platform.
      • true: The Public Key Hash in the CSR corresponds to an existing certificate, which means the same private key was used to generate the CSR. Review the PrivateKeyReuseAllowed value to determine whether a CSR, certificate renewal, or certificate import will be successful.

    • State: Compliant:

      • false: The value in the CSR differs from policy except when there is no effective policy value.
      • true: The value in the CSR either matches policy or there is no effective policy value (it's null).

    • SubjAltNameDNS: Compliant:

      • false: The Value failed to comply with WhitelistedDomains or WildcardsAllowed policies.
      • true: The value is compliant for one of the following reasons. The Values from the CSR are empty and the locked policy value applies. The Values comply with WhitelistedDomains or WildcardsAllowed policies. The policies are unlocked.

    • SubjAltNameEmail: Compliant:

      • false: The Value failed to comply with WhitelistedDomains or WildcardsAllowed policies.
      • true: The value is compliant for one of the following reasons. The Values from the CSR are empty and the locked policy value applies. The Values comply with WhitelistedDomains or WildcardsAllowed policies. The policies are unlocked.

    • SubjAltNameIp: Compliant:

      • false: The Value failed to comply with WhitelistedDomains or WildcardsAllowed policies.
      • true: The value is compliant for one of the following reasons. The Values from the CSR are empty and the locked policy value applies. The Values comply with WhitelistedDomains or WildcardsAllowed policies. The policies are unlocked.

    • SubjAltNameUpn: Compliant:

      • false: The Value failed to comply with WhitelistedDomains or WildcardsAllowed policies.
      • true: The value is compliant for one of the following reasons. The Values from the CSR are empty and the locked policy value applies. The Values comply with WhitelistedDomains or WildcardsAllowed policies. The policies are unlocked.

    • SubjAltNameUri: Compliant:

      • false: The Value failed to comply with WhitelistedDomains or WildcardsAllowed policies.
      • true: The value is compliant for one of the following reasons. The Values from the CSR are empty and the locked policy value applies. The Values comply with WhitelistedDomains or WildcardsAllowed policies. The policies are unlocked.
  • Enrollable:summarizes compliance data:

    • false: The CSR is considered non-compliant or rejected for provisioning or renewal. The reasons why a CSR can be unacceptable for certificate enrollment include:

      • One or more CSR settings failed to match locked Policy values from the Policy DN.

      • The CSR includes a SAN type that is not allowed by policy.

      • The CSR specifies a CN or DNS SAN that uses a domain that is not whitelisted and the Domain Whitelisting applies by policy.

      • The ManagementType is locked to Unassigned or Monitoring.

      • The PrivateKeyReuseAllowed is false and PrivateKeyReused is true.

    • true: The CSR complies with all policy including exact matches for locked Subject DN settings. The CSR is valid for provisioning or renewal.

 

Error: Null unless there is an error. If an error occurs, the CsrDetails and Policy values are null and one of the corresponding error messages accompany the HTTP 400 Bad Request:

  • Invalid PKCS#10 data.
  • Invalid PolicyDN format. The Policy DN contained null or white spaces for [ PolicyDN].
  • Parse failure due to an invalid PKCS#10 format.
  • Parse public key failure due to an invalid PKCS#10 format.
  • PKCS#10 data is not in the Base64 format.
  • PolicyDN error. PolicyDN: [ PolicyDN] does not exist or you do not have sufficient permissions to the object.

  • Private key check reuse error. Secret Store lookup error: [error].

  • Public key format is unsupported. Supported public key formats are RSA and ECC only.
  • Reading policy details failure.

 

Policy: The settings from the Policy DN. You can compare these settings to the CSRDetails:

  • CertificateAuthority:Locked:

    • false: The Value is optional.
    • true: The Certificate Authority (CA) Value is mandatory,

  • CsrGeneration: Locked:

    • false: The Value is optional.
    • true: The Value for CSR generation is mandatory. If the policy is locked with the Value: ServiceGenerated, automatically set Enrollable to false.

  • KeyGeneration: Locked:

    • false: The Value is optional.
    • true: The Value for key generation is mandatory. If the policy is locked with the Value=Remote, automatically set Enrollable to false.

  • KeyPair: Locked:

    • false: The Value is optional.
    • true: The Value that describes the method of public and private key pairs is mandatory.

  • KeyAlgorithm: Locked:

    • false: The Value is optional.
    • true: The Value that describes the public algorithm is mandatory.

  • KeySize: Locked:

    • false: The Value is optional.
    • true: The Value for the public key size is mandatory.

  • ManagementType: Locked:

    • false: The Value is optional.
    • true: The Value that describes the certificate purpose is mandatory. If the policy is locked with the Value=Unassigned or Monitoring, automatically set Enrollable to false.

  • PrivateKeyReuseAllowed:

    • false: A PolicyDN setting blocks the reuse of all private keys.
    • true: Predicts whether the PolicyDN will allow you to import a CSR or certificate that used the same private key as an existing certificate.

  • SubjAltNameDnsAllowed:

    • false: The SAN DNS is optional.
    • true: The capability for the CSR to provide a Domain Name System (DNS) as the Subject Alternate Name (SAN) is mandatory.

  • SubjAltNameEmailAllowed:

    • false: The SAN Email address is optional.
    • true: The capability for the CSR to provide an email address as the SAN is mandatory.

  • SubjAltNameIpAllowed:

    • false: The SAN IP address is optional.
    • true: The capability for the CSR to provide an IP address as the SAN is mandatory.

  • SubjAltNameUpnAllowed:

    • false: The SAN UPN address is optional.
    • true: The capability for the CSR to provide a User Principal Name (UPN) as the Subject Alternate Name (SAN) is mandatory.

  • SubjAltNameUriAllowed:

    • false: The SAN URI address is optional.
    • true: The capability for the CSR to provide a Universal Resource ID (URI) as the Subject Alternate Name (SAN) is mandatory.

  • Subject:

    • false: The Location values are optional.
    • true: Each Location (L) Value for City, Country, Organization, OrganizationalUnit, and State is mandatory.

  • UniqueSubjectEnforced:

    • false: The Subject is optional.
    • true: The Subject is mandatory.

HTTP 400

For invalid requests, this call returns a HTTP 400 BadRequest and the following data in the message body:

  • Error: The reason for the error.

  • Policy: The policy or null.

Example: Determine CSR compliance with a Trust Protection Platform policy

Request

POST https://tpp.venafi.example/vedsdk/Certificates/CheckPolicy
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "PolicyDN":"\\VED\\Policy\\Import",
   "PKCS10":"-----BEGIN CERTIFICATE REQUEST-----\nMIIFPjC...  -----END CERTIFICATE REQUEST-----\n"
}

Response

HTTP/1.1 200 OK
{
   "CSR":{
      "Details":{
         "City":{
            "Compliant":true,
            "Value":"El Granada"
         },
         "CommonName":{
            "Compliant":true,
            "Value":"silvana_a37fe.venafi.test"
         },
         "Country":{
            "Compliant":true,
            "Value":"US"
         },
         "KeyAlgorithm":{
            "Compliant":true,
            "Value":"RSA"
         },
         "KeySize":{
            "Compliant":true,
            "Value":2048
         },
         "Organization":{
            "Compliant":true,
            "Value":"Venafi"
         },
         "OrganizationalUnit":{
            "Compliant":true,
            "Values":[
               "Auto"
            ]
         },
         "PrivateKeyReused":{
            "Compliant":true,
            "Value":true
         },
         "State":{
            "Compliant":true,
            "Value":"CA"
         },
         "SubjAltNameDns":{
            "Compliant":true,
            "Values":[

            ]
         },
         "SubjAltNameEmail":{
            "Compliant":true,
            "Values":[

            ]
         },
         "SubjAltNameIp":{
            "Compliant":true,
            "Values":[

            ]
         },
         "SubjAltNameUpn":{
            "Compliant":true,
            "Values":[

            ]
         },
         "SubjAltNameUri":{
            "Compliant":true,
            "Values":[

            ]
         }
      },
      "Enrollable":false
   },
   "Error":null,
   "Policy":{
      "CertificateAuthority":{
         "Locked":false,
         "Value":null
      },
      "CsrGeneration":{
         "Locked":false,
         "Value":"ServiceGenerated"
      },
      "KeyGeneration":{
         "Locked":false,
         "Value":"Central"
      },
      "KeyPair":{
         "KeyAlgorithm":{
            "Locked":false,
            "Value":"RSA"
         },
         "KeySize":{
            "Locked":false,
            "Value":2048
         }
      },
      "ManagementType":{
         "Locked":false,
         "Value":"Monitoring"
      },
      "PrivateKeyReuseAllowed":true,
      "SubjAltNameDnsAllowed":true,
      "SubjAltNameEmailAllowed":true,
      "SubjAltNameIpAllowed":true,
      "SubjAltNameUpnAllowed":true,
      "SubjAltNameUriAllowed":true,
      "Subject":{
         "City":{
            "Locked":false,
            "Value":"SLC"
         },
         "Country":{
            "Locked":false,
            "Value":"US"
         },
         "Organization":{
            "Locked":false,
            "Value":"Venafi"
         },
         "OrganizationalUnit":{
            "Locked":false,
            "Values":[
               "Venafi Test"
            ]
         },
         "State":{
            "Locked":false,
            "Value":"Utah"
         }
      },
      "UniqueSubjectEnforced":false,
      "WhitelistedDomains":[

      ],
      "WildcardsAllowed":true
   }
}