Sort and filter certificates

This page describes how you can sort and filter the certificates that are returned by the ListCertificates API call in Certificate Authority Service.

Sorting support

By default, the ListCertificates API call returns the certificates ordered by the create_time field, with the newest certificates being listed first. No other sort order can be specified.

Filtering support

The following fields can be used for filtering the certificates returned by the ListCertificates API call:

Field Name Field Type Supported Operators
create_time timestamp <, >, <=, >=, =, !=
update_time timestamp <, >, <=, >=, =, !=
certificate_description.subject_description.not_after_time timestamp <, >, <=, >=, =, !=
certificate_description.subject_description.not_before_time timestamp <, >, <=, >=, =, !=
certificate_description.cert_fingerprint.sha256_hash string =, !=
certificate_description.subject_description.hex_serial_number string =, !=
certificate_description.subject_description.subject.common_name string =, !=
certificate_description.subject_description.subject.country_code string =, !=
certificate_description.subject_description.subject.organization string =, !=
certificate_description.subject_description.subject.organizational_unit string =, !=
certificate_description.subject_description.subject.locality string =, !=
certificate_description.subject_description.subject.province string =, !=
certificate_description.subject_description.subject.street_address string =, !=
certificate_description.subject_description.subject.postal_code string =, !=
certificate_description.subject_description.subject_alt_name.dns_names string : (HAS operator)
certificate_description.x509_description.key_usage.extended_key_usage.client_auth bool =, !=
certificate_description.x509_description.key_usage.extended_key_usage.server_auth bool =, !=
labels map : (HAS operator)
certificate_template string =, !=

(https://google.aip.dev/160#has-operator)

Note: The fields certificate_description.x509_description.key_usage.extended_key_usage.client_auth and certificate_description.x509_description.key_usage.extended_key_usage.server_auth are booleans that refer to whether the respective Extended Key Usages are present.

Filtering syntax

The filtering syntax is following the API Filtering guidance set in AIP 160 with the following limitations:

  • only top level AND operators are supported. Everything else is not (for example, OR, NOT, nested operators, or any combination of these operators).

    • Valid: Filter uses only top level AND operator:

      create_time>"2020-08-21T11:30:00.11-05:00" AND certificate_description.x509_description.key_usage.extended_key_usage.server_auth=true

    • Invalid: Filter uses OR operator:

       create_time>"2020-08-21T11:30:00.11-05:00" OR certificate_description.x509_description.key_usage.extended_key_usage.server_auth=true

    • Invalid: Filter uses nested operators:

       (create_time>"2020-08-21T11:30:00.11-05:00" AND certificate_description.x509_description.key_usage.extended_key_usage.server_auth=true) AND certificate_description.subject_description.subject.common_name="foo.com"

  • wildcard matching (using *) is not supported except for the certificate_description.subject_description.subject_alt_name.dns_names field which supports suffix matching for the DNS labels.

    • Valid: Filter compares a wildcard suffix match:

      certificate_description.subject_description.subject_alt_name.dns_names:"*.foo.com"

    • Invalid: Filter compares with a wildcard prefix match:

      certificate_description.subject_description.subject_alt_name.dns_names:"foo.*"

    • Invalid: Filter compares with a wildcard for an unsupported field:

      "certificate_description.subject_description.hex_serial_number"="*3d3"

What's next