Search/Get Certificate Inventory
Before you begin
- The user should have the ACF permission to view the inventory associated with the searched certificate(s).
- The field referenced in the search input must already be populated for the relevant certificates.
- The group associated with the relevant certificates should at least have read access.
Request Structure
| Endpoint: | /certificate/search |
| Type: | POST |
| Sample URL: |
To understand the elements of the sample URL, click here. |
| Headers | |
| Content-Type: | application/json |
| Name | Description |
|---|---|
| sessionId
|
(Mandatory if username and password
are not provided) Session Id received after login. Type: String |
| username
|
(Mandatory if sessionId is not provided)
AppViewX login username. Type: String |
| password
|
(Mandatory if sessionId is not provided)
AppViewX login password. Type: String |
| Content-Type
|
(Mandatory) Specifies the nature of the data in the
payload. Type: String Constraint: Value of the parameter should be ‘application/json’ |
| gwsource
|
(Mandatory) Source from which the request is
triggered Type: String |
| Payload
|
Contains all the parameters to be sent in the
request body for the post request. Type: Payload |
Payload
| Name | Description |
|---|---|
| input | (Mandatory) Search parameters such as keyword or free text search. |
| category
|
(Optional) Specifies the certificate category A comma-separated list of multiple values can also be provided, to search for certificates across categories. Type: String Possible values:
|
| resourceId
|
(Optional) Id of the certificate. Type: String |
| freeSearch
|
(Optional) Key for free text search Search will be performed on all cert fields based on the free text input provided. Type: String |
| keywordSearch
|
(Optional) Search by certificate attributes based on
the predefined key words. Type: String |
| subject:o
|
(Optional) Subject organization name Type: String |
| subject:ou
|
(Optional) Subject organization unit Type: String |
| subject:cn
|
(Optional) Subject common name Type: String |
| subject:l
|
(Optional) Subject location Type: String |
| subject:st
|
(Optional) Subject state Type: String |
| subject:c
|
(Optional) Subject country Type: String |
| certversion
|
(Optional) Certificate version Type: String |
| certserialno
|
(Optional) Certificate serial number Type: String Constraint: Serial number of the certificate to be specified in the same format as in example- 1C:DB:14:3D:5C:98:EC:00:D0:C1:D1:63:78:B4:AA:42 |
| certissuer
|
(Optional) Issuer common name Type: String |
| certstatus
|
(Optional) Certificate status Type: String Possible values: Managed, New Certificate, Monitored, Discovered |
| certgroup
|
(Optional) Certificate group. Type: String |
| expirydate
|
(Optional) Certificate expiry date in the MM/DD/YYYY
format For example, 03/26/2022 Type: String |
| expiryyear
|
(Optional) Certificate expiry year in the YYYY
format For example, 2022 Type: String |
| expirymonth
|
(Optional) Certificate expiry month in the MM
format For example, 03 Type: String |
| discoverysource
|
(Optional) Discovery source for the relevant
certificates For example, the device name or the CA setting name If a CA setting is to be specified, it should be entered in the following format: <<CA name>>::<<CA setting name>>. For example, EJBCA:: Setting1. Type: String |
| ca
|
(Optional) Certificate Authority name Type: String |
| application
|
(Optional) CA name / Auto-enrollment protocol name /
device vendor name Type: String Constraint: This input is applicable only for certificates that were discovered from a CA/a device and certificates that were enrolled using auto enrollment protocols. Possible values for auto enrollment protocols: SCEP, EST, ACME, SCEP_MS_INTUNE |
| issuer
|
(Optional) Issuer common name Type: String Constraint: Ensure that the entered value is obtained from the AppViewX certificate inventory or the certificate data, so a discrepancy/mismatch can be avoided. |
| hash
|
(Optional) Hash function Type: String Possible values: SHA160, SHA224, SHA256, SHA384, SHA512 |
| key
|
(Optional) Key type Type: String Possible values: RSA, EC, DSA |
| keylength
|
(Optional) Bit length depending on the key type
chosen Input value to be obtained from the defined CA policy. Type: String |
| caSettings
|
(Optional) CA setting name Input value to be obtained from the defined CA policy. Type: String |
| ellipticcurve
|
(Optional) Elliptic curve name Input value to be obtained from the defined CA policy. Type: String |
| filter | (Mandatory) Pagination and sort parameters for the search |
| start
|
(Optional) Start index from which the response has
to be displayed For example, if the search results must skip the first 100 and show results from value no.101, the value of this parameter will be 101. Type: Integer Default value: 0 |
| max
|
(Optional) The number of entries from the start
index to be displayed E.g., if the response is expected to have
skipped the first 100 and show the next 50, then the start index has
to be 101 and max has to be 50. For example, if the search results must display 50 values from the start index, the value of this parameter will be 50. Type: Integer Default value: 100 |
| sortOrder
|
(Optional) Sorting order for the search
results Type: String Possible: asc (default), desc |
| sortColumn
|
(Optional) Column name for sorting Type: String Default value: _id |
Response Structure
Response returns string of type application/json with the following body parameters:
| Name | Description |
|---|---|
| response | Contains the response attributes |
| response
|
Contains the inventory response attributes |
| objects
|
Certificate metadata Type: Array of Certificate json |
| totalRecords
|
Total number of records matching the search
criteria Type: String |
| obtainedRecords
|
Number of records fetched for the
query Type: String |
| obtainedRecordRange
|
Index of the records fetched |
| start
|
Start index of the fetched records Type: String |
| end
|
End index of the fetched records Type: String |
| message
|
Success or failure message Type: String |
| message | If matching records are found for the search query:
Matching results found for the given input.
If no records are available for the search query: No matching records found for the given input. Type: String |
| appStatusCode | Application specific status code for the response
It is a non-null value for a failure response. Type: String |
| tags | Additional information in case of failure response |
Status Codes
| HTTP Code | appStatusCode | Response Message |
|---|---|---|
| 200 OK | NA | Matching records are found for the search
query. Success message Matching results found for the given input. is displayed. |
| 404 Not Found | NA | No mtaching records found for the search query
The message No matching records found for the given input. is displayed. |
| 401 Unauthorized | AVX_GW_003 | Authentication failed, reason - Invalid
Credentials. Remediation: Ensure that valid username and password or a valid sessionId is provided as the header parameter. |
| 400 Bad Request | INVALID_REQUEST | Invalid sort order value Remediation:
Ensure that a valid value is provided for
|
| 400 Bad Request | INVALID_REQUEST | Invalid request specified Possible Causes:
Remediation: Ensure that valid filter values are provided. |
Sample Request/Response
{
"input":{
"category":"Server",
"keywordSearch" : {
"certserialno":"7E:94:56:98:57:F2:0E:3B"
}
},
"filter":{
"max":"100",
"start":"1",
"sortColumn":"commonName",
"sortOrder":"desc"
}
}{
"response": {
"httpStatusCode": 200,
"response": {
"objects": [
{
"commonName": "testcert5d.avx.com",
"serialNumber": "7E:94:56:98:57:F2:0E:3B",
"issuerCommonName": "Ejbca New Intermediate CA",
"status": "Managed",
"associatedObjects": [],
"discoverySources": [],
"subjectOrganization": "AppViewX",
"subjectOrganizationUnit": "PE",
"subjectLocality": "Plano",
"subjectState": "Texas",
"subjectCountry": "US",
"issuerOrganization": "",
"issuerOrganizationUnit": "",
"issuerLocality": "",
"issuerState": "",
"issuerCountry": "",
"version": "3",
"validFrom": 1598943490000,
"validTo": 1607583490000,
"validFor": "90 day(s) 18 hr(s) 8 min(s)",
"keyAlgorithmAndSize": "RSA 2048",
"signatureAlgorithm": "SHA256withRSA",
"signatureHashAlgorithm": "SHA256",
"keyUsage": "DigitalSignature, NonRepudiation, KeyEncipherment",
"extendedKeyUsage": "Client Authentication(1.3.6.1.5.5.7.3.2) Server Authentication(1.3.6.1.5.5.7.3.1) ",
"basicConstraints": "Subject Type=End entity, Path Length=none",
"group": "Default",
"subjectAlternativeNames": [
"URL : http://testcert5.avx.com",
"Email address : [email protected]",
"DNS : testcert5.avx.com",
"IP Address : 192.168.142.162"
],
"complianceStatus": "Compliant",
"applications": [],
"expiryStatus": "Valid",
"permission": "RW",
"category": "Server",
"uuid": "4f4e23cefea2297a4e7d6b202ceee5ba47a20c89",
"certificateAuthority": "Ejbca",
"authorityKeyIdentifier": "69:15:BC:24:60:6B:73:96:8B:F3:3A:ED:C4:38:EB:58:A6:3F:4B:5B",
"subjectKeyIdentifier": "0D:31:76:0B:F1:41:AD:A6:39:6B:79:A6:43:8D:62:07:CC:F5:94:FB",
"authorityInfoAccess": [],
"certificatePolicies": [],
"crlDistributionPoints": [
"CrlDistributionPoint : [ name : , url : http://192.168.12.139:8080/ejbca/publicweb/webdist/certdist?cmd=crl&issuer=CN=Ejbca%20New%20Intermediate%20CA ]"
],
"thumbprintAlgorithm": "SHA-1",
"thumbPrint": "9F:8E:0D:B6:A6:25:D4:05:E3:2B:5E:F7:85:1B:79:83:CB:EA:3C:DB",
"type": "Others",
"genericFields": {
"vs_ip_Ejbca": "192.168.142.162",
"device_name_Ejbca": "test_device"
},
"csrGenerationSource": "appviewx",
"newConnectors": [],
"csrAvailable": true,
"autoRenewDate": "",
"missingParamsForAutoRenew": "CSR parameters are available for certificate renewal",
"suspendedCertificate": false,
"mailAddress": "[email protected]",
"streetAddress": "",
"postalCode": "",
"requestIds": [
"R147",
"R241"
],
"publicKey": "30:82:01:0A:02:82:01:01:00:8B:64:08:1A:2B:40:B9:2F:7C:48:65:78:98:B3:A6:87:9D:E2:49:CF:25:A5:27:14:EE:A0:45:CE:E3:32:21:DC:8D:A5:AE:78:36:EF:5A:91:D6:7E:D9:F4:04:C5:A9:9A:38:F7:D4:C6:50:B2:4C:96:1C:AE:69:23:19:7C:45:87:07:37:4C:2C:07:25:87:6C:93:D0:B6:D0:5D:55:FC:29:A0:48:6A:75:CF:12:6C:41:AE:90:BD:E7:89:C5:C4:8D:81:78:3D:DD:0B:29:61:92:55:0E:5A:8F:44:8F:44:CE:07:D8:11:95:7F:03:33:DD:86:E0:9A:69:42:AD:C9:67:44:91:FF:B2:02:ED:1A:16:9C:B5:CC:03:92:3B:1A:17:52:D5:32:56:BF:52:D1:7C:8F:96:43:18:6E:43:22:55:32:01:4D:44:AA:52:13:6A:BB:B6:1B:DD:8D:76:D3:C6:C2:D0:D9:E0:9E:B8:4C:DD:0A:8D:5C:5E:20:02:79:20:26:84:7F:35:B7:EF:E0:98:D1:FC:37:D4:1B:B8:4C:07:64:00:E8:18:DC:63:98:85:56:F3:D0:F7:E4:EF:F1:C1:0F:B3:F2:86:48:73:36:A5:5D:AC:A9:A9:DE:F9:62:44:D0:C8:8D:F1:03:5F:3E:03:08:C8:0C:92:00:CF:72:55:02:03:01:00:01",
"issuedByRootCertificate": false,
"privatekeyAvaliable": true,
"resourceId": "5f4e5c2e70040d33314f0e9d"
}
],
"totalRecords": 1,
"obtainedRecords": 1,
"obtainedRecordRange": {
"start": 1,
"end": 1
}
},
"message": "Matching results found for the given input.",
"appStatusCode": null,
"tags": null
},
"message": null,
"appStatusCode": null,
"tags": {},
"headers": null
}References
- IP/HostName/TenantName: Replace with the actual IP address, hostname,
or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to
a computer network that uses the Internet Protocol for communication
The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host)
on a network
The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to
indicate which tenant's data the API request will
access/modify
The tenant name will be included in the endpoint URL for a SaaS deployment.
- IP: A unique identifier assigned to each device connected to
a computer network that uses the Internet Protocol for communication
- GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Example: 31443
- avxapi: Path parameter value (static) that is part of the endpoint's URL
- Endpoint: Endpoint of the API, for example: execute-hook
- gwsource: Source or origin of a gateway, for example: external.
