Update Certificate Policy - Update Certificate Policy

Service:

Key Vault

API Version:

7.4

Updates the policy for a certificate.
Set specified members in the certificate policy. Leave others as null. This operation requires the certificates/update permission.

PATCH {vaultBaseUrl}/certificates/{certificate-name}/policy?api-version=7.4

URI Parameters

Name	In	Required	Type	Description
certificate-name	path	True	string	The name of the certificate in the given vault.
vaultBaseUrl	path	True	string	The vault name, for example https://myvault.vault.azure.net.
api-version	query	True	string	Client API version.

Request Body

Name	Type	Description
attributes	CertificateAttributes	The certificate attributes.
issuer	IssuerParameters	Parameters for the issuer of the X509 component of a certificate.
key_props	KeyProperties	Properties of the key backing a certificate.
lifetime_actions	LifetimeAction[]	Actions that will be performed by Key Vault over the lifetime of a certificate.
secret_props	SecretProperties	Properties of the secret backing a certificate.
x509_props	X509CertificateProperties	Properties of the X509 component of a certificate.

Responses

Name	Type	Description
200 OK	CertificatePolicy	The certificate policy
Other Status Codes	KeyVaultError	Key Vault error response describing why the operation failed.

Examples

UpdateCertificatePolicy

Sample Request

HTTP

PATCH https://myvault.vault.azure.net//certificates/updateCert01/policy?api-version=7.4

{
  "key_props": {
    "exportable": true,
    "kty": "RSA",
    "key_size": 2048,
    "reuse_key": false
  },
  "secret_props": {
    "contentType": "application/x-pkcs12"
  },
  "x509_props": {
    "subject": "CN=KeyVaultTest",
    "ekus": [],
    "key_usage": [],
    "validity_months": 297
  },
  "lifetime_actions": [
    {
      "trigger": {
        "lifetime_percentage": 80
      },
      "action": {
        "action_type": "EmailContacts"
      }
    }
  ],
  "issuer": {
    "name": "Self"
  },
  "attributes": {
    "enabled": true
  }
}

Sample Response

Status code:

200

{
  "id": "https://myvault.vault.azure.net/certificates/updateCert01/policy",
  "key_props": {
    "exportable": true,
    "kty": "RSA",
    "key_size": 2048,
    "reuse_key": false
  },
  "secret_props": {
    "contentType": "application/x-pkcs12"
  },
  "x509_props": {
    "subject": "CN=KeyVaultTest",
    "ekus": [],
    "key_usage": [],
    "validity_months": 297
  },
  "lifetime_actions": [
    {
      "trigger": {
        "lifetime_percentage": 80
      },
      "action": {
        "action_type": "EmailContacts"
      }
    }
  ],
  "issuer": {
    "name": "Self"
  },
  "attributes": {
    "enabled": true,
    "created": 1482188947,
    "updated": 1482188948
  }
}

Definitions

Name	Description
Action	The action that will be executed.
CertificateAttributes	The certificate management attributes.
CertificatePolicy	Management policy for a certificate.
CertificatePolicyAction	The type of the action.
DeletionRecoveryLevel	Reflects the deletion recovery level currently in effect for certificates in the current vault. If it contains 'Purgeable', the certificate can be permanently deleted by a privileged user; otherwise, only the system can purge the certificate, at the end of the retention interval.
Error	The key vault server error.
IssuerParameters	Parameters for the issuer of the X509 component of a certificate.
JsonWebKeyCurveName	Elliptic curve name. For valid values, see JsonWebKeyCurveName.
JsonWebKeyType	The type of key pair to be used for the certificate.
KeyProperties	Properties of the key pair backing a certificate.
KeyUsageType	Defines how the certificate's key may be used.
KeyVaultError	The key vault error exception.
LifetimeAction	Action and its trigger that will be performed by Key Vault over the lifetime of a certificate.
SecretProperties	Properties of the key backing a certificate.
SubjectAlternativeNames	The subject alternate names of a X509 object.
Trigger	A condition to be satisfied for an action to be executed.
X509CertificateProperties	Properties of the X509 component of a certificate.

Action

The action that will be executed.

Name	Type	Description
action_type	CertificatePolicyAction	The type of the action.

CertificateAttributes

The certificate management attributes.

Name	Type	Description
created	integer	Creation time in UTC.
enabled	boolean	Determines whether the object is enabled.
exp	integer	Expiry date in UTC.
nbf	integer	Not before date in UTC.
recoverableDays	integer	softDelete data retention days. Value should be >=7 and <=90 when softDelete enabled, otherwise 0.
recoveryLevel	DeletionRecoveryLevel	Reflects the deletion recovery level currently in effect for certificates in the current vault. If it contains 'Purgeable', the certificate can be permanently deleted by a privileged user; otherwise, only the system can purge the certificate, at the end of the retention interval.
updated	integer	Last updated time in UTC.

CertificatePolicy

Management policy for a certificate.

Name	Type	Description
attributes	CertificateAttributes	The certificate attributes.
id	string	The certificate id.
issuer	IssuerParameters	Parameters for the issuer of the X509 component of a certificate.
key_props	KeyProperties	Properties of the key backing a certificate.
lifetime_actions	LifetimeAction[]	Actions that will be performed by Key Vault over the lifetime of a certificate.
secret_props	SecretProperties	Properties of the secret backing a certificate.
x509_props	X509CertificateProperties	Properties of the X509 component of a certificate.

CertificatePolicyAction

The type of the action.

Name	Type	Description
AutoRenew	string
EmailContacts	string

DeletionRecoveryLevel

