Harbor CLI Encryption Guide

This document provides an overview of how Harbor CLI encrypts sensitive data and offers recommendations for different runtime environments. While the Harbor CLI configuration file manages your credentials, passwords themselves are never stored in plain text. Instead, they are secured using the AES-GCM encryption described below. For details on how to configure and manage these credentials, please refer to the Harbor CLI Config Management documentation.

Overview of Encryption

Harbor CLI secures credentials using AES-GCM encryption. An encryption key is automatically generated and stored in one of several keyring backends, depending on your environment:

1. Environment-based Keyring
2. System Keyring
3. File-based Keyring (Fallback)

How It Works

1. Key Retrieval
   The CLI checks if an encryption key already exists.
   If not present, Harbor CLI generates a new 32-byte key.
2. Encrypt
   Harbor CLI uses AES-GCM to encrypt credentials with a random nonce.
   The CLI stores ciphertext as a Base64-encoded string.
3. Decrypt
   Harbor CLI decodes and decrypts the stored ciphertext whenever credentials are needed.

Recommended Backends

Desktop Environments

Use the system keyring if available. This is the most secure method, as most desktop operating systems keep secrets confidentially within their native keyring service.

Docker, Kubernetes or CI/CD Environments

Use the environment-based keyring in production. System keyrings typically aren’t available in containerized environments. Supplying encryption keys as environment variables or secrets is straightforward. In the following subsections we summarize a few examples how to inject the encryption key as environment variables and how to store the secret securely for production environments.

Example: Running Harbor CLI in Docker

Use a randomly generated key as an environment variable. This can be generated by tool such as openssl:

docker run -it --rm \
  -e HARBOR_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  registry.goharbor.io/harbor-cli/harbor-cli \
  login https://demo.goharbor.io -u username -p password

Example: Running Harbor CLI in Kubernetes

Use a randomly generated key / strong password and store in a kubernetes secret. Pass the secret content as an environment variable to the deployment pod:

# secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: harbor-cli-secrets
type: Opaque
data:
  HARBOR_ENCRYPTION_KEY: "<base64-encoded-key>"

# deployment.yaml
spec:
  containers:
  - name: harbor-cli
    image: registry.goharbor.io/harbor-cli/harbor-cli
    envFrom:
    - secretRef:
        name: harbor-cli-secrets

Example: CI/CD Pipeline

In case you want to use the Harbor CLI in a CI/CD workflow make sure to store your encryption key in a repository secret or similar secret vaults that are provided by your CI/CD provider. In case of GitHub or GitLab the encryption key could be stored in repository secrets and retrieved in either the github actions workflow or GitLab CI pipeline. See the following links for more info on using secrets in GitHub actions and GitLab CI.

Example: Third-Party Secret Vault

Another recommended method to store production encryption secrets are external secret vaults such as AWS Secrets Manager, GCP Secrets Manager, Azure Key Vault or HashiCorp Vault.

File-based Keyring (Fallback)

In environments where neither a system keyring nor environment-based keyring is available, Harbor CLI can store the encryption key in a file.By default, this file-based keyring is located within your XDG-compliant directory structure (e.g., ~/.local/share/harbor-cli/keyring or ~/.config/harbor-cli/keyring). The stored key is protected by file permissions set to allow only the owner to read or write the file. However, this approach is less secure and is not recommended for production.