Certificates Search and Count

The Search method will return the set of certificates known to Keyfactor Command that satisfy certain criteria. The criteria that can be searched on and the syntax by which queries are formed is the same as in the Advanced Certificate Search within the Keyfactor Command Management Portal. This is largely consistent with PowerShell comparison notation, but Keyfactor does not publish a complete specification of this query language. Instead, developers are encouraged to examine the query strings formed in the Keyfactor Command Management Portal and model their 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. queries based on this. The response will contain a JSON body with an array whose entries each represent a single matching certificate. The Count method expects the same parameters as the Search query but simply returns a count of the records that would be returned if the same parameters were provided to the Search endpoint An endpoint is a URL that enables the API to gain access to resources on a server.. For Count, the sorting parameters will have no effect.

Table 693: POST /3/Search and /3/Count Request Body

Parameter Name	Parameter Value
IncludeRevoked	Boolean denoting if revoked certificates should be included in the search results.
IncludeExpired	Boolean denoting if expired certificates should be included in the search results.
Query	Search query criteria, as defined above.
SortField	Name of the result field by which the results should be sorted. The field must be one returned within the results. This parameter A parameter or argument is a value that is passed into a function in an application. is optional and the Keyfactor Command certificate id will be used if not provided. The available fields are the same as in Table 694: POST /3/Search Response Body.
SortAscending	Boolean value denoting if the SortField should be sorted in ascending order. This parameter is optional and ascending will be used if not provided.
SkipCount	Number of records that should be skipped in the results, starting from the beginning of the records (for pagination). This field is optional and no records will be skipped if not provided.
ReturnLimit	Numeric value of the limit of records to be returned. This field is optional and 5000 will be used if not provided.

 

Table 694: POST /3/Search Response Body

Parameter Name	Parameter Value
Id	Certificate ID assigned by Keyfactor Command, which can be used for service chaining to other many other 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. requests by providing this value as a CMSID in the Lookup section of the request. See Table 68: Classic API Certificate Lookup Structure.
IssuedCN	Issued Common Name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com).
IssuedDN	Issued Distinguished Name
NotBefore	Beginning date for certificate validity
NotAfter	Ending (expiration) date for certificate validity
IssuerDN	Issuer Distinguished Name
PrincipalName	Subject Principal Name
RequesterName	Requester Name
TemplateName	Certificate Template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. Name
CertState	Certificate State. Will take one of the following values: Value Definition 0 Unknown 1 Active 2 Revoked 3 Denied 4 Failed 5 Pending 6 CertificateAuthority 7 ParentCertificateAuthority
KeySize	Bit-length of the public/private keys.
KeyType	Cryptographic algorithm used for the public/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.. Will take one of the following values: Value Definition 0 Unknown 1 RSA 2 DSA 3 ECC Elliptical curve cryptography (ECC) is a public key encryption technique based on elliptic curve theory that can be used to create faster, smaller, and more efficient cryptographic keys. ECC generates keys through the properties of the elliptic curve equation instead of the traditional method of generation as the product of very large prime numbers. 4 DH
SerialNumber	The hexadecimal serial number of the certificate.
Thumbprint	The hexadecimal thumbprint of the certificate.

Example Request

POST http://<host>/CMSApi/Certificates/3/Search HTTP/1.1

{
	"includeRevoked": true, 
	"includeExpired": true, 
	"query": "(ExpirationDate -eq \"2018-05-10\")"
}

Example Response

[{
	"Id":<certificate-id>,
	"IssuedCN": "<cn>",
	"IssuedDN": "<dn>",
	"NotBefore": "2017-05-10T18:59:57",
	"NotAfter": "2018-05-10T18:59:57",
	"IssuerDN": "<issuer-dn>",
	"PrincipalName": null,
	"RequesterName": null,
	"TemplateName": null,
	"CertState": 0,
	"KeySize": 4096,
	"KeyType": 1
}]