Contract CLI Documentation

Complete command reference and usage guide for the IBM Confidential Computing Contract CLI.

Introduction
Installation
Prerequisites
Quick Start
Command Reference
Common Workflows
CI/CD Integration
Exit Codes
Troubleshooting
Examples

Introduction

The Contract CLI automates the process of generating and managing contracts for provisioning IBM Confidential Computing services including IBM Confidential Computing Container Runtime, IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions, and IBM Confidential Computing Containers for Red Hat OpenShift Container Platform. It provides a comprehensive set of commands for:

Generating signed and encrypted contracts
Managing encryption certificates
Validating contracts and network configurations
Handling attestation records
Working with container configurations

Installation

Download the latest release for your platform from the releases page.

Available Platforms

Linux: amd64, arm64, s390x, ppc64le
macOS: amd64 (Intel), arm64 (Apple Silicon)
Windows: amd64, arm64

Verify Installation

# Check version
contract-cli --version

# View available commands
contract-cli --help

Prerequisites

OpenSSL

OpenSSL is required for all cryptographic operations. The CLI will use the openssl binary from your system PATH.

Installation:

Linux: apt-get install openssl or yum install openssl
macOS: brew install openssl
Windows: Download OpenSSL

Custom OpenSSL Path (Optional)

If OpenSSL is not in your system PATH, configure the OPENSSL_BIN environment variable:

Linux/macOS:

export OPENSSL_BIN=/usr/bin/openssl

Windows (PowerShell):

$env:OPENSSL_BIN="C:\Program Files\OpenSSL-Win64\bin\openssl.exe"

Quick Start

Generate a Complete Contract

# 1. Generate RSA key pair
openssl genrsa -out private.pem 4096

# 2. Create your contract YAML
cat > contract.yaml <<EOF
env: |
  type: env
  logging:
    logRouter:
      hostname: example.logs.cloud.ibm.com
      iamApiKey: your-api-key
workload: |
  type: workload
  compose:
    archive: your-archive
EOF 

# 3. Validate the contract
contract-cli validate-contract --in contract.yaml --os hpvs

# 4. Generate signed and encrypted contract
contract-cli encrypt --in contract.yaml --priv private.pem --out encrypted-contract.yaml

Command Reference

base64

Encode text or JSON data to Base64 format. Useful for encoding data that needs to be included in contracts or configurations.

Usage