Reflects the deletion recovery level currently in effect for certificates in the current vault. If it contains 'Purgeable', the certificate can be permanently deleted by a privileged user; otherwise, only the system can purge the certificate, at the end of the retention interval.

Name	Type	Description
CustomizedRecoverable	string	Denotes a vault state in which deletion is recoverable without the possibility for immediate and permanent deletion (i.e. purge when 7<= SoftDeleteRetentionInDays < 90).This level guarantees the recoverability of the deleted entity during the retention interval and while the subscription is still available.
CustomizedRecoverable+ProtectedSubscription	string	Denotes a vault and subscription state in which deletion is recoverable, immediate and permanent deletion (i.e. purge) is not permitted, and in which the subscription itself cannot be permanently canceled when 7<= SoftDeleteRetentionInDays < 90. This level guarantees the recoverability of the deleted entity during the retention interval, and also reflects the fact that the subscription itself cannot be cancelled.
CustomizedRecoverable+Purgeable	string	Denotes a vault state in which deletion is recoverable, and which also permits immediate and permanent deletion (i.e. purge when 7<= SoftDeleteRetentionInDays < 90). This level guarantees the recoverability of the deleted entity during the retention interval, unless a Purge operation is requested, or the subscription is cancelled.
Purgeable	string	Denotes a vault state in which deletion is an irreversible operation, without the possibility for recovery. This level corresponds to no protection being available against a Delete operation; the data is irretrievably lost upon accepting a Delete operation at the entity level or higher (vault, resource group, subscription etc.)
Recoverable	string	Denotes a vault state in which deletion is recoverable without the possibility for immediate and permanent deletion (i.e. purge). This level guarantees the recoverability of the deleted entity during the retention interval(90 days) and while the subscription is still available. System wil permanently delete it after 90 days, if not recovered
Recoverable+ProtectedSubscription	string	Denotes a vault and subscription state in which deletion is recoverable within retention interval (90 days), immediate and permanent deletion (i.e. purge) is not permitted, and in which the subscription itself cannot be permanently canceled. System wil permanently delete it after 90 days, if not recovered
Recoverable+Purgeable	string	Denotes a vault state in which deletion is recoverable, and which also permits immediate and permanent deletion (i.e. purge). This level guarantees the recoverability of the deleted entity during the retention interval (90 days), unless a Purge operation is requested, or the subscription is cancelled. System wil permanently delete it after 90 days, if not recovered

Error

The key vault server error.

Name	Type	Description
code	string	The error code.
innererror	Error	The key vault server error.
message	string	The error message.

IssuerParameters

Parameters for the issuer of the X509 component of a certificate.

Name	Type	Description
cert_transparency	boolean	Indicates if the certificates generated under this policy should be published to certificate transparency logs.
cty	string	Certificate type as supported by the provider (optional); for example 'OV-SSL', 'EV-SSL'
name	string	Name of the referenced issuer object or reserved names; for example, 'Self' or 'Unknown'.

JsonWebKeyCurveName

Elliptic curve name. For valid values, see JsonWebKeyCurveName.

Name	Type	Description
P-256	string
P-256K	string
P-384	string
P-521	string

JsonWebKeyType

The type of key pair to be used for the certificate.

Name	Type	Description
EC	string
EC-HSM	string
RSA	string
RSA-HSM	string
oct	string
oct-HSM	string

KeyProperties

Properties of the key pair backing a certificate.

Name	Type	Description
crv	JsonWebKeyCurveName	Elliptic curve name. For valid values, see JsonWebKeyCurveName.
exportable	boolean	Indicates if the private key can be exported. Release policy must be provided when creating the first version of an exportable key.
key_size	integer	The key size in bits. For example: 2048, 3072, or 4096 for RSA.
kty	JsonWebKeyType	The type of key pair to be used for the certificate.
reuse_key	boolean	Indicates if the same key pair will be used on certificate renewal.

KeyUsageType

Defines how the certificate's key may be used.

Name	Type	Description
cRLSign	string
dataEncipherment	string
decipherOnly	string
digitalSignature	string
encipherOnly	string
keyAgreement	string
keyCertSign	string
keyEncipherment	string
nonRepudiation	string

KeyVaultError

The key vault error exception.

Name	Type	Description
error	Error	The key vault server error.

LifetimeAction

Action and its trigger that will be performed by Key Vault over the lifetime of a certificate.

Name	Type	Description
action	Action	The action that will be executed.
trigger	Trigger	The condition that will execute the action.

SecretProperties

Properties of the key backing a certificate.

Name	Type	Description
contentType	string	The media type (MIME type).

SubjectAlternativeNames

The subject alternate names of a X509 object.

Name	Type	Description
dns_names	string[]	Domain names.
emails	string[]	Email addresses.
upns	string[]	User principal names.

Trigger

A condition to be satisfied for an action to be executed.

Name	Type	Description
days_before_expiry	integer	Days before expiry to attempt renewal. Value should be between 1 and validity_in_months multiplied by 27. If validity_in_months is 36, then value should be between 1 and 972 (36 * 27).
lifetime_percentage	integer	Percentage of lifetime at which to trigger. Value should be between 1 and 99.

X509CertificateProperties

Properties of the X509 component of a certificate.

Name	Type	Description
ekus	string[]	The enhanced key usage.
key_usage	KeyUsageType[]	Defines how the certificate's key may be used.
sans	SubjectAlternativeNames	The subject alternative names.
subject	string	The subject name. Should be a valid X509 distinguished Name.
validity_months	integer	The duration that the certificate is valid in months.