https://github.com/ibm-hyper-protect/contract-go

Go library to work with hyper protect contracts
https://github.com/ibm-hyper-protect/contract-go
hpcc-peerpod hpcr hpcr4rhvs hpvs hyper-protect hyper-protect-services ibm
Last synced: 4 months ago
JSON representation
Go library to work with hyper protect contracts
Host: GitHub
URL: https://github.com/ibm-hyper-protect/contract-go
Owner: ibm-hyper-protect
License: apache-2.0
Created: 2023-09-28T14:11:40.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2026-02-03T10:35:51.000Z (5 months ago)
Last Synced: 2026-02-03T23:18:58.226Z (5 months ago)
Topics: hpcc-peerpod, hpcr, hpcr4rhvs, hpvs, hyper-protect, hyper-protect-services, ibm
Language: Go
Homepage:
Size: 610 KB
Stars: 1
Watchers: 2
Forks: 8
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project

README

          # Contract Go

[![contract-go CI](https://github.com/ibm-hyper-protect/contract-go/actions/workflows/build.yml/badge.svg)](https://github.com/ibm-hyper-protect/contract-go/actions/workflows/build.yml)

[![Latest Release](https://img.shields.io/github/v/release/ibm-hyper-protect/contract-go?include_prereleases)](https://github.com/ibm-hyper-protect/contract-go/releases/latest)

[![Go Report Card](https://goreportcard.com/badge/github.com/ibm-hyper-protect/contract-go)](https://goreportcard.com/report/ibm-hyper-protect/contract-go)

[![Go Reference](https://pkg.go.dev/badge/github.com/ibm-hyper-protect/contract-go.svg)](https://pkg.go.dev/github.com/ibm-hyper-protect/contract-go/v2)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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

## Table of Contents

- [Overview](#overview)

- [Features](#features)

- [Installation](#installation)

- [Quick Start](#quick-start)

- [Documentation](#documentation)

- [Supported Platforms](#supported-platforms)

- [Examples](#examples)

- [Related Projects](#related-projects)

- [Contributing](#contributing)

- [License](#license)

- [Support](#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](https://cloud.ibm.com/docs/vpc?topic=vpc-about-se)

- [IBM Hyper Protect Virtual Servers](https://www.ibm.com/docs/en/hpvs/2.2.x)

- [IBM Hyper Protect Confidential Container for Red Hat OpenShift](https://www.ibm.com/docs/en/hpcc/1.1.x)

## Features

- **Attestation Management**

  - Decrypt encrypted attestation records

  - Verify signature of attestation records against IBM certificates

- **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, initdata annotation and docker compose / podman play archives

  - Create signed and encrypted & 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 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

```bash

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](https://slproweb.com/products/Win32OpenSSL.html)

#### Optional: Custom OpenSSL Path

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

```bash

# 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

```go

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

        "",                  // 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

```go

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](https://ibm-hyper-protect.github.io/contract-go)** - Detailed API reference and usage examples

- **[Go Package Documentation](https://pkg.go.dev/github.com/ibm-hyper-protect/contract-go/v2)** - Generated Go docs

- **[Examples](samples/)** - 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/`](samples/) directory contains example configurations:

- [Simple Contract](samples/simple_contract.yaml)

- [Workload Configuration](samples/workload.yaml)

- [Network Configuration](samples/network/network_config.yaml)

- [Docker Compose](samples/tgz/docker-compose.yaml)

## Related Projects

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

| Project | Description |

|---------|-------------|

| [contract-cli](https://github.com/ibm-hyper-protect/contract-cli) | CLI tool for generating Hyper Protect contracts |

| [terraform-provider-hpcr](https://github.com/ibm-hyper-protect/terraform-provider-hpcr) | Terraform provider for Hyper Protect contracts |

| [k8s-operator-hpcr](https://github.com/ibm-hyper-protect/k8s-operator-hpcr) | Kubernetes operator for contract management |

| [linuxone-vsi-automation-samples](https://github.com/ibm-hyper-protect/linuxone-vsi-automation-samples) | Terraform examples for HPVS and HPCR RHVS |

| [hyper-protect-virtual-server-samples](https://github.com/ibm-hyper-protect/hyper-protect-virtual-server-samples) | HPVS feature samples and scripts |

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:

- Opening issues

- Submitting pull requests

- Code style and conventions

- Testing requirements

Please also read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.

## License

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

## Support

### Reporting Issues

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

- **[Report a Bug](https://github.com/ibm-hyper-protect/contract-go/issues/new?template=bug_report.yml)** - Found a bug? Let us know!

- **[Request a Feature](https://github.com/ibm-hyper-protect/contract-go/issues/new?template=feature_request.yml)** - Have an idea for improvement?

- **[Ask a Question](https://github.com/ibm-hyper-protect/contract-go/issues/new?template=question.yml)** - Need help using the library?

### Security

- **Security Vulnerabilities**: Report via [GitHub Security Advisories](https://github.com/ibm-hyper-protect/contract-go/security/advisories/new) - **DO NOT** create public issues

- See our complete [Security Policy](SECURITY.md) for details

### Community

- **[Discussions](https://github.com/ibm-hyper-protect/contract-go/discussions)** - General questions and community discussion

- **[Documentation](https://ibm-hyper-protect.github.io/contract-go)** - Comprehensive API documentation

- **[Maintainers](MAINTAINERS.md)** - Current maintainer list and contact info

## Contributors

![Contributors](https://contrib.rocks/image?repo=ibm-hyper-protect/contract-go)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/ibm-hyper-protect/contract-go

Awesome Lists containing this project

README
