nitrite

README

Nitrite

A library for verifying AWS Nitro Enclave attestations for Go.

Usage

It's fairly simple to use it, so here's an example:

import (
	"bytes"
	"github.com/hf/nitrite"
	"time"
)

func verifyAttestation(attestation []byte) error {
	res, err := nitrite.Verify(
		bytes.NewReader(attestation),
		nitrite.VerifyOptions{
			CurrentTime: time.Now(),
		})

	if nil != err {
		return err
	}

	return nil
}

This package includes the Nitro Enclave Root CA certificates.

It's recommended you explicitly calculate the SHA256 sum of the DefaultRootCA string and match it according to the AWS documentation at the start of your application. Alternatively, you can supply your own copy of the root CA.

License

Copyright © 2021 Stojan Dimitrovski. Licensed under the MIT License. See LICENSE for more information.

Documentation

Overview

Package nitrite implements attestation verification for AWS Nitro Enclaves.

Index

• Constants
• Variables
• type Document
• type Result
  • func Verify(data []byte, options VerifyOptions) (*Result, error)
• type VerifyOptions

Constants

const (
	// DefaultCARoots contains the PEM encoded roots for verifying Nitro
	// Enclave attestation signatures. You can download them from
	// https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip
	// It's recommended you calculate the SHA256 sum of this string and match
	// it to the one supplied in the AWS documentation
	// https://docs.aws.amazon.com/enclaves/latest/user/verify-root.html
	DefaultCARoots string = "" /* 792-byte string literal not displayed */
)

Variables

var (
	ErrBadCOSESign1Structure          error = errors.New("Data is not a COSESign1 array")
	ErrCOSESign1EmptyProtectedSection error = errors.New("COSESign1 protected section is nil or empty")
	ErrCOSESign1EmptyPayloadSection   error = errors.New("COSESign1 payload section is nil or empty")
	ErrCOSESign1EmptySignatureSection error = errors.New("COSESign1 signature section is nil or empty")
	ErrCOSESign1BadAlgorithm          error = errors.New("COSESign1 algorithm not ECDSA384")
)

Errors that are encountered when manipulating the COSESign1 structure.

var (
	ErrBadAttestationDocument           error = errors.New("Bad attestation document")
	ErrMandatoryFieldsMissing           error = errors.New("One or more of mandatory fields missing")
	ErrBadDigest                        error = errors.New("Payload 'digest' is not SHA384")
	ErrBadTimestamp                     error = errors.New("Payload 'timestamp' is 0 or less")
	ErrBadPCRs                          error = errors.New("Payload 'pcrs' is less than 1 or more than 32")
	ErrBadPCRIndex                      error = errors.New("Payload 'pcrs' key index is not in [0, 32)")
	ErrBadPCRValue                      error = errors.New("Payload 'pcrs' value is nil or not of length {32,48,64}")
	ErrBadCABundle                      error = errors.New("Payload 'cabundle' has 0 elements")
	ErrBadCABundleItem                  error = errors.New("Payload 'cabundle' has a nil item or of length not in [1, 1024]")
	ErrBadPublicKey                     error = errors.New("Payload 'public_key' has a value of length not in [1, 1024]")
	ErrBadUserData                      error = errors.New("Payload 'user_data' has a value of length not in [1, 512]")
	ErrBadNonce                         error = errors.New("Payload 'nonce' has a value of length not in [1, 512]")
	ErrBadCertificatePublicKeyAlgorithm error = errors.New("Payload 'certificate' has a bad public key algorithm (not ECDSA)")
	ErrBadCertificateSigningAlgorithm   error = errors.New("Payload 'certificate' has a bad public key signing algorithm (not ECDSAWithSHA384)")
	ErrBadSignature                     error = errors.New("Payload's signature does not match signature from certificate")
)

Errors encountered when parsing the CBOR attestation document.

Types

type Document

type Document struct {
	ModuleID    string          `cbor:"module_id" json:"module_id"`
	Timestamp   uint64          `cbor:"timestamp" json:"timestamp"`
	Digest      string          `cbor:"digest" json:"digest"`
	PCRs        map[uint][]byte `cbor:"pcrs" json:"pcrs"`
	Certificate []byte          `cbor:"certificate" json:"certificate"`
	CABundle    [][]byte        `cbor:"cabundle" json:"cabundle"`

	PublicKey []byte `cbor:"public_key" json:"public_key,omitempty"`
	UserData  []byte `cbor:"user_data" json:"user_data,omitempty"`
	Nonce     []byte `cbor:"nonce" json:"nonce,omitempty"`
}

Document represents the AWS Nitro Enclave Attestation Document.

type Result

type Result struct {
	// Document contains the attestation document.
	Document *Document `json:"document,omitempty"`

	// Certificates contains all of the certificates except the root.
	Certificates []*x509.Certificate `json:"certificates,omitempty"`

	// Protected section from the COSE Sign1 payload.
	Protected []byte `json:"protected,omitempty"`
	// Unprotected section from the COSE Sign1 payload.
	Unprotected []byte `json:"unprotected,omitempty"`
	// Payload section from the COSE Sign1 payload.
	Payload []byte `json:"payload,omitempty"`
	// Signature section from the COSE Sign1 payload.
	Signature []byte `json:"signature,omitempty"`

	// SignatureOK designates if the signature was OK (but certificate could be
	// invalid, not trusted, expired, etc.)
	SignatureOK bool `json:"signature_ok"`

	// COSESign1 contains the COSE Signature Structure which was used to
	// calculate the `Signature`.
	COSESign1 []byte `json:"cose_sign1,omitempty"`
}

Result is a successful verification result of an attestation payload.

func Verify

func Verify(data []byte, options VerifyOptions) (*Result, error)

Verify verifies the attestation payload from `data` with the provided verification options. If the options specify `Roots` as `nil`, the `DefaultCARoot` will be used. If you do not specify `CurrentTime`, `time.Now()` will be used. It is strongly recommended you specifically supply the time. If the returned error is non-nil, it is either one of the `Err` codes specified in this package, or is an error from the `crypto/x509` package. Revocation checks are NOT performed and you should check for revoked certificates by looking at the `Certificates` field in the `Result`. Result will be non-null if and only if either of these are true: certificate verification has passed, certificate verification has failed (expired, not trusted, etc.), signature is OK or signature is not OK. If either signature is not OK or certificate can't be verified, both Result and error will be set! You can use the SignatureOK field from the result to distinguish errors.

type VerifyOptions

type VerifyOptions struct {
	Roots       *x509.CertPool
	CurrentTime time.Time
}

VerifyOptions specifies the options for verifying the attestation payload. If `Roots` is nil, the `DefaultCARoot` is used. If `CurrentTime` is 0, `time.Now()` will be used. It is a strong recommendation you explicitly supply this value.