CertEnroll Renew

Certificate renewal in Keyfactor Command allows a certificate to be issued based on data from an existing certificate. Some configurations, such as the issuing CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. and template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received., can be made to differ between the original certificate and the renewed one. At renewal time, the new certificate can also be automatically delivered to different certificate stores managed by Keyfactor Command Agents, replacing the old certificates. This provides an easy mechanism to quickly replace expiring or compromised certificates, migrate deployed certificates from one PKI A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. to another, or replace certificates with similar certificates using more secure cryptographic algorithms. The Renew Web API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. method, along with the web console and expiration alert handlers, allows access to this renewal functionality. The structure of a renew request is given Table 680: POST /3/Renew Request Body, and the response in Table 681: POST /3/Renew Response Body.

Table 680: POST /3/Renew Request Body

Parameter Name	Parameter Value
Lookup	Description of the certificate to be renewed. See Table 65: Classic API Certificate Lookup Structure.
CertStores	Array of GUIDs listing the certificate stores where the new certificate should be delivered. This must be a subset of the CertStores containing the original certificate.
Template	Certificate template to be used for the new certificate request.
CAConfiguration	Certificate authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. for the new certificate, in the form "hostname The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername).\\logical name The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two)." (double-backslash required for JSON formatting).
Metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates.	Optional dictionary of metadata fields and values to be associated with the newly issued certificate.
CustomPassword	Password to protect the private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. of the new certificate. This field is optional and Keyfactor Command will use a randomly assigned password if this is not set.

 

Table 681: POST /3/Renew Response Body

Parameter Name	Parameter Value
Thumbprint	Thumbprint of the issued certificate.
CMSRequestId	Identifier for the certificate request in Keyfactor Command, if certificate is pending issuance.
RequestDisposition	Value returned by the CA in response to this certificate request.
DispositionMessage	Message accompanying the disposition value returned by the CA.
RenewedCertStores	List of certstores that had a certificate addition job scheduled successfully. The certstores will be listed in the format "<Store machine >-<Store path>".

Example Request

POST http://<host>/CMSApi/CertEnroll/3/Renew HTTP/1.1

{
	"Lookup": {"Type" : "CMSID", "CMSID" : 7},
	"CertStores": ["<Guid>"],
	"Template": "UserServer",
	"CAConfiguration" : "CA1.jdk.com\\jdk-CA1",
	"Metadata":{"Email-Contact":"a.b@example.com"}
}

Example Response

{
"RenewedCertStores": ["192.168.41.171-/home/pi/cherry/cherrystore"],
"Thumbprint": "46CCE7023bce5c434f4206b74473fd614df56218",
"CMSRequestId": 0,
"RequestDisposition": "Issued",
"DispositionMessage": "The certificate renewal has been completed successfully. Agent jobs to install the new certificate have been created."
}