Contract Go

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:

• Hyper Protect Virtual Servers (HPVS) - Secure virtual servers on IBM Cloud
• Hyper Protect Container Runtime (HPCR) for RedHat Virtualization (RHVS)
• Hyper Protect Confidential Container (HPCC) for Red Hat OpenShift Peer Pods

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 Hyper Protect Virtual Servers
• IBM Hyper Protect Confidential Container for Red Hat OpenShift

Features

• Attestation Management

  • Decrypt encrypted attestation records

• Certificate Operations

  • Download HPVS 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, and docker compose / podman play archives
  • Create encrypted and signed contracts
  • Support contract expiry with CSR (Certificate Signing Request)
  • Validate contract schemas

• Archive Management

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

• Image Selection

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

• Network Validation

  • Validate network-config schemas for on-premise deployments
  • Support HPVS, HPCR RHVS, and HPCC Peer Pod 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
`

    // Generate signed and encrypted contract
    signedContract, inputHash, outputHash, err := contract.HpcrContractSignedEncrypted(
        contractYAML,
        "hpvs",              // Hyper Protect OS type
        "",                  // 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
HPVS	Hyper Protect Virtual Servers	Supported
HPCR-RHVS	Hyper Protect Container Runtime for Red Hat Virtualization	Supported
HPCC-PeerPod	Hyper Protect Confidential Container Peer Pods	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 HPVS and HPCR RHVS
hyper-protect-virtual-server-samples	HPVS 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