mmv1/products/privateca/CaPool.yaml

# Copyright 2024 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
name: 'CaPool'
description: |
  A CaPool represents a group of CertificateAuthorities that form a trust anchor. A CaPool can be used to manage
  issuance policies for one or more CertificateAuthority resources and to rotate CA certificates in and out of the
  trust anchor.
references:
  guides:
    'Certificate Authority Service Overview': 'https://cloud.google.com/certificate-authority-service/docs/overview'
  api: 'https://cloud.google.com/certificate-authority-service/docs/reference/rest/v1/projects.locations.caPools'
docs:
base_url: 'projects/{{project}}/locations/{{location}}/caPools'
self_link: 'projects/{{project}}/locations/{{location}}/caPools/{{name}}'
create_url: 'projects/{{project}}/locations/{{location}}/caPools?caPoolId={{name}}'
update_verb: 'PATCH'
update_mask: true
import_format:
  - 'projects/{{project}}/locations/{{location}}/caPools/{{name}}'
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
autogen_async: true
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: true
iam_policy:
  method_name_separator: ':'
  allowed_iam_role: 'roles/privateca.certificateManager'
  parent_resource_attribute: 'ca_pool'
  iam_conditions_request_type: 'QUERY_PARAM_NESTED'
  example_config_body: 'templates/terraform/iam/example_config_body/privateca_ca_pool.tf.tmpl'
custom_code:
examples:
  - name: 'privateca_capool_basic'
    primary_resource_id: 'default'
    primary_resource_name: 'fmt.Sprintf("tf-test-my-pool%s", context["random_suffix"])'
    vars:
      name: 'my-pool'
  - name: 'privateca_capool_all_fields'
    primary_resource_id: 'default'
    vars:
      name: 'my-pool'
  - name: 'privateca_quickstart'
    primary_resource_id: 'default'
    vars:
      my_ca_pool: 'my-ca-pool'
      my_certificate: 'my-certificate'
    exclude_test: true
    exclude_docs: true
parameters:
  - name: 'location'
    type: String
    description: |
      Location of the CaPool. A full list of valid locations can be found by
      running `gcloud privateca locations list`.
    url_param_only: true
    required: true
    immutable: true
