Contract Go

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

A Go library for automating the provisioning and management of IBM Hyper Protect confidential computing workloads.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Documentation
• Supported Platforms
• Examples
• Related Projects
• Contributing
• License
• Support

Overview

The contract-go library automates the provisioning of IBM Hyper Protect confidential computing solutions:

• IBM Confidential Computing Container Runtime (CCCR) - Secure virtual servers on IBM Cloud
• IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions (CCCRV)
• IBM Confidential Computing Containers for Red Hat OpenShift Container Platform (HPCC)

This library provides cryptographic operations, contract generation, validation, and management capabilities for deploying workloads in secure enclaves on IBM LinuxONE.

What are Hyper Protect Services?

IBM Hyper Protect services provide confidential computing capabilities that protect data in use by leveraging Secure Execution feature of Z.

Learn more:

• Confidential computing with LinuxONE
• IBM Confidential Computing Container Runtime (CCCR)
• IBM Confidential Computing Containers for Red Hat OpenShift Container Platform

Features

• Attestation Management

  • Decrypt encrypted attestation records

• Certificate Operations

  • Download CCCR encryption certificates from IBM Cloud
  • Extract specific encryption certificates by version
  • Validate expiry of encryption certificate

• Contract Generation

  • Generate Base64-encoded data from text, JSON, initdata annotation and docker compose / podman play archives
  • Create encrypted and signed contracts
  • Support contract expiry with CSR (Certificate Signing Request)
  • Validate contract schemas
  • Decrypt encrypted text in Hyper Protect format

• Archive Management

  • Generate Base64 tar archives of docker-compose.yaml or pods.yaml
  • Support encrypted base64 tar generation

• Image Selection

  • Retrieve latest CCCR image details from IBM Cloud API
  • Filter images by semantic versioning

• Network Validation

  • Validate network-config schemas for on-premise deployments
  • Support CCCR, CCCRV, and IBM Confidential Computing Containers for Red Hat OpenShift Container Platform configurations

Installation

go get github.com/ibm-hyper-protect/contract-go/v2

Prerequisites

• Go 1.24.7 or later
• OpenSSL - Required for encryption operations
  • On Linux: apt-get install openssl or yum install openssl
  • On macOS: brew install openssl
  • On Windows: Download OpenSSL

Optional: Custom OpenSSL Path

If OpenSSL is not in your system PATH, set 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 Signed and Encrypted Contract

package main

import (
    "fmt"
    "log"

    "github.com/ibm-hyper-protect/contract-go/v2/contract"
)

