Bug: 274660638

Clone this repo:
  1. 6f1099d Merge tag 'upstream/v0.2.3' into aosp/master by Dan Willemsen · 1 year, 1 month ago main master
  2. 61a4dd0 Initial empty repository by Frank Piva · 1 year, 1 month ago
  3. d0957a9 fix: Remove EnableECPLogging logic in client (#69) by Andy Zhao · 1 year, 2 months ago upstream/v0.2.3
  4. e26f9fc chore: Add Linter step to all relevant workflows and fix lint errors. (#67) by Andy Zhao · 1 year, 2 months ago
  5. dc1cf97 feat: Add ErrCredUnavailable sentinel error (#65) by Andy Zhao · 1 year, 2 months ago upstream/v0.2.2

Google Proxies for Enterprise Certificates (Preview)

Certificate-based-access

If you use certificate-based access to protect your Google Cloud resources, the end user device certificate is one of the credentials that is verified before access to a resource is granted. You can configure Google Cloud to use the device certificates in your operating system key store when verifying access to a resource from the gcloud CLI or Terraform by using the enterprise certificates feature.

Google Enterprise Certificate Proxies (ECP)

Google Enterprise Certificate Proxies (ECP) are part of the Google Cloud Zero Trust architecture that enables mutual authentication with client-side certificates. This repository contains a set of proxies/modules that can be used by clients or toolings to interact with certificates that are stored in protected key storage systems.

To interact the client certificates, application code should not need to use most of these proxies within this repository directly. Instead, the application should leverage the clients and toolings provided by Google such as Cloud SDK to have a more convenient developer experience.

Compatibility

Currently ECP is in Preview stage and all the APIs and configurations are subject to change.

The following platforms/keystores are supported by ECP:

  • MacOS: Keychain
  • Linux: PKCS#11
  • Windows: MY

Prerequisites

Before using ECP with your application/client, you should follow the instructions here to configure your enterprise certificate policies with Access Context Manager.

Quick Start

  1. Install gcloud CLI (Cloud SDK) at: https://cloud.google.com/sdk/docs/install.

    1. Note: gcloud version 416.0 or newer is required.
  2. $ gcloud components install enterprise-certificate-proxy.

  3. MacOS ONLY

    1. $ gcloud config virtualenv create

    2. $ gcloud config virtualenv enable

  4. Create a new JSON file at ~/.config/gcloud/certificate_config.json:

    • Alternatively you can put the JSON in the location of your choice and set the path to it using:

      $ gcloud config set context_aware/enterprise_certificate_config_file_path "<json file path>".

    • Another approach for setting the JSON file location is setting the location with the GOOGLE_API_CERTIFICATE_CONFIG environment variable.

  5. Update the certificate_config.json file with details about the certificate (See Configuration section for details.)

  6. Enable usage of client certificates through gcloud CLI config command:

    gcloud config set context_aware/use_client_certificate true
    
  7. You can now use gcloud to access GCP resources with mTLS.

Certificate Configuration

ECP relies on the certificate_config.json file to read all the metadata information for locating the certificate. The contents of this JSON file look like the following:

MacOS (Keychain)

{
  "cert_configs": {
    "macos_keychain": {
      "issuer": "YOUR_CERT_ISSUER"
    }
  },
  "libs": {
      "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp",
      "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.dylib",
      "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.dylib"
  },
  "version": 1
}

Windows (MyStore)

{
  "cert_configs": {
    "windows_store": {
      "store": "MY",
      "provider": "current_user",
      "issuer": "YOUR_CERT_ISSUER"
    }
  },
  "libs": {
      "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp.exe",
      "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.dll",
      "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.dll"
  },
  "version": 1
}

Linux (PKCS#11)

{
  "cert_configs": {
    "pkcs11": {
      "label": "YOUR_TOKEN_LABEL",
      "user_pin": "YOUR_PIN",
      "slot": "YOUR_SLOT",
      "module": "The PKCS #11 module library file path"
    }
  },
  "libs": {
      "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp",
      "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.so",
      "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.so"
  },
  "version": 1
}

Logging

To enable logging set the “ENABLE_ENTERPRISE_CERTIFICATE_LOGS” environment variable.

Example

export ENABLE_ENTERPRISE_CERTIFICATE_LOGS=1 # Now the
enterprise-certificate-proxy will output logs to stdout.

Build binaries

For amd64 MacOS, run ./build/scripts/darwin_amd64.sh. The binaries will be placed in build/bin/darwin_amd64 folder.

For amd64 Linux, run ./build/scripts/linux_amd64.sh. The binaries will be placed in build/bin/linux_amd64 folder.

For amd64 Windows, in powershell terminal, run .\build\scripts\windows_amd64.ps1. The binaries will be placed in build\bin\windows_amd64 folder. Note that gcc is required for compiling the Windows shared library. The easiest way to get gcc on Windows is to download Mingw64, and add “gcc.exe” to the powershell path.

Contributing

Contributions to this library are always welcome and highly encouraged. See the CONTRIBUTING documentation for more information on how to get started.

License

Apache - See LICENSE for more information.