connector

README

Intel® Trust Authority Connector

Go module for communicating with Intel Trust Authority via REST APIs.

Download

Download the latest version of the module with the following command:

go get github.com/intel/trustauthority-client/go-connector

Go Requirement

Use go1.19 or newer. Follow https://go.dev/doc/install for installation of Go.

Unit Tests

To run the tests, run cd go-connector && go test ./...

See the example test in go-connector/token_test.go for an example of a test.

Usage

Create a new Connector instance, then use the exposed interfaces to access different parts of the Intel Trust Authority API.

import "github.com/intel/trustauthority-client/go-connector"

cfg := connector.Config{
        // Replace TRUSTAUTHORITY_URL with real Intel Trust Authority URL
        BaseUrl: "TRUSTAUTHORITY_URL",
        // Replace TRUSTAUTHORITY_API_URL with real Intel Trust Authority API URL
        ApiUrl: "TRUSTAUTHORITY_API_URL",
        // Provide TLS config
        TlsCfg: &tls.Config{},
        // Replace TRUSTAUTHORITY_API_KEY with real API key
        ApiKey: "TRUSTAUTHORITY_API_KEY",
        // Provide Retry config
        RClient: &connector.RetryConfig{},
}

retryCfg := connector.RetryConfig{
        // Minimum time to wait between retries, default is 2s
        RetryWaitMin:
        // Maximum time to wait between retries, default is 10s
        RetryWaitMax:
        // Maximum number of retries, default is 2
        RetryMax:
        // CheckRetry specifies the policy for handling retries, and is called
        // after each request. Default retries when http status code is one among 500, 503 and 504
        // and when there is client timeout or if a service is unavailable
        CheckRetry:
        // Backoff specifies the policy for how long to wait between retries, default is DefaultBackoff, which 
        // provides a default callback for Backoff which will perform exponential backoff based on the attempt
        // number and limited by the provided minimum and maximum durations.
        BackOff:
}

connector, err := connector.New(&cfg)
if err != nil {
    fmt.Printf("Something bad happened: %s\n\n", err)
    return err
}

To get Intel Trust Authority signed nonce

req := connector.GetNonceArgs{
    RequestId: reqId,
}
resp, err := connector.GetNonce(req)
if err != nil {
    fmt.Printf("Something bad happened: %s\n\n", err)
    return err
}

To get Intel Trust Authority signed token with Nonce and Evidence

req := connector.GetTokenArgs{
    Nonce:     nonce,
    Evidence:  evidence,
    PolicyIds: policyIds,
    RequestId: reqId,
}
resp, err := connector.GetToken(req)
if err != nil {
    fmt.Printf("Something bad happened: %s\n\n", err)
    return err
}

To verify Intel Trust Authority signed token

parsedToken, err := connector.VerifyToken(string(token))
if err != nil {
    fmt.Printf("Something bad happened: %s\n\n", err)
    return err
}

To download Intel Trust Authority token signing certificates

jwks, err := connector.GetTokenSigningCertificates()
if err != nil {
    fmt.Printf("Something bad happened: %s\n\n", err)
    return err
}

To attest TEE with Intel Trust Authority using TEE Adapter

To create adapter refer go-sgx or go-tdx:

req := connector.AttestArgs{
    Adapter:   adapter,
    PolicyIds: policyIds,
    RequestId: reqId,
}
resp, err := connector.Attest(req)
if err != nil {
    return err
}

License

This source is distributed under the BSD-style license found in the LICENSE file.

Documentation

Overview

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

* Copyright (c) 2022-2023 Intel Corporation * All rights reserved. * SPDX-License-Identifier: BSD-3-Clause

Index

• Constants
• type AttestArgs
• type AttestResponse
• type AttestationTokenResponse
• type Config
• type Connector
  • func New(cfg *Config) (Connector, error)
• type Evidence
• type EvidenceAdapter
• type GetNonceArgs
• type GetNonceResponse
• type GetTokenArgs
• type GetTokenResponse
• type RetryConfig
• type VerifierNonce

Constants

const (
	HeaderRequestId = "request-id"
	HeaderTraceId   = "trace-id"

	AtsCertChainMaxLen         = 10
	MaxRetries                 = 2
	DefaultRetryWaitMinSeconds = 2
	DefaultRetryWaitMaxSeconds = 10
	ServiceUnavailableError    = `service unavailable`
)

Types

type AttestArgs

type AttestArgs struct {
	Adapter   EvidenceAdapter
	PolicyIds []uuid.UUID
	RequestId string
}

AttestArgs holds the request parameters needed for attestation with Intel Trust Authority

type AttestResponse

type AttestResponse struct {
	Token   string
	Headers http.Header
}

AttestResponse holds the response parameters recieved during attestation flow

type AttestationTokenResponse

type AttestationTokenResponse struct {
	Token string `json:"token"`
}

AttestationTokenResponse holds the token recieved from Intel Trust Authority

type Config

type Config struct {
	BaseUrl string
	TlsCfg  *tls.Config
	ApiUrl  string
	ApiKey  string

	*RetryConfig
	// contains filtered or unexported fields
}

Config holds the Intel Trust Authority configuration for Connector

type Connector

type Connector interface {
	GetTokenSigningCertificates() ([]byte, error)
	GetNonce(GetNonceArgs) (GetNonceResponse, error)
	GetToken(GetTokenArgs) (GetTokenResponse, error)
	Attest(AttestArgs) (AttestResponse, error)
	VerifyToken(string) (*jwt.Token, error)
}

Connector is an interface which exposes methods for calling Intel Trust Authority REST APIs

func New

func New(cfg *Config) (Connector, error)

New returns a new Connector instance

type Evidence

type Evidence struct {
	Type     uint32
	Evidence []byte
	UserData []byte
	EventLog []byte
}

Evidence is used to store Quote to be sent for Attestation

type EvidenceAdapter

type EvidenceAdapter interface {
	CollectEvidence(nonce []byte) (*Evidence, error)
}

EvidenceAdapter is an interface which exposes methods for collecting Quote from Platform

type GetNonceArgs

type GetNonceArgs struct {
	RequestId string
}

GetNonceArgs holds the request parameters needed for getting nonce from Intel Trust Authority

type GetNonceResponse

type GetNonceResponse struct {
	Nonce   *VerifierNonce
	Headers http.Header
}

GetNonceResponse holds the response parameters recieved from nonce endpoint

type GetTokenArgs

type GetTokenArgs struct {
	Nonce     *VerifierNonce
	Evidence  *Evidence
	PolicyIds []uuid.UUID
	RequestId string
}

GetTokenArgs holds the request parameters needed for getting token from Intel Trust Authority

type GetTokenResponse

type GetTokenResponse struct {
	Token   string
	Headers http.Header
}

GetTokenResponse holds the response parameters recieved from attest endpoint

type RetryConfig

type RetryConfig struct {
	RetryWaitMin *time.Duration // Minimum time to wait between retries
	RetryWaitMax *time.Duration // Maximum time to wait between retries
	RetryMax     *int           // Maximum number of retries

	CheckRetry retryablehttp.CheckRetry
	BackOff    retryablehttp.Backoff
}

RetryConfig holds the configuration for automatic retries to tolerate minor outages

type VerifierNonce

type VerifierNonce struct {
	Val       []byte `json:"val"`
	Iat       []byte `json:"iat"`
	Signature []byte `json:"signature"`
}

VerifierNonce holds the signed nonce issued from Intel Trust Authority