GET Certificate Stores

The GET /CertificateStores method is used to return a list of all certificate stores defined in Keyfactor Command. The results include both approved certificates stores and certificates stores found on discovery but not yet approved. This method allows URL parameters to specify paging and the level of information detail. This method returns HTTP 200 OK on a success with details about the certificate store(s).

Tip:  The following permissions (see Security Overview) are required to use this feature:

CertificateStoreManagement: Read

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions in the Keyfactor Command Reference Guide for more information about global vs container permissions.

Table 252: GET Certificate Stores Input Parameters

Name In Description
queryString Query

A string containing a query to limit the results (e.g. field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to the Keyfactor Command Reference Guide: Using the Certificate Store Search Feature. The query fields supported for this endpoint are:

  • AddSupported (True, False)

  • Container (ContainerName)

  • AgentAvailable (True, False)

  • ContainerId

  • AgentId

  • HasInventoryScheduled (True, False)

  • Approved (True, False)

  • PrivateKeyAllowed (0-Forbidden, 1-Optional, 2-Required)

  • Category (0-Javakeystore,2-PEMFile, 3-F5SSLProfiles,4-IISRoots, 5-NetScaler, 6-IISPersonal, 7-F5WebServer, 8-IISRevoked, 9-F5WebServerREST, 10-F5SSLProfilesREST, 11-F5CABundlesREST, 100-AmazonWebServices, 101-FileTransferProtocol)

  • RemoveSupported (True, False)

  • CertificateId

  • StorePath

  • ClientMachine

 
Tip:  Use the following query to limit the results to only active certificate stores and not include discovery results:
approved -eq true
pageReturned Query An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
returnLimit Query An integer that specifies how many results to return per page. The default is 50.
sortField Query A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is ClientMachine.
sortAscending Query An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 253: GET Certificate Stores Response Data

Name Description
Id A string indicating the GUID of the certificate store within Keyfactor Command. This ID is automatically set by Keyfactor Command.
ContainerId An integer indicating the ID of the certificate store's associated certificate store container, if applicable (see GET Certificate Store Containers).
ClientMachine The string value of the client machine. The value for this will vary depending on the certificate store type. For example, for a Java keystore or an F5 device, it is the hostname of the machine on which the store is located, but for an Amazon Web Services store, it is the FQDN of the Keyfactor Command Windows Orchestrator. See Adding or Modifying a Certificate Store in the Keyfactor Command Reference Guide for more information.
Storepath A string indicating the path to the certificate store on the target. The format for this path will vary depending on the certificate store type. For example, for a Java keystore, this will be a file path (e.g. /opt/myapp/store.jks), but for an F5 device, this will be a partition name on the device (e.g. Common). See Adding or Modifying a Certificate Store in the Keyfactor Command Reference Guide for more information. The maximum number of characters supported in this field is 722.
CertStoreInventoryJobId A string indicating the GUID that identifies the inventory job for the certificate store in the Keyfactor Command database. This will be null if an inventory schedule is not set for the certificate store.
CertStoreType An integer indicating the ID of the certificate store type, as defined in Keyfactor Command, for this certificate store. (0-Javakeystore,2-PEMFile, 3-F5SSLProfiles,4-IISRoots, 5-NetScaler, 6-IISPersonal, 7-F5WebServer, 8-IISRevoked, 9-F5WebServerREST, 10-F5SSLProfilesREST, 11-F5CABundlesREST, 100-AmazonWebServices, 101-FileTransferProtocol)
Approved A Boolean that indicates whether a certificate store is approved (true) or not (false). If a certificate store is approved, it can be used and updated. A certificate store that has been discovered using the discover feature but not yet marked as approved will be false here.
CreateIfMissing A Boolean that indicates whether a new certificate store should be created with the information provided (true) or not (false). This option is only valid for Java keystores and any custom certificate store types you have defined to support this functionality.
Properties

Some types of certificate stores have additional properties that are stored in this parameter. The data is stored in a series of, typically, key value pairs that define the property name and value (see GET Certificate Store Types for more information).

As of Keyfactor Command v10, this parameter is used to store certificate store server usernames, server passwords, and the UseSSL flag. Built-in certificate stores that typically require configuration of certificate store server parameters include NetScaler and F5 stores. The legacy methods for managing certificate store server credentials have been deprecated but are retained for backwards compatiblity. For more information, see POST Certificate Stores Server.

When reading this field, the values are returned as simple key value pairs, with the values being individual values. When writing, the values are specified as objects, though they are typically single values.

For example, on a GET request for a PEM store configured with a separate private key, the contents of this field might be:

"{
  \"privateKeyPath\":\"/opt/app/mystore.key\",
  \"separatePrivateKey\":\"true\"
}"

