certificates

Creates, updates, deletes, gets or lists a certificates resource.

Overview

Name	certificates
Type	Resource
Id	google.privateca.certificates

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	Identifier. The resource name for this Certificate in the format projects/*/locations/*/caPools/*/certificates/*.
certificateDescription	object	A CertificateDescription describes an X.509 certificate or CSR that has been issued, as an alternative to using ASN.1 / X.509. (id: CertificateDescription)
certificateTemplate	string	Immutable. The resource name for a CertificateTemplate used to issue this certificate, in the format projects/*/locations/*/certificateTemplates/*. If this is specified, the caller must have the necessary permission to use this template. If this is omitted, no template will be used. This template must be in the same location as the Certificate.
config	object	Immutable. A description of the certificate and key that does not require X.509 or ASN.1. (id: CertificateConfig)
createTime	string (google-datetime)	Output only. The time at which this Certificate was created.
issuerCertificateAuthority	string	Output only. The resource name of the issuing CertificateAuthority in the format projects/*/locations/*/caPools/*/certificateAuthorities/*.
labels	object	Optional. Labels with user-defined metadata.
lifetime	string (google-duration)	Required. Immutable. The desired lifetime of a certificate. Used to create the "not_before_time" and "not_after_time" fields inside an X.509 certificate. Note that the lifetime may be truncated if it would extend past the life of any certificate authority in the issuing chain.
pemCertificate	string	Output only. The pem-encoded, signed X.509 certificate.
pemCertificateChain	array	Output only. The chain that may be used to verify the X.509 certificate. Expected to be in issuer-to-root order according to RFC 5246.
pemCsr	string	Immutable. A pem-encoded X.509 certificate signing request (CSR).
requestedNotBeforeTime	string (google-datetime)	Optional. The requested not_before_time of this Certificate. This field may only be set if the CaPool.IssuancePolicy.allow_requester_specified_not_before_time field is set to true for the issuing CaPool. If this field is specified, the certificate will be issued with this 'not_before_time'. If this is not specified, the 'not_before_time' will be set to the issuance time or issuance time minus backdate_duration depending on the CaPool configuration.
revocationDetails	object	Output only. Details regarding the revocation of this Certificate. This Certificate is considered revoked if and only if this field is present. (id: RevocationDetails)
subjectMode	string	Immutable. Specifies how the Certificate's identity fields are to be decided. If this is omitted, the DEFAULT subject mode will be used. (SUBJECT_REQUEST_MODE_UNSPECIFIED, DEFAULT, RDN_SEQUENCE, REFLECTED_SPIFFE)
updateTime	string (google-datetime)	Output only. The time at which this Certificate was updated.

list

Name	Datatype	Description
name	string	Identifier. The resource name for this Certificate in the format projects/*/locations/*/caPools/*/certificates/*.
certificateDescription	object	A CertificateDescription describes an X.509 certificate or CSR that has been issued, as an alternative to using ASN.1 / X.509. (id: CertificateDescription)
certificateTemplate	string	Immutable. The resource name for a CertificateTemplate used to issue this certificate, in the format projects/*/locations/*/certificateTemplates/*. If this is specified, the caller must have the necessary permission to use this template. If this is omitted, no template will be used. This template must be in the same location as the Certificate.
config	object	Immutable. A description of the certificate and key that does not require X.509 or ASN.1. (id: CertificateConfig)
createTime	string (google-datetime)	Output only. The time at which this Certificate was created.
issuerCertificateAuthority	string	Output only. The resource name of the issuing CertificateAuthority in the format projects/*/locations/*/caPools/*/certificateAuthorities/*.
labels	object	Optional. Labels with user-defined metadata.
lifetime	string (google-duration)	Required. Immutable. The desired lifetime of a certificate. Used to create the "not_before_time" and "not_after_time" fields inside an X.509 certificate. Note that the lifetime may be truncated if it would extend past the life of any certificate authority in the issuing chain.
pemCertificate	string	Output only. The pem-encoded, signed X.509 certificate.
pemCertificateChain	array	Output only. The chain that may be used to verify the X.509 certificate. Expected to be in issuer-to-root order according to RFC 5246.
pemCsr	string	Immutable. A pem-encoded X.509 certificate signing request (CSR).
requestedNotBeforeTime	string (google-datetime)	Optional. The requested not_before_time of this Certificate. This field may only be set if the CaPool.IssuancePolicy.allow_requester_specified_not_before_time field is set to true for the issuing CaPool. If this field is specified, the certificate will be issued with this 'not_before_time'. If this is not specified, the 'not_before_time' will be set to the issuance time or issuance time minus backdate_duration depending on the CaPool configuration.
revocationDetails	object	Output only. Details regarding the revocation of this Certificate. This Certificate is considered revoked if and only if this field is present. (id: RevocationDetails)
subjectMode	string	Immutable. Specifies how the Certificate's identity fields are to be decided. If this is omitted, the DEFAULT subject mode will be used. (SUBJECT_REQUEST_MODE_UNSPECIFIED, DEFAULT, RDN_SEQUENCE, REFLECTED_SPIFFE)
updateTime	string (google-datetime)	Output only. The time at which this Certificate was updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, caPoolsId, certificatesId		Returns a Certificate.
list	select	projectsId, locationsId, caPoolsId	pageToken, filter, orderBy, pageSize	Lists Certificates.
create	insert	projectsId, locationsId, caPoolsId	certificateId, validateOnly, issuingCertificateAuthorityId, requestId	Create a new Certificate in a given Project, Location from a particular CaPool.
patch	update	projectsId, locationsId, caPoolsId, certificatesId	requestId, updateMask	Update a Certificate. Currently, the only field you can update is the labels field.
revoke	exec	projectsId, locationsId, caPoolsId, certificatesId		Revoke a Certificate.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
caPoolsId	string
certificatesId	string
locationsId	string
projectsId	string
certificateId	string
filter	string
issuingCertificateAuthorityId	string
orderBy	string
pageSize	integer (int32)
pageToken	string
requestId	string
updateMask	string (google-fieldmask)
validateOnly	boolean

SELECT examples

get

Returns a Certificate.

SELECT
name,
certificateDescription,
certificateTemplate,
config,
createTime,
issuerCertificateAuthority,
labels,
lifetime,
pemCertificate,
pemCertificateChain,
pemCsr,
requestedNotBeforeTime,
revocationDetails,
subjectMode,
updateTime
FROM google.privateca.certificates
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND caPoolsId = '{{ caPoolsId }}' -- required
AND certificatesId = '{{ certificatesId }}' -- required
;

list

Lists Certificates.

SELECT
name,
certificateDescription,
certificateTemplate,
config,
createTime,
issuerCertificateAuthority,
labels,
lifetime,
pemCertificate,
pemCertificateChain,
pemCsr,
requestedNotBeforeTime,
revocationDetails,
subjectMode,
updateTime
FROM google.privateca.certificates
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND caPoolsId = '{{ caPoolsId }}' -- required
AND pageToken = '{{ pageToken }}'
AND filter = '{{ filter }}'
AND orderBy = '{{ orderBy }}'
AND pageSize = '{{ pageSize }}'
;

INSERT examples

create

Create a new Certificate in a given Project, Location from a particular CaPool.

INSERT INTO google.privateca.certificates (
data__pemCsr,
data__config,
data__labels,
data__certificateTemplate,
data__name,
data__lifetime,
data__subjectMode,
data__requestedNotBeforeTime,
projectsId,
locationsId,
caPoolsId,
certificateId,
validateOnly,
issuingCertificateAuthorityId,
requestId
)
SELECT 
'{{ pemCsr }}',
'{{ config }}',
'{{ labels }}',
'{{ certificateTemplate }}',
'{{ name }}',
'{{ lifetime }}',
'{{ subjectMode }}',
'{{ requestedNotBeforeTime }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ caPoolsId }}',
'{{ certificateId }}',
'{{ validateOnly }}',
'{{ issuingCertificateAuthorityId }}',
'{{ requestId }}'
RETURNING
name,
certificateDescription,
certificateTemplate,
config,
createTime,
issuerCertificateAuthority,
labels,
lifetime,
pemCertificate,
pemCertificateChain,
pemCsr,
requestedNotBeforeTime,
revocationDetails,
subjectMode,
updateTime
;

Manifest

# Description fields are for documentation purposes
- name: certificates
props:
  - name: projectsId
    value: "{{ projectsId }}"
    description: Required parameter for the certificates resource.
  - name: locationsId
    value: "{{ locationsId }}"
    description: Required parameter for the certificates resource.
  - name: caPoolsId
    value: "{{ caPoolsId }}"
    description: Required parameter for the certificates resource.
  - name: pemCsr
    value: "{{ pemCsr }}"
    description: |
      Immutable. A pem-encoded X.509 certificate signing request (CSR).
  - name: config
    description: |
      Immutable. A description of the certificate and key that does not require X.509 or ASN.1.
    value:
      subjectKeyId:
        keyId: "{{ keyId }}"
      subjectConfig:
        subject:
          organizationalUnit: "{{ organizationalUnit }}"
          streetAddress: "{{ streetAddress }}"
          commonName: "{{ commonName }}"
          organization: "{{ organization }}"
          province: "{{ province }}"
          locality: "{{ locality }}"
          postalCode: "{{ postalCode }}"
          rdnSequence:
            - attributes: "{{ attributes }}"
          countryCode: "{{ countryCode }}"
        subjectAltName:
          ipAddresses:
            - "{{ ipAddresses }}"
          dnsNames:
            - "{{ dnsNames }}"
          emailAddresses:
            - "{{ emailAddresses }}"
          uris:
            - "{{ uris }}"
          customSans:
            - critical: {{ critical }}
              objectId:
                objectIdPath: "{{ objectIdPath }}"
              value: "{{ value }}"
      publicKey:
        format: "{{ format }}"
        key: "{{ key }}"
      x509Config:
        caOptions:
          isCa: {{ isCa }}
          maxIssuerPathLength: {{ maxIssuerPathLength }}
        aiaOcspServers:
          - "{{ aiaOcspServers }}"
        additionalExtensions:
          - critical: {{ critical }}
            objectId:
              objectIdPath:
                - {{ objectIdPath }}
            value: "{{ value }}"
        policyIds:
          - objectIdPath: "{{ objectIdPath }}"
        nameConstraints:
          critical: {{ critical }}
          excludedIpRanges:
            - "{{ excludedIpRanges }}"
          permittedEmailAddresses:
            - "{{ permittedEmailAddresses }}"
          excludedDnsNames:
            - "{{ excludedDnsNames }}"
          permittedUris:
            - "{{ permittedUris }}"
          excludedEmailAddresses:
            - "{{ excludedEmailAddresses }}"
          excludedUris:
            - "{{ excludedUris }}"
          permittedIpRanges:
            - "{{ permittedIpRanges }}"
          permittedDnsNames:
            - "{{ permittedDnsNames }}"
        keyUsage:
          baseKeyUsage:
            keyEncipherment: {{ keyEncipherment }}
            certSign: {{ certSign }}
            digitalSignature: {{ digitalSignature }}
            contentCommitment: {{ contentCommitment }}
            encipherOnly: {{ encipherOnly }}
            decipherOnly: {{ decipherOnly }}
            dataEncipherment: {{ dataEncipherment }}
            crlSign: {{ crlSign }}
            keyAgreement: {{ keyAgreement }}
          extendedKeyUsage:
            serverAuth: {{ serverAuth }}
            clientAuth: {{ clientAuth }}
            emailProtection: {{ emailProtection }}
            ocspSigning: {{ ocspSigning }}
            codeSigning: {{ codeSigning }}
            timeStamping: {{ timeStamping }}
          unknownExtendedKeyUsages:
            - objectIdPath: "{{ objectIdPath }}"
  - name: labels
    value: "{{ labels }}"
    description: |
      Optional. Labels with user-defined metadata.
  - name: certificateTemplate
    value: "{{ certificateTemplate }}"
    description: |
      Immutable. The resource name for a CertificateTemplate used to issue this certificate, in the format `projects/*/locations/*/certificateTemplates/*`. If this is specified, the caller must have the necessary permission to use this template. If this is omitted, no template will be used. This template must be in the same location as the Certificate.
  - name: name
    value: "{{ name }}"
    description: |
      Identifier. The resource name for this Certificate in the format `projects/*/locations/*/caPools/*/certificates/*`.
  - name: lifetime
    value: "{{ lifetime }}"
    description: |
      Required. Immutable. The desired lifetime of a certificate. Used to create the "not_before_time" and "not_after_time" fields inside an X.509 certificate. Note that the lifetime may be truncated if it would extend past the life of any certificate authority in the issuing chain.
  - name: subjectMode
    value: "{{ subjectMode }}"
    description: |
      Immutable. Specifies how the Certificate's identity fields are to be decided. If this is omitted, the `DEFAULT` subject mode will be used.
    valid_values: ['SUBJECT_REQUEST_MODE_UNSPECIFIED', 'DEFAULT', 'RDN_SEQUENCE', 'REFLECTED_SPIFFE']
  - name: requestedNotBeforeTime
    value: "{{ requestedNotBeforeTime }}"
    description: |
      Optional. The requested not_before_time of this Certificate. This field may only be set if the CaPool.IssuancePolicy.allow_requester_specified_not_before_time field is set to true for the issuing CaPool. If this field is specified, the certificate will be issued with this 'not_before_time'. If this is not specified, the 'not_before_time' will be set to the issuance time or issuance time minus backdate_duration depending on the CaPool configuration.
  - name: certificateId
    value: "{{ certificateId }}"
  - name: validateOnly
    value: {{ validateOnly }}
  - name: issuingCertificateAuthorityId
    value: "{{ issuingCertificateAuthorityId }}"
  - name: requestId
    value: "{{ requestId }}"

UPDATE examples

patch

Update a Certificate. Currently, the only field you can update is the labels field.

UPDATE google.privateca.certificates
SET 
data__pemCsr = '{{ pemCsr }}',
data__config = '{{ config }}',
data__labels = '{{ labels }}',
data__certificateTemplate = '{{ certificateTemplate }}',
data__name = '{{ name }}',
data__lifetime = '{{ lifetime }}',
data__subjectMode = '{{ subjectMode }}',
data__requestedNotBeforeTime = '{{ requestedNotBeforeTime }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND caPoolsId = '{{ caPoolsId }}' --required
AND certificatesId = '{{ certificatesId }}' --required
AND requestId = '{{ requestId}}'
AND updateMask = '{{ updateMask}}'
RETURNING
name,
certificateDescription,
certificateTemplate,
config,
createTime,
issuerCertificateAuthority,
labels,
lifetime,
pemCertificate,
pemCertificateChain,
pemCsr,
requestedNotBeforeTime,
revocationDetails,
subjectMode,
updateTime;

Lifecycle Methods

revoke

Revoke a Certificate.

EXEC google.privateca.certificates.revoke 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@caPoolsId='{{ caPoolsId }}' --required, 
@certificatesId='{{ certificatesId }}' --required 
@@json=
'{
"reason": "{{ reason }}", 
"requestId": "{{ requestId }}"
}'
;