contract-cli

Contract CLI Documentation

Note: The offering names have been changed:

Hyper Protect Virtual Servers (HPVS) → IBM Confidential Computing Container Runtime (CCCR)

Hyper Protect Container Runtime for Red Hat Virtualization (HPCR-RHVS) → IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions (CCCRV)

Hyper Protect Confidential Container (HPCC) → IBM Confidential Computing Containers for Red Hat OpenShift Container Platform

Complete command reference and usage guide for the Hyper Protect Contract CLI.

Introduction
Installation
Prerequisites
Quick Start
Command Reference
Common Workflows
Troubleshooting
Examples

Introduction

The Contract CLI automates the process of generating and managing contracts for provisioning IBM Hyper Protect services including IBM Confidential Computing Container Runtime (CCCR) for VPC, IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions (CCCRV), 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 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 CCCRV:

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

For IBM Confidential Computing Containers for Red Hat OpenShift Container Platform:

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.

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
`--out`	string	No	Path to save decrypted attestation records
`-h, --help`	-	No	Display help information

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

Using standard input:

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

download-certificate

Download encryption certificates from the IBM Hyper Protect Repository. Retrieves the latest or specific versions of CCCR 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

encrypt

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

Usage

contract-cli encrypt [flags]

Flags

Flag	Type	Required	Description
`--in`	string	Yes	Path to unencrypted contract YAML file (use ‘-‘ for standard input)
`--priv`	string	No*	Path to private key for signing
`--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 CCCRV:

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

For IBM Confidential Computing Containers for Red Hat OpenShift Container Platform:

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 Hyper Protect 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:

echo "my-secret-password" | 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 (CCCR) 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 CCCR 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 CCCR 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 CCCR 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 Hyper Protect 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 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 CCCR contract:

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

Validate CCCRV contract:

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

Validate IBM Confidential Computing Containers for Red Hat OpenShift Container Platform 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

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 Hpcc 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

# 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

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 CCCR/CCCRV 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:

Simple Contract - Basic contract structure
Contract with Expiry - Contract with expiration
Attestation Records - Example attestation files
Network Configuration - Network config examples
Docker Compose - Compose file examples
Signed & Encrypted Contract - Signed & Encrypted hpcc contract
Sample Command Reference - Example CLI commands and usage demonstrations

Additional Resources

Main README - Project overview and quick start
Contributing Guide - How to contribute
Security Policy - Security best practices
IBM Hyper Protect Documentation - Official IBM docs

Need Help?

Open an issue
Ask a question
Check the troubleshooting section above

This site is open source. Improve this page.

contract-cli

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

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

Troubleshooting

OpenSSL Not Found

Invalid Contract Schema

Certificate Version Not Found

Permission Denied

Examples

Additional Resources