contract-cli base64 [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Input data to encode (text or JSON) (use '-' for standard input)
`--format`	string	No	Input data format (text or json)
`--out`	string	No	Path to save Base64 encoded output
`-h, --help`	-	No	Display help information

Examples

Basic text encoding:

contract-cli base64 --in "Hello World" --format text

JSON encoding:

contract-cli base64 --in '{"type": "workload"}' --format json

Save to file:

contract-cli base64 --in "Hello World" --format text --out encoded.txt

Using standard input (pipe input):

echo "Hello World" | contract-cli base64 --in - --format text

base64-tgz

Generate Base64-encoded tar.gz archive of docker-compose.yaml or pods.yaml. Creates a compressed archive of your container configuration files, encoded as Base64 for inclusion in Hyper Protect contracts. Supports both plain and encrypted output.

Usage

contract-cli base64-tgz [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to folder containing `docker-compose.yaml` or `pods.yaml` (use '-' for standard input)
`--output`	string	No	Output type: `plain` or `encrypted` (default: `plain`)
`--cert`	string	No	Path to encryption certificate (for encrypted output)
`--os`	string	No	Target Hyper Protect platform: `hpvs`, `hpcr-rhvs`, or `hpcc-peerpod` (default: `hpvs`)
`--out`	string	No	Path to save the output
`-h, --help`	-	No	Display help information

Examples

Plain Base64 archive:

contract-cli base64-tgz --in ./compose-folder

Encrypted archive with latest certificate:

contract-cli base64-tgz --in ./compose-folder --output encrypted

Encrypted archive with custom certificate:

contract-cli base64-tgz \
  --in ./compose-folder \
  --output encrypted \
  --cert encryption.crt

For HPCR-RHVS:

contract-cli base64-tgz \
  --in ./pods-folder \
  --output encrypted \
  --os hpcr-rhvs

For HPCC Peer Pods:

contract-cli base64-tgz \
  --in ./pods-folder \
  --output encrypted \
  --os hpcc-peerpod

Save to file:

contract-cli base64-tgz --in ./compose-folder --out archive.txt

Using standard input (pipe input):

echo "pods-folder" | contract-cli base64-tgz --in -

decrypt-attestation

Decrypt encrypted attestation records generated by Hyper Protect instances. Attestation records are typically found at /var/hyperprotect/se-checksums.txt.enc and contain cryptographic hashes for verifying workload integrity.

Optionally verify the signature of decrypted attestation records by providing both --signature and --attestation-cert flags together.

Usage

contract-cli decrypt-attestation [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to encrypted attestation file (use '-' for standard input)
`--priv`	string	Yes	Path to private key used for decryption
`--password`	string	No	Password for encrypted private key
`--out`	string	No	Path to save decrypted attestation records
`--signature`	string	No*	Path to signature file (se-signature.bin)
`--attestation-cert`	string	No*	Path to IBM attestation certificate file (PEM format)
`-h, --help`	-	No	Display help information

* Both --signature and --attestation-cert must be provided together if signature verification is desired

Examples

Decrypt to console:

contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem

Decrypt and save to file:

contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem \
  --out decrypted-attestation.txt

Decrypt and verify signature:

contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem \
  --signature se-signature.bin \
  --attestation-cert hpse-attestation.crt

Decrypt, verify signature, and save to file:

contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem \
  --out decrypted-attestation.txt \
  --signature se-signature.bin \
  --attestation-cert hpse-attestation.crt

Using standard input:

cat se-checksums.txt.enc | contract-cli decrypt-attestation \
  --in - \
  --priv private.pem

Using password-protected private key:

contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private-encrypted.pem \
  --password "your-secure-password" \
  --out decrypted-attestation.txt

Using password from environment variable:

export PRIVATE_KEY_PASSWORD="your-secure-password"
contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private-encrypted.pem \
  --password "$PRIVATE_KEY_PASSWORD" \
  --out decrypted-attestation.txt

download-certificate

Download encryption certificates from the IBM Hyper Protect Repository. Retrieves the latest or specific versions of HPCR encryption certificates required for contract encryption and workload deployment.

Usage

contract-cli download-certificate [flags]

Flags

Flag	Type	Required	Description
`--version`	strings	Yes	Specific certificate versions to download (comma-separated, e.g., 1.0.21,1.0.22)
`--format`	string	No	Output format for data (json, yaml, or text)
`--out`	string	No	Path to save downloaded encryption certificates
`-h, --help`	-	No	Display help information

Examples

Download latest certificate:

contract-cli download-certificate

Download specific version:

contract-cli download-certificate --version 1.0.23

Download multiple versions:

contract-cli download-certificate --version 1.0.21,1.0.22,1.0.23

Save to file in YAML format:

contract-cli download-certificate \
  --version 1.0.23 \
  --format yaml \
  --out certificates.yaml

sign-contract

Generates a signed contract from a contract with encrypted workload and env sections.

Usage

contract-cli sign-contract [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to encrypted IBM Confidential Computing contract YAML file (use '-' for standard input)
`--priv`	string	Yes	Path to private key for signing
`--password`	string	No	Password for encrypted private key
`--out`	string	No	Path to save signed and encrypted contract
`-h, --help`	-	No	Display help information

Examples

Sign a contract:

contract-cli sign-contract --in contract.yaml --priv private.pem

Sign and save to file:

contract-cli sign-contract --in contract.yaml --priv private.pem --out signed-contract.yaml

Using standard input:

cat contract.yaml | contract-cli sign-contract --in - --priv private.pem

Using password-protected private key:

contract-cli sign-contract \
  --in contract.yaml \
  --priv private-encrypted.pem \
  --password "your-secure-password" \
  --out signed-contract.yaml

encrypt

Generate a signed and encrypted contract for IBM Confidential Computing deployment. Supports optional contract expiry for enhanced security.

Usage

contract-cli encrypt [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to unencrypted IBM Confidential Computing contract YAML file (use '-' for standard input)
`--priv`	string	No*	Path to private key for signing
`--password`	string	No	Password for encrypted private key
`--cert`	string	No	Path to encryption certificate (uses latest if not specified)
`--os`	string	No	Target Hyper Protect platform: `hpvs`, `hpcr-rhvs`, or `hpcc-peerpod` (default: `hpvs`)
`--out`	string	No	Path to save signed and encrypted contract
`--contract-expiry`	bool	No	Enable contract expiry feature
`--cacert`	string	No**	Path to CA certificate (required with expiry)
`--cakey`	string	No**	Path to CA key (required with expiry)
`--csr`	string	No**	Path to CSR file (required with expiry)
`--csrParam`	string	No**	Path to CSR parameters JSON
`--expiry`	int	No**	Contract validity in days (required with expiry)
`-h, --help`	-	No	Display help information

* Generated automatically if not provided ** Required when --contract-expiry is enabled

Examples

Basic encryption:

contract-cli encrypt --in contract.yaml --priv private.pem

With custom certificate:

contract-cli encrypt \
  --in contract.yaml \
  --priv private.pem \
  --cert encryption.crt

Save to file:

contract-cli encrypt \
  --in contract.yaml \
  --priv private.pem \
  --out encrypted-contract.yaml

With contract expiry:

contract-cli encrypt \
  --contract-expiry \
  --in contract.yaml \
  --priv private.pem \
  --cacert ca.crt \
  --cakey ca.key \
  --csr csr.pem \
  --expiry 90

For HPCR-RHVS:

contract-cli encrypt \
  --in contract.yaml \
  --priv private.pem \
  --os hpcr-rhvs

Using password-protected private key:

contract-cli encrypt \
  --in contract.yaml \
  --priv private-encrypted.pem \
  --password "your-secure-password" \
  --out encrypted-contract.yaml

For HPCC Peer Pods:

contract-cli encrypt \
  --in contract.yaml \
  --priv private.pem \
  --os hpcc-peerpod

Using standard input:

echo "test-string" | contract-cli encrypt \
  --in - \
  --priv private.pem

encrypt-string

Encrypt strings using the IBM Confidential Computing encryption format. Output format: hyper-protect-basic.<encrypted-password>.<encrypted-string>. Use this to encrypt sensitive data like passwords or API keys for contracts.

Usage

contract-cli encrypt-string [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	String data to encrypt (use '-' for standard input)
`--format`	string	No	Input data format (text or json)
`--cert`	string	No	Path to encryption certificate (uses latest if not specified)
`--os`	string	No	Target Hyper Protect platform: `hpvs`, `hpcr-rhvs`, or `hpcc-peerpod` (default: `hpvs`)
`--out`	string	No	Path to save encrypted output
`-h, --help`	-	No	Display help information

Examples

Encrypt plain text:

contract-cli encrypt-string --in "my-secret-password"

Encrypt JSON:

contract-cli encrypt-string \
  --in '{"apiKey": "secret123"}' \
  --format json

With custom certificate:

contract-cli encrypt-string \
  --in "my-secret" \
  --cert encryption.crt

Save to file:

contract-cli encrypt-string \
  --in "my-secret" \
  --out encrypted-secret.txt

Using standard input:

# Encrypt echo statement
echo "my-secret-password" | contract-cli encrypt-string --in -

# Encrypt file content
cat workload.yaml | contract-cli encrypt-string --in -

get-certificate

Extract a specific encryption certificate version from download-certificate output. Parses the JSON output from download-certificate and extracts the certificate for the specified version.

Usage

contract-cli get-certificate [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to download-certificate JSON output (use '-' for standard input)
`--version`	string	Yes	Certificate version to extract (e.g., 1.0.23)
`--out`	string	No	Path to save extracted encryption certificate
`-h, --help`	-	No	Display help information

Examples

Extract specific version:

contract-cli get-certificate \
  --in certificates.json \
  --version 1.0.23

Save to file:

contract-cli get-certificate \
  --in certificates.json \
  --version 1.0.23 \
  --out cert-1.0.23.crt

Using standard input:

cat "cert.json" | contract-cli get-certificate --in - --version 1.0.23

image

Retrieve IBM Confidential Computing Container Runtime image details from IBM Cloud. Parses image information from IBM Cloud API, CLI, or Terraform output to extract image ID, name, checksum, and version. Supports filtering by specific version.

Usage

contract-cli image [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to IBM Cloud images JSON (from API, CLI, or Terraform) (use '-' for standard input)
`--version`	string	No	Specific HPCR version to retrieve (returns latest if not specified)
`--format`	string	No	Output format for data (json, yaml, or text)
`--out`	string	No	Path to save HPCR image details
`-h, --help`	-	No	Display help information

Examples

Get latest image:

contract-cli image --in ibm-cloud-images.json

Get specific version:

contract-cli image \
  --in ibm-cloud-images.json \
  --version "1.0.23"

Output in YAML:

contract-cli image \
  --in ibm-cloud-images.json \
  --format yaml

Save to file:

contract-cli image \
  --in ibm-cloud-images.json \
  --out hpcr-image.json

Using standard input:

cat "ibm-cloud-images.json" | contract-cli image --in -

validate-contract

Validate an unencrypted contract against the IBM Confidential Computing schema. Checks contract structure, required fields, and data types before encryption to help catch errors early in the development process.

Usage

contract-cli validate-contract [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to unencrypted IBM Confidential Computing contract YAML file (use '-' for standard input)
`--os`	string	No	Target Hyper Protect platform: `hpvs`, `hpcr-rhvs`, or `hpcc-peerpod` (default: `hpvs`)
`-h, --help`	-	No	Display help information

Examples

Validate HPVS contract:

contract-cli validate-contract --in contract.yaml --os hpvs

Validate HPCR-RHVS contract:

contract-cli validate-contract --in contract.yaml --os hpcr-rhvs

Validate HPCC Peer Pods contract:

contract-cli validate-contract --in contract.yaml --os hpcc-peerpod

Using standard input:

cat contract.yaml | contract-cli validate-contract --in - --os hpvs

validate-network

Validate network-config YAML file against the schema. Validates network configuration for on-premise deployments, ensuring all required fields are present and properly formatted.

Usage

contract-cli validate-network [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to network-config YAML file (use '-' for standard input)
`-h, --help`	-	No	Display help information

Examples

Validate network configuration:

contract-cli validate-network --in network-config.yaml

Using standard input:

cat network-config.yaml | contract-cli validate-network --in -

validate-encryption-certificate

Validates encryption certificate for on-premise, VPC deployment. It will check encryption certificate validity, ensuring all required fields are present and properly formatted.

Usage

contract-cli validate-encryption-certificate [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to encryption certificate file (use '-' for standard input)
`-h, --help`	-	No	Display help information

Examples

Validate encryption certificate configuration:

contract-cli validate-encryption-certificate --in encryption-cert.crt

Using standard input:

cat encryption-cert.crt | contract-cli validate-encryption-certificate --in -

initdata

Create initdata annotation from signed and encrypted contract for IBM Confidential Computing Containers for Red Hat OpenShift Container Platform (Peer Pod) solution.

Usage

contract-cli initdata [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to signed & encrypted contract YAML file (use '-' for standard input)
`--out`	string	No	Path to store gzipped & encoded initdata value
`-h, --help`	-	No	Display help information

Examples

Create initdata from signed & encrypted contract:

contract-cli initdata --in signed_encrypted_contract.yaml

Using standard input:

cat signed_encrypted_contract.yaml | contract-cli initdata --in -

Common Workflows

Complete Contract Generation Workflow

# Step 1: Generate key pair
openssl genrsa -out private.pem 4096

# Step 2: Download encryption certificate
contract-cli download-certificate --version 1.0.23 --out certs.json
contract-cli get-certificate --in certs.json --version 1.0.23 --out cert.crt

# Step 3: Create docker-compose archive
contract-cli base64-tgz --in ./compose-folder --output encrypted --cert cert.crt --out archive.txt

# Step 4: Create contract YAML (with archive from step 3)
cat > contract.yaml <<EOF
env: |
  type: env
  logging:
    logRouter:
      hostname: logs.example.com
workload: |
  type: workload
  compose:
    archive: $(cat archive.txt)
EOF

# Step 5: Validate contract
contract-cli validate-contract --in contract.yaml --os hpvs

# Step 6: Generate signed and encrypted contract
contract-cli encrypt --in contract.yaml --priv private.pem --cert cert.crt --out final-contract.yaml

Working with Attestation Records

# Decrypt attestation from running instance
contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem \
  --out attestation.txt

# Decrypt and verify signature
contract-cli decrypt-attestation \
  --in se-checksums.txt.enc \
  --priv private.pem \
  --signature se-signature.bin \
  --attestation-cert hpse-attestation.crt \
  --out attestation.txt

# View decrypted attestation
cat attestation.txt

Certificate Management

# Download all available certificates
contract-cli download-certificate --out all-certs.json

# Extract specific version
contract-cli get-certificate \
  --in all-certs.json \
  --version 1.0.23 \
  --out cert-1.0.23.crt

CI/CD Integration

The CLI supports stdin input (--in -) for all commands, making it easy to integrate into CI/CD pipelines.

GitHub Actions Example

name: Generate Contract
on:
  push:
    branches: [main]

jobs:
  generate-contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download contract-cli
        run: |
          curl -sL https://github.com/ibm-hyper-protect/contract-cli/releases/latest/download/contract-cli-linux-amd64 -o contract-cli
          chmod +x contract-cli

      - name: Validate contract
        run: ./contract-cli validate-contract --in contract.yaml --os hpvs

      - name: Generate signed and encrypted contract
        run: |
          ./contract-cli encrypt \
            --in contract.yaml \
            --priv "${{ secrets.PRIVATE_KEY_PATH }}" \
            --out encrypted-contract.yaml

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: encrypted-contract
          path: encrypted-contract.yaml

Shell Script Pattern

#!/bin/bash
set -euo pipefail

# Validate → Encrypt → Deploy pattern
if ! contract-cli validate-contract --in contract.yaml --os hpvs; then
  echo "Contract validation failed" >&2
  exit 1
fi

contract-cli encrypt \
  --in contract.yaml \
  --priv private.pem \
  --out encrypted-contract.yaml

echo "Contract generated successfully"

Exit Codes

Code	Meaning
`0`	Success
`1`	General error (invalid input, missing files, encryption failure, etc.)

All error messages are written to stderr. Successful output is written to stdout (unless --out is specified).

Troubleshooting

OpenSSL Not Found

Error:

Error: openssl binary not found in PATH

Solution:

Install OpenSSL for your platform
Or set OPENSSL_BIN environment variable to the full path of OpenSSL

Invalid Contract Schema

Error:

Error: contract validation failed

Solution:

Run validate-contract to see specific schema errors
Check contract structure matches IBM Confidential Computing requirements
Ensure all required fields are present

Certificate Version Not Found

Error:

Error: certificate version not found

Solution:

Run download-certificate without --version to see available versions
Verify the version number format (e.g., 1.0.23)

Permission Denied

Error:

Error: permission denied reading file

Solution:

Check file permissions: chmod 600 private.pem
Ensure you have read access to input files
Verify output directory is writable

Examples

The samples/ directory contains working examples:

Contract - Basic contract structure
Contract with Expiry - Contract with expiration
Attestation Records - Example attestation files
Certificate Examples - Encryption certificate samples
Network Configuration - Network config examples
Docker Compose - Compose file examples
Signed & Encrypted Contract - Signed & Encrypted HPCC contract
Contract Signing - Contract signing examples

Additional Resources

Main README - Project overview and quick start
Contributing Guide - How to contribute
Security Policy - Security best practices
Changelog - Release history and version notes

IBM Confidential Computing Documentation

Related Projects

contract-go - Go library
terraform-provider-hpcr - Terraform provider
k8s-operator-hpcr - Kubernetes operator

Need Help?

Open an issue
Ask a question
Check the troubleshooting section above

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Contract CLI Documentation

Table of Contents

Introduction

Installation

Available Platforms

Verify Installation

Prerequisites

OpenSSL

Custom OpenSSL Path (Optional)

Quick Start

Generate a Complete Contract

Command Reference

base64

Usage

Flags

Examples

base64-tgz

Usage

Flags

Examples

decrypt-attestation

Usage

Flags

Examples

download-certificate

Usage

Flags

Examples

sign-contract

Usage

Flags

Examples

encrypt

Usage

Flags

Examples

encrypt-string

Usage

Flags

Examples

get-certificate

Usage

Flags

Examples

image

Usage

Flags

Examples

validate-contract

Usage

Flags

Examples

validate-network

Usage

Flags

Examples

validate-encryption-certificate

Usage

Flags

Examples

initdata

Usage

Flags

Examples

Common Workflows

Complete Contract Generation Workflow

Working with Attestation Records

Certificate Management

CI/CD Integration

GitHub Actions Example

Shell Script Pattern

Exit Codes

Troubleshooting

OpenSSL Not Found