Skip to content

Commit 430e5b1

Browse files
grmincharvind5vartikadkrishnadesai0987Minch, GlennX R
authored
Cassini 13303a - update readmes (#175)
* Updated error message and fixed indentation. * Add validation for HTTP scheme to avoid API Key leakage (#93) * cassini-10987Golang version upgrade to 1.21.4 (#94) * Major revision of the repo main and tdx-cli README files. * Minor format correction * Consolidate adapters, update tdx, main, & go-connector readmes, add deprecation notices. * Updates per PR review comments. * Minor change to go-tpm readme per conversation with Kent. * One more change to go-tpm readme. * Misc updates. --------- Co-authored-by: Rawat, Arvind <arvind.rawat@intel.com> Co-authored-by: vartikad <50076331+vartikad@users.noreply.github.com> Co-authored-by: krishnadesai0987 <109665492+krishnadesai0987@users.noreply.github.com> Co-authored-by: Minch, GlennX R <glennx.r.minch@intel.com> Co-authored-by: Thompson, Kent <kent.thompson@intel.com>
1 parent 98349bb commit 430e5b1

File tree

7 files changed

+130
-206
lines changed

7 files changed

+130
-206
lines changed

‎README.md

Lines changed: 47 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,62 @@
1-
---
2-
last_updated: 18 October 2024
3-
---
1+
# Intel® Trust Authority Client for Go
2+
3+
<p style="font-size: 0.875em;">· 10/14/2024 ·</p>
4+
5+
[Intel® Trust Authority](https://www.intel.com/content/www/us/en/security/trust-authority.html) [Client for Go](https://docs.trustauthority.intel.com/main/articles/integrate-go-client.html) ("the client") provides a set of Go modules and a command line interface (CLI) for attesting different TEEs with Intel Trust Authority. The attestation client API and [attestation client CLI](https://docs.trustauthority.intel.com/main/articles/integrate-go-tdx-cli.html) can be used by both attesters and relying parties, in either Passport or Background-check attestation mode.
6+
7+
> [!NOTE]
8+
> This is the General Availability (GA) release code for the Intel TDX host , Azure CVM\* with Intel TDX+vTPM , and GCP CVM with Intel TDX adapters are now consolidated in the **main** branch in the [`go-tdx`](./go-tdx/) directory.
9+
<br> <p style="font-size: 0.875em;">**\*** CVM = Confidential Virtual Machine</p>
10+
11+
> [!NOTE]
12+
> The following preview branches are deprecated in this release: **azure-tdx-preview**, **tpm-preview**, and **gcp-tdx-preview**. These branches will be removed in the next release.
413
5-
# Intel® Trust Authority Client
14+
## Supported TEEs and Platforms
15+
The Intel Trust Authority Client for Go works with the following TEEs and platforms:
616

7-
[Intel® Trust Authority](https://www.intel.com/content/www/us/en/security/trust-authority.html) Client for Go ("the Client") provides a set of Go modules and command line interfaces (CLI) for attesting different TEEs with Intel Trust Authority. The Client can be used by both attesters and relying parties, in either Passport or Background-check attestation mode. You can import the Go modules into your application, or you can directly invoke the CLI for Intel® TDX attestation from your application or workflow.
17+
| TEE or Platform | Status | Repo Branch | Notes |
18+
| --- | --- | --- | --- |
19+
| Intel® Software Guard Extensions (Intel® SGX) | GA | [**main**](https://github.com/intel/trustauthority-client-for-go/tree/main/go-sgx) | Bare metal host/on-premises. |
20+
| Intel® Trust Domain Extensions (Intel® TDX) | GA | [**main**](https://github.com/intel/trustauthority-client-for-go/tree/main/go-tdx) | Bare metal hosts & cloud VMs that support configfs, such as GCP. See the notes above this table. |
21+
| Azure\* confidential VMs with Intel TDX | GA | [**main**](https://github.com/intel/trustauthority-client-for-go/tree/main/go-aztdx) | Moved from Preview to GA status. See notes.|
22+
| Azure\* confidential VMs with Intel TDX and vTPM | GA | [**main**](https://github.com/intel/trustauthority-client-for-go/tree/go-tpm) | Moved from Preview to GA status. See notes.|
23+
| Google Cloud Platform\* (GCP) confidential VMs on Intel CPUs with Intel TDX | GA | [**main**](https://github.com/intel/trustauthority-client-for-go/tree/main/go-tdx) | Moved from Preview to GA status. See notes. |
24+
| AMD Secure Encrypted Virtualization - Secure Nested Paging\* (AMD SEV-SNP\*) | Preview | [**sevsnp-preview**](https://github.com/intel/trustauthority-client-for-go/tree/sevsnp-preview) | Pilot environment only |
25+
| Physical TPM | Preview | [**physical-tpm-preview**](https://github.com/intel/trustauthority-client-for-go/tree/physical-tpm-preview) | Pilot environment only |
826

9-
Supported TEEs include [Intel® Software Guard Extensions](https://www.intel.com/content/www/us/en/products/docs/accelerator-engines/software-guard-extensions.html) (Intel® SGX) and [Intel® Trust Domain Extensions](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html) (Intel® TDX), [Azure confidential VMs with Intel TDX](https://azure.microsoft.com/en-us/updates/confidential-vms-with-intel-tdx-dcesv5-ecesv5-public-preview/) (Preview), and Google Cloud Platform (GCP) [Confidential VMs on Intel CPUs with Intel TDX](https://cloud.google.com/blog/products/identity-security/confidential-vms-on-intel-cpus-your-datas-new-intelligent-defense) (Preview). Eventually, other platforms may be added.
27+
Platforms with status **GA** are available and supported in the US and EU production environments. **Preview** TEEs and platforms are in limited-access preview status in the pilot environments only. Details of implementation and usage may change before general availability. The corresponding Intel Trust Authority attestation services for preview features are not available in the production environment. Contact your Intel representative for more information about the pilot program.
1028

11-
For more information about the Client for Go and CLI for Intel TDX, see [Client integration reference](https://docs.trustauthority.intel.com/main/articles/integrate-overview.html) in the Intel Trust Authority documentation.
29+
You can use the clients to collect the reference values needed for attestation policies. For example, you can create a known-good state for your TEE, use the client CLI to collect evidence, and then use the collected evidence values to create an [attestation policy](https://docs.trustauthority.intel.com/main/articles/concept-policy-v2.html) for Intel Trust Authority.
1230

13-
## Methods of Integration
31+
Client libraries require **Go 1.22 or newer**. See https://go.dev/doc/install for installation of Go.
1432

15-
The Client provides the following modules that can be imported by an application to attest Intel® SGX and Intel® TDX TEEs by using Intel Trust Authority.
33+
## Repo Structure
1634

17-
1. [go-connector](./go-connector): Provides an HTTPClient interface to communicate with Intel Trust Authority via REST APIs for remote attestations services, and functions to verify an attestation token and download the JWKS of token signing certificates. The Connector can be used by attesters or relying parties.
18-
1. [go-sgx](./go-sgx): Implements an adapter interface to Intel® SGX DCAP to collect evidence from an Intel SGX enclave for attestation by Intel Trust Authority.
19-
1. [go-tdx](./go-tdx): Implements an adapter interface to collect evidence from an Intel TDX trust domain (TD) for attestation by Intel Trust Authority. The go-tdx adapter also implements utility functions to decrypt a blob or create a new RSA key pair.
20-
1. [go-tpm](./go-tpm): Implements an adapter interface to collect evidence from a Trusted Platform Module (TPM) for attestation by Intel Trust Authority.
21-
1. [go-aztdx](./go-aztdx): Implements an adapter interface to collect evidence from a Azure Confidential Virtual Machine (CVM) with Intel TDX for attestation by Intel Trust Authority.
35+
The repository **main** branch contains the following principal directories:
2236

23-
Intel Trust Authority CLI for Intel TDX [tdx-cli](./tdx-cli) provides a CLI to attest an Intel TDX TD with Intel Trust Authority. tdx-cli requires go-connector and go-tdx. See the [README](./tdx-cli/README.md) for details.
37+
- **go-connector**: Go modules for connecting to Intel Trust Authority services. This is the core library.
38+
- **go-sgx**: Go modules for attesting an Intel SGX enclave.
39+
- **go-tdx**: Go modules for attesting Intel TDX trust domains.
40+
- **tdx-cli**: Attestation client command line interface (CLI).
41+
- **go-tpm**: Go modules for attesting a TPM.
42+
- **go-aztdx**: Go modules for attesting an Azure confidential VM with Intel TDX and vTPM.
43+
- **release**: Scripts for installing the client CLI for different platforms. Usage is described in the README files for the platform.
2444

25-
## Go Requirement
45+
Preview branches are added as needed for preview versions of new TEE or platform adapters and features. The preview branches are named for the TEE or platform they support. Preview branches are based on **main**, with modifications as required. The README files in each branch describe the prerequisites and installation for the platform.
2646

27-
Requires **Go 1.22 or newer**. See https://go.dev/doc/install for installation of Go.
47+
The primary documentation for all of the client adapters including preview versions is available in the Intel Trust Authority documentation [Client integration reference](https://docs.trustauthority.intel.com/main/articles/integrate-overview.html).
48+
49+
## Code of Conduct and Contributing
50+
51+
See the [CONTRIBUTING](./CONTRIBUTING.md) file for information on how to contribute to this project. The project follows the [ Code of Conduct](./CODE_OF_CONDUCT.md).
2852

2953
## License
3054

3155
This library is distributed under the BSD-style license found in the [LICENSE](./LICENSE)
3256
file.
57+
58+
<br><br>
59+
---
60+
**\*** Other names and brands may be claimed as the property of others.
61+
62+
<!--- links --->

‎go-aztdx/README.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
1-
Intel Trust Authority Azure CVM Intel TDX with vTPM Adapter for Go
1+
Intel Trust Authority Azure CVM Intel TDX for Go
22

33
<p style="font-size: 0.875em;">· 08/22/2024 ·</p>
44

5-
> [!NOTE]
6-
> Intel® Trust Authority Azure confidential VM (CVM) with Intel TDX and vTPM Adapter for Go is in limited preview status. Details of implementation and usage may change before general availability. Preview features are only available on the Intel Trust Authority pilot environment. Contact your Intel representative for access.
7-
85

96
## Usage
107

11-
Import the **go-aztdx** package into your project to attest an Azure confidential VM with Intel TDX and vTPM. The following import statements includes the **go-connector**, which provides the core functionality for attestation, and **go-tpm**, which provides the TPM adapter for interacting with the vTPM.
8+
Import the **go-aztdx** package into your project to collect TDX evidence from an Azure confidential VM. The following import statements includes the **go-connector**, which provides the core functionality for attestation, and **go-tpm**, which is used to collect TDX evidence from Azure's vTPM.
129

1310
```go
1411

‎go-connector/README.md

Lines changed: 20 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,21 @@
1-
---
2-
last_updated: 30 January 2024
3-
---
1+
# Intel® Trust Authority Client Go Connector
42

5-
# Intel® Trust Authority Connector
3+
<p style="font-size: 0.875em;">· 10/18/2024 ·</p>
64

7-
The [Intel® Trust Authority](https://www.intel.com/content/www/us/en/security/trust-authority.html) **go-connector** module is the main component of the integration client. The go-connector provides attestation and verification functions, and it can be used by an attester in a supported TEE, or by a relying party. A relying party can run the go-connector as a standalone module; it does not require Intel® SGX DCAP or a TEE adapter. A confidential computing workload (the attester) running in a supported TEE requires the go-connector and a TEE adapter module to collect evidence (a quote) from the TEE.
5+
The [Intel® Trust Authority](https://www.intel.com/content/www/us/en/security/trust-authority.html) **go-connector** module is the main component of the remote attestation client. The go-connector provides a set of Go modules for connecting to Intel Trust Authority services. The go-connector API is designed to be used by both attesters and relying parties, in either Passport or Background-check attestation mode. Go-connector relies on _TEE adapters_ to interact with the underlying host platform.
86

9-
For more information about the Client for Go and CLI for Intel TDX, see [Client integration reference](https://docs.trustauthority.intel.com/main/articles/integrate-overview.html) in the Intel Trust Authority documentation.
7+
There are two options for using **go-connector**: you can import the Go modules into your Go application, or you can execute the [attestation client CLI](https://docs.trustauthority.intel.com/main/articles/integrate-go-tdx-cli.html) from your application or workflow. The CLI is a wrapper around the go-connector that provides a command-line interface the core functionality of the go-connector, plus additional features exposed by TEE adapters.
108

11-
## Download
9+
**go-connector** requires configuration information to connect to the Intel Trust Authority service. The configuration information includes the URL of the Intel Trust Authority service for your region, the API key, TLS configuration, and optional connection retry parameters. For more information, see the [sample configuration code](https://docs.trustauthority.intel.com/main/articles/integrate-go-client.html#go-connector-api).
10+
11+
For more information about **go-connector** and related topics, see the following resources:
12+
- [Intel Trust Authority Go Connector Reference](https://docs.trustauthority.intel.com/main/articles/integrate-go-client.html) — Detailed documentation for the go-connector API.
13+
- [Intel Trust Authority Attestation Client CLI](https://docs.trustauthority.intel.com/main/articles/integrate-go-tdx-cli.html) — Documentation for the attestation client CLI.
14+
- [Intel Trust Authority Documentation](https://docs.trustauthority.intel.com/main/) —The primary documentation for Intel Trust Authority.
15+
- [Intel Trust Authority Client README](../README.md) — The main README for this branch.
16+
17+
18+
## Download **go-connector**
1219

1320
Download the latest version of the module with the following command.
1421

@@ -22,135 +29,18 @@ Use **Go 1.22 or newer**. See https://go.dev/doc/install for installation of Go.
2229

2330
## Unit Tests
2431

25-
To run the tests, run `cd go-connector && go test ./...`
26-
27-
See the example test in `go-connector/token_test.go` for an example of a test.
32+
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.
2833

2934
## Usage
3035

31-
Create a new Connector instance, and then use the exposed interfaces to
32-
access different parts of the Intel Trust Authority API.
33-
34-
```go
35-
import "github.com/intel/trustauthority-client/go-connector"
36-
37-
cfg := connector.Config{
38-
// Intel Trust Authority base URL
39-
BaseUrl: "https://portal.trustauthority.intel.com",
40-
// Intel Trust Authority API URL
41-
ApiUrl: "https://api.trustauthority.intel.com",
42-
// Provide TLS config
43-
TlsCfg: &tls.Config{},
44-
// Replace TRUSTAUTHORITY_API_KEY with an **attestation** API key
45-
ApiKey: "TRUSTAUTHORITY_API_KEY",
46-
// Provide Retry config
47-
RClient: &connector.RetryConfig{},
48-
}
49-
50-
retryCfg := connector.RetryConfig{
51-
// Minimum time to wait between retries, default is 2s.
52-
RetryWaitMin:
53-
// Maximum time to wait between retries, default is 10s.
54-
RetryWaitMax:
55-
// Maximum number of retries, default is 2.
56-
RetryMax:
57-
// CheckRetry specifies the policy for handling retries, and is called
58-
// after each request. Default retries when http status code is one of 500, 503, or 504,
59-
// and when there is a client timeout or if a service is unavailable.
60-
CheckRetry:
61-
// Backoff specifies the policy for how long to wait between retries, default is DefaultBackoff, which
62-
// provides a default callback for Backoff that will perform an exponential backoff based on the attempt
63-
// number and limited by the provided minimum and maximum durations.
64-
BackOff:
65-
}
66-
67-
connector, err := connector.New(&cfg)
68-
if err != nil {
69-
fmt.Printf("Something bad happened: %s\n\n", err)
70-
return err
71-
}
72-
```
73-
74-
### To get an Intel Trust Authority signed nonce
36+
For usage information, see the [Intel Trust Authority Go Connector Reference](https://docs.trustauthority.intel.com/main/articles/integrate-go-client.html).
7537

76-
**GetNonce()** accepts an optional [RequestID](https://docs.trustauthority.intel.com/main/articles/glossary.html#request-id) that you can use to track API requests. If successful, GetNonce() returns the nonce and HTTP response headers, or an error if unsuccessful.
38+
## Code of Conduct and Contributing
7739

78-
```go
79-
req := connector.GetNonceArgs{
80-
RequestId: reqId,
81-
}
82-
resp, err := connector.GetNonce(req)
83-
if err != nil {
84-
fmt.Printf("Something bad happened: %s\n\n", err)
85-
return err
86-
}
87-
```
88-
89-
### To get Intel Trust Authority attestation token
90-
91-
There are two methods for requesting an attestation token: **Attest()** and **GetToken()**. Attest() is the simplest method to implement for Passport attestation. GetToken() supports the Background-check attestation model. The following code fragment assumes that you have previously obtained a nonce and a quote.
92-
93-
If successful, GetToken() returns an Intel Trust Authority attestation token (JWT) and the HTTP response headers, or an error if unsuccessful.
94-
95-
```go
96-
req := connector.GetTokenArgs{
97-
Nonce: nonce,
98-
Evidence: evidence,
99-
PolicyIds: policyIds,
100-
RequestId: reqId,
101-
TokenSigningAlg: alg,
102-
PolicyMustMatch: matchFlag,
103-
}
104-
resp, err := connector.GetToken(req)
105-
if err != nil {
106-
fmt.Printf("Something bad happened: %s\n\n", err)
107-
return err
108-
}
109-
```
110-
111-
### To verify an attestation token
112-
113-
**VerifyToken()** takes an attestation token as input, and then checks the token format and verifies that it was signed with a genuine Intel Trust Authority certificate, and that the public key can be extracted from the certificate. VerifyToken() does not validate claims in the JWT body. VerifyToken() returns a parsed token in JWT format if successful, or an error if unsuccessful.
114-
115-
```go
116-
parsedToken, err := connector.VerifyToken(string(token))
117-
if err != nil {
118-
fmt.Printf("Something bad happened: %s\n\n", err)
119-
return err
120-
}
121-
```
122-
123-
### To download Intel Trust Authority token signing certificates
124-
125-
**GetTokenSigningCertificates()** gets the JWKS of certificates used by Intel Trust Authority to sign attestation tokens. To get the signing certificate for a given token, search the JWKS for the ID contained in the attestation token's **kid** claim.
126-
127-
```go
128-
jwks, err := connector.GetTokenSigningCertificates()
129-
if err != nil {
130-
fmt.Printf("Something bad happened: %s\n\n", err)
131-
return err
132-
}
133-
```
134-
135-
### To attest a TEE using Attest()
136-
137-
**Attest()** provides an all-in-one method for getting a nonce, collecting a quote from a TEE, and then requesting a attestation token from Intel Trust Authority. You need to create a Connector and a TEE adapter before calling Attest(). The sample above shows how to create a Connector.
138-
139-
For more information about TEE adapters, see [go-sgx](../go-sgx/README.md) or [go-tdx](../go-tdx/README.md).
140-
141-
```go
142-
req := connector.AttestArgs{
143-
Adapter: adapter,
144-
PolicyIds: policyIds,
145-
RequestId: reqId,
146-
}
147-
resp, err := connector.Attest(req)
148-
if err != nil {
149-
return err
150-
}
151-
```
40+
See the [CONTRIBUTING](../CONTRIBUTING.md) file for information on how to contribute to this project. The project follows the [ Code of Conduct](../CODE_OF_CONDUCT.md).
15241

15342
## License
15443

155-
This source is distributed under the BSD-style license found in the [LICENSE](../LICENSE)
44+
This library is distributed under the BSD-style license found in the [LICENSE](../LICENSE)
15645
file.
46+

0 commit comments

Comments
 (0)