properties:
  - name: 'name'
    type: String
    description: |
      The name for this CaPool.
    url_param_only: true
    required: true
    immutable: true
  - name: 'tier'
    type: Enum
    description: |
      The Tier of this CaPool.
    required: true
    immutable: true
    enum_values:
      - 'ENTERPRISE'
      - 'DEVOPS'
  - name: 'issuancePolicy'
    type: NestedObject
    description: |
      The IssuancePolicy to control how Certificates will be issued from this CaPool.
    properties:
      - name: 'allowedKeyTypes'
        type: Array
        description: |
          If any AllowedKeyType is specified, then the certificate request's public key must match one of the key types listed here.
          Otherwise, any key may be used.
        item_type:
          type: NestedObject
          properties:
            - name: 'rsa'
              type: NestedObject
              description: |
                Describes an RSA key that may be used in a Certificate issued from a CaPool.
              properties:
                - name: 'minModulusSize'
                  type: String
                  description: |
                    The minimum allowed RSA modulus size, in bits. If this is not set, or if set to zero, the
                    service-level min RSA modulus size will continue to apply.
                - name: 'maxModulusSize'
                  type: String
                  description: |
                    The maximum allowed RSA modulus size, in bits. If this is not set, or if set to zero, the
                    service will not enforce an explicit upper bound on RSA modulus sizes.
            - name: 'ellipticCurve'
              type: NestedObject
              description: |
                Represents an allowed Elliptic Curve key type.
              properties:
                - name: 'signatureAlgorithm'
                  type: Enum
                  description: |
                    The algorithm used.
                  required: true
                  enum_values:
                    - 'ECDSA_P256'
                    - 'ECDSA_P384'
                    - 'EDDSA_25519'
      - name: 'backdateDuration'
        type: String
        description: |
          The duration to backdate all certificates issued from this CaPool. If not set, the
          certificates will be issued with a not_before_time of the issuance time (i.e. the current
          time). If set, the certificates will be issued with a not_before_time of the issuance
          time minus the backdate_duration. The not_after_time will be adjusted to preserve the
          requested lifetime. The backdate_duration must be less than or equal to 48 hours.
      - name: 'maximumLifetime'
        type: String
        description: |
          The maximum lifetime allowed for issued Certificates. Note that if the issuing CertificateAuthority
          expires before a Certificate's requested maximumLifetime, the effective lifetime will be explicitly truncated to match it.
      - name: 'allowedIssuanceModes'
        type: NestedObject
        description: |
          IssuanceModes specifies the allowed ways in which Certificates may be requested from this CaPool.
        properties:
          - name: 'allowCsrBasedIssuance'
            type: Boolean
            description: |
              When true, allows callers to create Certificates by specifying a CSR.
            required: true
          - name: 'allowConfigBasedIssuance'
            type: Boolean
            description: |
              When true, allows callers to create Certificates by specifying a CertificateConfig.
            required: true
      - name: 'identityConstraints'
        type: NestedObject
        description: |
          Describes constraints on identities that may appear in Certificates issued through this CaPool.
          If this is omitted, then this CaPool will not add restrictions on a certificate's identity.
        properties:
          - name: 'allowSubjectPassthrough'
            type: Boolean
            description: |
              If this is set, the Subject field may be copied from a certificate request into the signed certificate.
              Otherwise, the requested Subject will be discarded.
            required: true
            send_empty_value: true
          - name: 'allowSubjectAltNamesPassthrough'
            type: Boolean
            description: |
              If this is set, the SubjectAltNames extension may be copied from a certificate request into the signed certificate.
              Otherwise, the requested SubjectAltNames will be discarded.
            required: true
            send_empty_value: true
          - name: 'celExpression'
            type: NestedObject
            description: |
              A CEL expression that may be used to validate the resolved X.509 Subject and/or Subject Alternative Name before a
              certificate is signed. To see the full allowed syntax and some examples,
              see https://cloud.google.com/certificate-authority-service/docs/cel-guide
            properties:
              - name: 'expression'
                type: String
                description: |
                  Textual representation of an expression in Common Expression Language syntax.
                required: true
              - name: 'title'
                type: String
                description: |
                  Title for the expression, i.e. a short string describing its purpose. This can be used e.g. in UIs which allow to enter the expression.
              - name: 'description'
                type: String
                description: |
                  Description of the expression. This is a longer text which describes the expression, e.g. when hovered over it in a UI.
              - name: 'location'
                type: String
                description: |
                  String indicating the location of the expression for error reporting, e.g. a file name and a position in the file.
      - name: 'baselineValues'
        type: NestedObject
        description: |
          A set of X.509 values that will be applied to all certificates issued through this CaPool. If a certificate request
          includes conflicting values for the same properties, they will be overwritten by the values defined here. If a certificate
          request uses a CertificateTemplate that defines conflicting predefinedValues for the same properties, the certificate
          issuance request will fail.
        custom_flatten: 'templates/terraform/custom_flatten/privateca_certificate_509_config.go.tmpl'
        custom_expand: 'templates/terraform/custom_expand/privateca_certificate_509_config.go.tmpl'
        properties:
          - name: 'additionalExtensions'
            type: Array
            description: |
              Specifies an X.509 extension, which may be used in different parts of X.509 objects like certificates, CSRs, and CRLs.
            item_type:
              type: NestedObject
              properties:
                - name: 'critical'
                  type: Boolean
                  description: |
                    Indicates whether or not this extension is critical (i.e., if the client does not know how to
                    handle this extension, the client should consider this to be an error).
                  required: true
                - name: 'value'
                  type: String
                  description: |
                    The value of this X.509 extension. A base64-encoded string.
                  required: true
                - name: 'objectId'
                  type: NestedObject
                  description: |
                    Describes values that are relevant in a CA certificate.
                  required: true
                  properties:
                    - name: 'objectIdPath'
                      type: Array
                      description: |
                        An ObjectId specifies an object identifier (OID). These provide context and describe types in ASN.1 messages.
                      required: true
                      item_type:
                        type: Integer
          - name: 'policyIds'
            type: Array
            description: |
              Describes the X.509 certificate policy object identifiers, per https://tools.ietf.org/html/rfc5280#section-4.2.1.4.
            item_type:
              type: NestedObject
              properties:
                - name: 'objectIdPath'
                  type: Array
                  description: |
                    An ObjectId specifies an object identifier (OID). These provide context and describe types in ASN.1 messages.
                  required: true
                  item_type:
                    type: Integer
          - name: 'aiaOcspServers'
            type: Array
            description: |
              Describes Online Certificate Status Protocol (OCSP) endpoint addresses that appear in the
              "Authority Information Access" extension in the certificate.
            item_type:
              type: String
          - name: 'caOptions'
            type: NestedObject
            description: |
              Describes values that are relevant in a CA certificate.
            required: true
            properties:
              - name: 'isCa'
                type: Boolean
                description: |
                  When true, the "CA" in Basic Constraints extension will be set to true.
              - name: 'nonCa'
                type: Boolean
                description: |
                  When true, the "CA" in Basic Constraints extension will be set to false.
                  If both `is_ca` and `non_ca` are unset, the extension will be omitted from the CA certificate.
                url_param_only: true
              - name: 'maxIssuerPathLength'
                type: Integer
                description: |
                  Refers to the "path length constraint" in Basic Constraints extension. For a CA certificate, this value describes the depth of
                  subordinate CA certificates that are allowed. If this value is less than 0, the request will fail.
              - name: 'zeroMaxIssuerPathLength'
                type: Boolean
                description: |
                  When true, the "path length constraint" in Basic Constraints extension will be set to 0.
                  if both `max_issuer_path_length` and `zero_max_issuer_path_length` are unset,
                  the max path length will be omitted from the CA certificate.
                url_param_only: true
          - name: 'keyUsage'
            type: NestedObject
            description: |
              Indicates the intended use for keys that correspond to a certificate.
            required: true
            properties:
              - name: 'baseKeyUsage'
                type: NestedObject
                description: |
                  Describes high-level ways in which a key may be used.
                required: true
                properties:
                  - name: 'digitalSignature'
                    type: Boolean
                    description: |
                      The key may be used for digital signatures.
                  - name: 'contentCommitment'
                    type: Boolean
                    description: |
                      The key may be used for cryptographic commitments. Note that this may also be referred to as "non-repudiation".
                  - name: 'keyEncipherment'
                    type: Boolean
                    description: |
                      The key may be used to encipher other keys.
                  - name: 'dataEncipherment'
                    type: Boolean
                    description: |
                      The key may be used to encipher data.
                  - name: 'keyAgreement'
                    type: Boolean
                    description: |
                      The key may be used in a key agreement protocol.
                  - name: 'certSign'
                    type: Boolean
                    description: |
                      The key may be used to sign certificates.
                  - name: 'crlSign'
                    type: Boolean
                    description: |
                      The key may be used sign certificate revocation lists.
                  - name: 'encipherOnly'
                    type: Boolean
                    description: |
                      The key may be used to encipher only.
                  - name: 'decipherOnly'
                    type: Boolean
                    description: |
                      The key may be used to decipher only.
              - name: 'extendedKeyUsage'
                type: NestedObject
                description: |
                  Describes high-level ways in which a key may be used.
                required: true
                properties:
                  - name: 'serverAuth'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.1. Officially described as "TLS WWW server authentication", though regularly used for non-WWW TLS.
                  - name: 'clientAuth'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.2. Officially described as "TLS WWW client authentication", though regularly used for non-WWW TLS.
                  - name: 'codeSigning'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.3. Officially described as "Signing of downloadable executable code client authentication".
                  - name: 'emailProtection'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.4. Officially described as "Email protection".
                  - name: 'timeStamping'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.8. Officially described as "Binding the hash of an object to a time".
                  - name: 'ocspSigning'
                    type: Boolean
                    description: |
                      Corresponds to OID 1.3.6.1.5.5.7.3.9. Officially described as "Signing OCSP responses".
              - name: 'unknownExtendedKeyUsages'
                type: Array
                description: |
                  An ObjectId specifies an object identifier (OID). These provide context and describe types in ASN.1 messages.
                item_type:
                  type: NestedObject
                  properties:
                    - name: 'objectIdPath'
                      type: Array
                      description: |
                        An ObjectId specifies an object identifier (OID). These provide context and describe types in ASN.1 messages.
                      required: true
                      item_type:
                        type: Integer
          - name: 'nameConstraints'
            type: NestedObject
            description: |
              Describes the X.509 name constraints extension.
            properties:
              - name: 'critical'
                type: Boolean
                description:
                  Indicates whether or not the name constraints are marked
                  critical.
                required: true
              - name: 'permittedDnsNames'
                type: Array
                description: |
                  Contains permitted DNS names. Any DNS name that can be
                  constructed by simply adding zero or more labels to
                  the left-hand side of the name satisfies the name constraint.
                  For example, `example.com`, `www.example.com`, `www.sub.example.com`
                  would satisfy `example.com` while `example1.com` does not.
                item_type:
                  type: String
              - name: 'excludedDnsNames'
                type: Array
                description: |
                  Contains excluded DNS names. Any DNS name that can be
                  constructed by simply adding zero or more labels to
                  the left-hand side of the name satisfies the name constraint.
                  For example, `example.com`, `www.example.com`, `www.sub.example.com`
                  would satisfy `example.com` while `example1.com` does not.
                item_type:
                  type: String
              - name: 'permittedIpRanges'
                type: Array
                description: |
                  Contains the permitted IP ranges. For IPv4 addresses, the ranges
                  are expressed using CIDR notation as specified in RFC 4632.
                  For IPv6 addresses, the ranges are expressed in similar encoding as IPv4
                  addresses.
                item_type:
                  type: String
              - name: 'excludedIpRanges'
                type: Array
                description: |
                  Contains the excluded IP ranges. For IPv4 addresses, the ranges
                  are expressed using CIDR notation as specified in RFC 4632.
                  For IPv6 addresses, the ranges are expressed in similar encoding as IPv4
                  addresses.
                item_type:
                  type: String
              - name: 'permittedEmailAddresses'
                type: Array
                description: |
                  Contains the permitted email addresses. The value can be a particular
                  email address, a hostname to indicate all email addresses on that host or
                  a domain with a leading period (e.g. `.example.com`) to indicate
                  all email addresses in that domain.
                item_type:
                  type: String
              - name: 'excludedEmailAddresses'
                type: Array
                description: |
                  Contains the excluded email addresses. The value can be a particular
                  email address, a hostname to indicate all email addresses on that host or
                  a domain with a leading period (e.g. `.example.com`) to indicate
                  all email addresses in that domain.
                item_type:
                  type: String
              - name: 'permittedUris'
                type: Array
                description: |
                  Contains the permitted URIs that apply to the host part of the name.
                  The value can be a hostname or a domain with a
                  leading period (like `.example.com`)
                item_type:
                  type: String
              - name: 'excludedUris'
                type: Array
                description: |
                  Contains the excluded URIs that apply to the host part of the name.
                  The value can be a hostname or a domain with a
                  leading period (like `.example.com`)
                item_type:
                  type: String
  - name: 'publishingOptions'
    type: NestedObject
    description: |
      The PublishingOptions to follow when issuing Certificates from any CertificateAuthority in this CaPool.
    diff_suppress_func: 'tpgresource.EmptyOrUnsetBlockDiffSuppress'
    properties:
      - name: 'publishCaCert'
        type: Boolean
        description: |
          When true, publishes each CertificateAuthority's CA certificate and includes its URL in the "Authority Information Access"
          X.509 extension in all issued Certificates. If this is false, the CA certificate will not be published and the corresponding
          X.509 extension will not be written in issued certificates.
        required: true
      - name: 'publishCrl'
        type: Boolean
        description: |
          When true, publishes each CertificateAuthority's CRL and includes its URL in the "CRL Distribution Points" X.509 extension
          in all issued Certificates. If this is false, CRLs will not be published and the corresponding X.509 extension will not
          be written in issued certificates. CRLs will expire 7 days from their creation. However, we will rebuild daily. CRLs are
          also rebuilt shortly after a certificate is revoked.
        required: true
      - name: 'encodingFormat'
        type: Enum
        description: |
          Specifies the encoding format of each CertificateAuthority's CA
          certificate and CRLs. If this is omitted, CA certificates and CRLs
          will be published in PEM.
        enum_values:
          - 'PEM'
          - 'DER'
  - name: 'labels'
    type: KeyValueLabels
    description: |
      Labels with user-defined metadata.

      An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass":
      "1.3kg", "count": "3" }.