func main() {
    // Your contract YAML
    contractYAML := `
env: |
  type: env
  logging:
    logRouter:
      hostname: 5c2d6b69-c7f0-41bd-b69b-240695369d6e.ingress.us-south.logs.cloud.ibm.com
      iamApiKey: ab00e3c09p1d4ff7fff9f04c12183413
workload: |
  type: workload
  compose:
    archive: your-archive
attestationPublicKey: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUF4cklNT3RvSktWRTZQbGhvVlJ1dgorb3YxaW1jOEZRZUdQZ3VoVFBpQUFrNDVqRStJSnVKTHZtVHFkOE8yVlZwT05iZEhiN3ZpWGEydUwxeFBOcUp2ClVpVmZNTDUyN1B4V25TU3drcitKNDYwamZvZCtaMkJOQ0k1eVV6dVYxQVhvNHV3YmVLVzNYbVM2b2FIT1YrNmsKU1YwWCt3cFE5a3J5QnJ2NWVJc2tsSTBtS3JnaXBOc2N4b3hvNG4rRDlPMWRDVU5XRzZ4MmlpVnVLeXp4VzZZTgordW9wNHZxb3VMM2pGQ1crVkRGVHgycGViNzNqL2V6WnRUVVhEbStPZTc1V21zVkxjUUg4RXZYbVFsRVAvbEduCnZZMWQ1RXI1ZjlBSU5yOEdRWjM1OHNrWENvdCtseDZiMmQveTZwWEFOTFpBR2ZoRmZLSUMxSVdHOTQrRVdqMG4KUFB6Y1NpeHhHUk53bHZjV3BDY3hKTHFEb1VCaDF0NVA4OGJTVVJUVnpuZUVydDVYbUtjRVdDd3JsSGRrSWdGYgp1azFpbWlEOHl4S2RtZmNKdzZzRm5NeDlTb3FxSFFqNk9FUFZrV3E3Y1VYQUVMN05PSzlWTnZzZUxlNnEwRkRVClNLOSt5Ty9PdEdtSEFMcFJtY2dzNGlKOVJmRTlZQUt0a1JQRlRETUdYR0lFUGdnQkIyMHRlblk0ZTRyaXE1UWgKYWp1Y2txd3psRkhjbEZLWk9jMXNMR3NCRmhHSERIZm1taWNnWkhBdVN5YVpaM29QM3czbmhNK2IwT2grSjFSMwpWQUVWWUlDMzArVUZVR1dyTU40Q3ZDLzZaVk5YVkZ4ZkZMcU8raGFnNnI4Q3VqVEtLQ3NiaE5kaVNoNlRvdWhUCjZNY2N3OVg2bkpPdFBhK0E3L0ZVV3BVQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo=
`

    // Generate signed and encrypted contract
    signedContract, inputHash, outputHash, err := contract.HpcrContractSignedEncrypted(
        contractYAML,
        "hpvs",              // Hyper Protect OS type (CCCR)
        "",                  // Use default encryption certificate
        privateKey,          // Your RSA private key
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Signed Contract: %s\n", signedContract)
    fmt.Printf("Input SHA256: %s\n", inputHash)
    fmt.Printf("Output SHA256: %s\n", outputHash)
}

Select Latest HPCR Image

package main

import (
    "fmt"
    "log"

    "github.com/ibm-hyper-protect/contract-go/v2/image"
)

func main() {
    // Image JSON from IBM Cloud
    imageJSON := `[...]` // Your IBM Cloud images JSON

    // Get latest image matching version constraint
    imageID, imageName, checksum, version, err := image.HpcrSelectImage(
        imageJSON,
        ">=1.1.0", // Optional version constraint
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Image ID: %s\n", imageID)
    fmt.Printf("Image Name: %s\n", imageName)
    fmt.Printf("Checksum: %s\n", checksum)
    fmt.Printf("Version: %s\n", version)
}

Documentation

Comprehensive documentation is available at:

• User Documentation - Detailed API reference and usage examples
• Go Package Documentation - Generated Go docs
• Examples - Sample contracts and configurations

Supported Platforms

Platform	Description	Support Status
CCCR	IBM Confidential Computing Container Runtime	Supported
CCCRV	IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions	Supported
IBM Confidential Computing Containers for Red Hat OpenShift Container Platform (Peer Pods)	IBM Confidential Computing Containers for Red Hat OpenShift Container Platform	Supported

Examples

The samples/ directory contains example configurations:

• Simple Contract
• Workload Configuration
• Network Configuration
• Docker Compose

Related Projects

This library is used by several tools in the IBM Hyper Protect ecosystem:

Project	Description
contract-cli	CLI tool for generating Hyper Protect contracts
terraform-provider-hpcr	Terraform provider for Hyper Protect contracts
k8s-operator-hpcr	Kubernetes operator for contract management
linuxone-vsi-automation-samples	Terraform examples for CCCR and CCCRV
hyper-protect-virtual-server-samples	CCCR feature samples and scripts

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• Opening issues
• Submitting pull requests
• Code style and conventions
• Testing requirements

Please also read our Code of Conduct before contributing.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

Reporting Issues

We use GitHub issue templates to help us understand and address your concerns efficiently:

• Report a Bug - Found a bug? Let us know!
• Request a Feature - Have an idea for improvement?
• Ask a Question - Need help using the library?

Security

• Security Vulnerabilities: Report via GitHub Security Advisories - DO NOT create public issues
• See our complete Security Policy for details

Community

• Discussions - General questions and community discussion
• Documentation - Comprehensive API documentation
• Maintainers - Current maintainer list and contact info

Contributors