However, the syntax used when updating the properties sets the value as a key value pair using value as the key. For example, on a POST or PUT request for a PEM store configured with a separate private key, the contents of this field might be:

"{
  \"privateKeyPath\":{\"value\":\"/opt/app/mystore.key\"},
  \"separatePrivateKey\":{\"value\":\"true\"}
}"

An example server properties parameter POST for an FTP or NetScaler store would contain:

"{
   \"ServerUsername\":{\"value\":{\"SecretValue\":\"User_Name\"}},
   \"ServerPassword\":{\"value\":{\"SecretValue\":\"Password\"}},
   \"ServerUseSsl\":{\"value\":\"true\"}
}"

An example server properties parameter POST for an FTP or NetScaler store with the username and password stored as PAM secrets would contain (where the Provider value—1 in this example—is the Id value from GET PAM Providers):

"{
   \"ServerUsername\":{\"value\":{\"Provider\":\"1\",\"Parameters\":{\"SecretId\":\"User_Name\"}}},
   \"ServerPassword\":{\"value\":{\"Provider\":\"1\",\"Parameters\":{\"SecretId\":\"Password\"}}},
   \"ServerUseSsl\":{\"value\":\"true\"}
}"
Note:  There are three standard properties that are used for any built-in certificate store types that require server credentials (e.g. F5):
  • ServerUsername
  • ServerPassword

  • ServerUseSsl

These replace the separate certificate store server records that existed in previous versions of Keyfactor Command. For legacy support, if credentials are not provided through store properties during creation or editing of a certificate store, Keyfactor Command will attempt to find a certificate store server record and copy the credentials from it into the store properties for future use.

Tip:  Built-in stores that make use of this field include:
  • AWS stores use this field to store secured versions of the access key and secret.
  • F5 REST stores (all types) use this field to store secured versions of the server authentication information (ServerUsername, ServerPassword, ServerUseSsl) and primary node information (PrimaryNode, PrimaryNodeCheckRetryWaitSecs, PrimaryNodeCheckRetryMax) and F5 version (F5Version).
  • F5 SOAP stores (all types) use this field to store secured versions of the server authentication information (ServerUsername, ServerPassword, ServerUseSsl).
  • FTP stores use this field to store secured versions of the server authentication information (ServerUsername, ServerPassword, ServerUseSsl).
  • IIS stores (all types) use this field to store the UseSSL flag and the port for SMB communications.
  • Java keystores use this field to store type (ProviderType).
  • NetScaler stores use this field to store secured versions of the server authentication information (ServerUsername, ServerPassword, ServerUseSsl).
  • PEM stores use this field to store the path to the private key file, if defined, and the Boolean value indicating whether a separate private key path is defined.
AgentId A string indicating the Keyfactor Command GUID of the orchestrator for this store.
AgentAssigned A Boolean that indicates whether there is an orchestrator assigned to this certificate store (true) or not (false).
ContainerName A string indicating the name of the certificate store's associated container, if applicable.
InventorySchedule

The inventory schedule for this certificate store. ClosedShow schedule details.
ReenrollmentStatus

An array that indicates whether the certificate store can use the re-enrollment function with accompanying data about the re-enrollment job. ClosedShow reenrollment status details.
SetNewPasswordAllowed A Boolean that indicates whether the store password can be changed (true) or not (false).
Password
Note:  Secret data is stored in the secrets table or a PAM provider and is not returned in responses.
Tip:  For code examples, see the Keyfactor API Endpoint Utility. To find the embedded web copy of this utility, click the help icon () at the top of the Keyfactor Command Management Portal page next to the Log Out button.