[ aws . acm ]

list-certificates

Description

Retrieves a list of certificate ARNs and domain names. You can request that only certificates that match a specific status be listed. You can also filter by specific attributes of the certificate. Default filtering returns only RSA_2048 certificates. For more information, see Filters .

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

list-certificates is a paginated operation. Multiple API calls may be issued in order to retrieve the entire data set of results. You can disable pagination by providing the --no-paginate argument. When using --output text and the --query argument on a paginated response, the --query argument must extract data from the results of the following query expressions: CertificateSummaryList

Synopsis

  list-certificates
[--certificate-statuses <value>]
[--includes <value>]
[--max-items <value>]
[--cli-input-json | --cli-input-yaml]
[--starting-token <value>]
[--page-size <value>]
[--generate-cli-skeleton <value>]

Options

--certificate-statuses (list)

Filter the certificate list by status value.

(string)

Syntax:

"string" "string" ...

Where valid values are:
  PENDING_VALIDATION
  ISSUED
  INACTIVE
  EXPIRED
  VALIDATION_TIMED_OUT
  REVOKED
  FAILED

--includes (structure)

Filter the certificate list. For more information, see the Filters structure.

extendedKeyUsage -> (list)

Specify one or more ExtendedKeyUsage extension values.

(string)

keyUsage -> (list)

Specify one or more KeyUsage extension values.

(string)

keyTypes -> (list)

Specify one or more algorithms that can be used to generate key pairs.

Default filtering returns only RSA_2048 certificates. To return other certificate types, provide the desired type signatures in a comma-separated list. For example, "keyTypes": ["RSA_2048,RSA_4096"] returns both RSA_2048 and RSA_4096 certificates.

(string)

Shorthand Syntax:

extendedKeyUsage=string,string,keyUsage=string,string,keyTypes=string,string

JSON Syntax:

{
  "extendedKeyUsage": ["TLS_WEB_SERVER_AUTHENTICATION"|"TLS_WEB_CLIENT_AUTHENTICATION"|"CODE_SIGNING"|"EMAIL_PROTECTION"|"TIME_STAMPING"|"OCSP_SIGNING"|"IPSEC_END_SYSTEM"|"IPSEC_TUNNEL"|"IPSEC_USER"|"ANY"|"NONE"|"CUSTOM", ...],
  "keyUsage": ["DIGITAL_SIGNATURE"|"NON_REPUDIATION"|"KEY_ENCIPHERMENT"|"DATA_ENCIPHERMENT"|"KEY_AGREEMENT"|"CERTIFICATE_SIGNING"|"CRL_SIGNING"|"ENCIPHER_ONLY"|"DECIPHER_ONLY"|"ANY"|"CUSTOM", ...],
  "keyTypes": ["RSA_2048"|"RSA_1024"|"RSA_4096"|"EC_prime256v1"|"EC_secp384r1"|"EC_secp521r1", ...]
}

--max-items (integer)

The total number of items to return in the command’s output. If the total number of items available is more than the value specified, a NextToken is provided in the command’s output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. Do not use the NextToken response element directly outside of the AWS CLI.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--starting-token (string)

A token to specify where to start paginating. This is the NextToken from a previously truncated response.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--page-size (integer)

The size of each page to get in the AWS service call. This does not affect the number of items returned in the command’s output. Setting a smaller page size results in more calls to the AWS service, retrieving fewer items in each call. This can help prevent the AWS service calls from timing out.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See ‘aws help’ for descriptions of global parameters.

Examples

To list the ACM certificates for an AWS account

The following list-certificates command lists the ARNs of the certificates in your account:

aws acm list-certificates

The preceding command produces output similar to the following:

{
    "CertificateSummaryList": [
        {
            "CertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012",
            "DomainName": "www.example.com"
        },
        {
            "CertificateArn": "arn:aws:acm:us-east-1:493619779192:certificate/87654321-4321-4321-4321-210987654321",
            "DomainName": "www.example.net"
        }
    ]
}

You can decide how many certificates you want to display each time you call list-certificates. For example, if you have four certificates and you want to display no more than two at a time, set the max-items argument to 2 as in the following example:

aws acm list-certificates --max-items 2

Two certificate ARNs and a NextToken value will be displayed:

"CertificateSummaryList": [
  {
    "CertificateArn": "arn:aws:acm:us-east-1:123456789012: \
            certificate/12345678-1234-1234-1234-123456789012",
    "DomainName": "www.example.com"
  },
  {
    "CertificateArn": "arn:aws:acm:us-east-1:123456789012: \
            certificate/87654321-4321-4321-4321-210987654321",
    "DomainName": "www.example.net"
  }
  ],
    "NextToken": "9f4d9f69-275a-41fe-b58e-2b837bd9ba48"

To display the next two certificates in your account, set this NextToken value in your next call:

aws acm list-certificates --max-items 2 --next-token 9f4d9f69-275a-41fe-b58e-2b837bd9ba48

You can filter your output by using the certificate-statuses argument. The following command displays certificates that have a PENDING_VALIDATION status:

aws acm list-certificates --certificate-statuses PENDING_VALIDATION

You can also filter your output by using the includes argument. The following command displays certificates filtered on the following properties. The certificates to be displayed:

- Specify that the RSA algorithm and a 2048 bit key are used to generate key pairs.
- Contain a Key Usage extension that specifies that the certificates can be used to create digital signatures.
- Contain an Extended Key Usage extension that specifies that the certificates can be used for code signing.

aws acm list-certificates --max-items 10 --includes extendedKeyUsage=CODE_SIGNING,keyUsage=DIGITAL_SIGNATURE,keyTypes=RSA_2048

Output

NextToken -> (string)

When the list is truncated, this value is present and contains the value to use for the NextToken parameter in a subsequent pagination request.

CertificateSummaryList -> (list)

A list of ACM certificates.

(structure)

This structure is returned in the response object of ListCertificates action.

CertificateArn -> (string)

Amazon Resource Name (ARN) of the certificate. This is of the form:

arn:aws:acm:region:123456789012:certificate/12345678-1234-1234-1234-123456789012

For more information about ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces .

DomainName -> (string)

Fully qualified domain name (FQDN), such as www.example.com or example.com, for the certificate.