Certificates attribute filters

GET Certificates and HEAD Certificates can filter by certificate attributes. Attribute filters return case insensitive results. For example, a search for OU=Engineering, returns certificates with OU: ENGINEERING, OU:Engineering, and OU:engineering.

You can use multiple Certificates status filters and Certificates attribute filters in the same API call. The syntax is the same for both:

  • Certificates with two possible values from the same filter, use the ampersand (&) symbol as the OR operator.
  • Certificates with a range of values from the same filter, list each value and use the comma (,) separator as the OR operator.
  • Certificates that meet criteria from multiple filters, use the ampersand (&) symbol as the AND operator.

For example:

...OU=Engineering&OU=QA  //Find certs that have either value
...OU=Engineering,BldgA,BldgB  //Find certs having one value from the list
...CN=test.com&SAN-IP=10.20.30.40 //Find certs based on both filters
Attribute filters

Certificates filter attribute

Description

C

Find certificates by Country attribute of Subject DN.

Example: C=US

CertificateType

Find certificates by category of usage. Use CodeSigning, Device, Server, and/or User. As a best practice, you should always specify at least one CertificateType. Otherwise, the API call returns relevant certificates regardless of the certificate type, including certificates that have not yet been classified by the daily task.

Example: CertificateType=Server,Device returns certificates for servers or devices.

CN

Find certificates by Common name attribute of Subject DN.

Example: CN=test.venafi.com

Issuer

Find certificates by issuer. Use the CN ,O, L, S, and C values from the certificate request.

  • Surround the complete value within double quotes (").
  • If a value already has double quotes, escape them with a second set of double quotes. For example, OU=""(c) 2020 Entrust, Inc. - for authorized use only"".

Example: CN=Example Root CA, O=Venafi,Inc., L=Salt Lake City, S=Utah, C=US

IsSelfSigned

Find certificates based on the signer:

  • 0: Default. Only return CA-signed certificates. Self-signed CA root certificates are also included because they generally only appear in the Policy tree if they are being misused as TLS server certificates.
  • 1: Only return self-signed certificates.

Example: IsSelfSigned=1

IsWildcard

Find certificates based on the Certificate CN or DNS SAN:

  • 0: Default. Omit wild card notation as part of the CN and DNS SANs.
  • 1: Only return certificates that have a CN or DNS SAN that begin with *. wild card notation.

Example: IsWildcard=1

KeyAlgorithm

Find certificates by algorithm for the public key.

Example: KeyAlgorithm=RSA,DSA

KeySize

Find certificates by public key size.

Example: KeySize=1024,2048

KeySizeGreater

Find certificates with a key size that is larger than the one you specified.

Example: KeySizeGreater=1024

KeySizeLess

Find certificates with a key size that is smaller than the one you specified.

Example: KeySizeLess=1025

L

Find certificates by Locality/City attribute of Subject Distinguished Name (SDN).

Example: L=London

O

Find certificates by Organization attribute of Subject DN.

Example: O=Venafi%20Inc.,BankABC

OU

Find certificates by Organization Unit (OU).

Example: OU=Quality Assurance.

S

Find certificates by State/Province attribute of Subject DN.

Example: S=New%20York, Georgia

SAN-DNS

Find certificates by Subject Alternate Name (SAN) Distinguished Name Server (DNS).

Example: SAN-DNS = sso.venafi.example

SAN-Email

Find certificates by SAN Email RFC822.

Example: SAN-Email=first.last@venafi.example

SAN-IP

Find certificates by SAN IP Address.

Example: SAN-IP=10.20.30.40

SAN-UPN

Find certificates by SAN User Principal Name (UPN) or OtherName.

Example: SAN-UPN=My.Email@venafi.example

SAN-URI

Find certificates by SAN Uniform Resource Identifier (URI).

Example: SAN-URI=https://login.venafi.example

Serial

Find certificates by Serial number.

Example: Serial=13279B74000000000053

SignatureAlgorithm

Find certificates by the algorithm used to sign the certificate.

Example: SignatureAlgorithm=sha1RSA,md5RSA,sha256RSA

Thumbprint

Find certificates by one or more SHA-1 thumbprints. To get the thumbprint value, also known as a fingerprint, call GET Certificates/{guid}.

Example: Thumbprint=71E8672798C03842735293EF49425EF06C7FA8AB& Thumbprint=8BEA4EEA4D045BC1E01CD08F16A0CB4046AF7AED

ValidFrom

Find certificates by the date of issue. Specify the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ or HH:MM:SS.mmmmmmmZ

Example: ValidFrom=2021-02-11T21:36:22.0000000Z

ValidFromGreater

Find certificates that expire after YYYY-MM-DD.

Example: ValidFromGreater=2021-02-11

ValidFromLess

Find certificates that expire before YYYY-MM-DD.

Example: ValidFromLess=2022-02-11

ValidTo

Find certificates by expiration date. Specify the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ or HH:MM:SS.mmmmmmmZ

Example: ValidTo=2022-02-11T21:36:22.0000000Z

ValidToGreater

Find certificates that expire after a certain date. Specify the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ or HH:MM:SS.mmmmmmmZ

Example: ValidToGreater=2021-02-11T21:36:22.0000000Z

ValidToLess

Find certificates that expire before a certain date. Specify the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ or HH:MM:SS.mmmmmmmZ

Example: ValidToLess=2022-02-11T21:36:22.0000000Z