attestationreport

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 24, 2022 License: Apache-2.0 Imports: 21 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Sign added in v0.2.0 

func Sign(mu *sync.Mutex, ar ArJws, priv crypto.PrivateKey, pub crypto.PublicKey, certsPem [][]byte) (bool, []byte)

Sign signs the attestation report with private key 'priv' and appends the pem encoded certificate chain 'certsPem' to the JWS structure. The certificates must be handed over in the order they should be appended (Signing Certificate -> Intermediate Certificates -> Root CA Certificate) Parameter 'mu' is an optional mutex, in case the private key requires exclusive access (e.g. because it is located in a hardware module)

Types

type AppDescription 

type AppDescription struct {
	Type        string              `json:"type"`
	Name        string              `json:"name"`
	AppManifest string              `json:"appManifest"` // Links to Type 'App Manifest'->'Name'
	External    []ExternalInterface `json:"externalConnections"`
}

AppDescription represents the JSON attestation report element of type 'App Description'

type AppManifest 

type AppManifest struct {
	Type               string           `json:"type"`
	Name               string           `json:"name"`
	DevCommonName      string           `json:"developerCommonName"`
	Version            string           `json:"version"`
	Oss                []string         `json:"oss"` // Links to Type 'OsManifest'->'Name'
	Description        string           `json:"description"`
	CertificationLevel int              `json:"certificationLevel"`
	Validity           Validity         `json:"validity"`
	Verifications      []SwVerification `json:"verifications"`
}

AppManifest represents the JSON attestation report element of type 'App Manifest'

type ArJws 

type ArJws struct {
	Type               string          `json:"type"`
	TpmM               TpmMeasurement  `json:"tpmMeasurement,omitempty"`
	SWM                []SwMeasurement `json:"swMeasurements,omitempty"`
	RtmManifest        string          `json:"rtmManifests"`
	OsManifest         string          `json:"osManifest"`
	AppManifests       []string        `json:"appManifests"`
	CompanyDescription string          `json:"companyDescription"`
	DeviceDescription  string          `json:"deviceDescription"`
	Nonce              string          `json:"nonce"`
}

ArJws represents the attestation report in JWS format with its contents already in signed JWs format

func Generate added in v0.2.0 

func Generate(nonce []byte, metadata [][]byte, measurements []Measurement, measurementParams []MeasurementParams) ArJws

Generate generates an attestation report with the provided nonce 'nonce' and manifests and descriptions 'metadata'. The manifests and descriptions must be raw JWS tokens in the JWS JSON full serialization format. Takes a list of 'measurements' and accompanying 'measurementParams', which must be arrays of the same length. The 'measurements' must implement the attestation report 'Measurer' interface providing a method for collecting the measurements from a hardware or software interface

type ArPlain 

type ArPlain struct {
	Type               string             `json:"type"`
	TpmM               TpmMeasurement     `json:"tpmMeasurement,omitempty"`
	SWM                []SwMeasurement    `json:"swMeasurements,omitempty"`
	RtmManifest        RtmManifest        `json:"rtmManifest"`
	OsManifest         OsManifest         `json:"osManifest"`
	AppManifests       []AppManifest      `json:"appManifests"`
	CompanyDescription CompanyDescription `json:"companyDescription"`
	DeviceDescription  DeviceDescription  `json:"deviceDescription"`
	Nonce              string             `json:"nonce"`
}

ArPlain represents the attestation report with its plain elements

type CertParams 

type CertParams struct {
	Type    string   `json:"type"`
	Subject Name     `json:"subject,omitempty"`
	SANs    []string `json:"sans,omitempty"`
}

CertParams contains params of an x.509 certificate. The tpm module cannot send an AK CSR to the server, as the AK is a restricted key which does not allow signing of non-TPM-based objects such as CSRs. Therefore, pass the certificate parameters encoded in this structure

type CompDescResult added in v0.2.0 

type CompDescResult struct {
	Name           string            `json:"name"`
	CompCertLevel  int               `json:"compCertLevel"`       // Overall certification level for the company operating the device
	SignatureCheck []SignatureResult `json:"signatureValidation"` // Results for validation of the Description Signatures and the used certificates
	ValidityCheck  Result            `json:"validityCheck"`       // Result from checking the validity of the manifest
}

CompDescResult represents the results of the validation of the Company Description and its mapping to the used device certificate

type CompanyDescription 

type CompanyDescription struct {
	Type               string   `json:"type"`
	DN                 string   `json:"dn"`
	CertificationLevel int      `json:"certificationLevel"`
	Description        string   `json:"description"`
	Validity           Validity `json:"validity"`
}

CompanyDescription represents the JSON attestation report element of type 'Company Description'

type DevDescResult added in v0.2.0 

type DevDescResult struct {
	Summary             Result            `json:"resultSummary"`
	CorrectRtm          Result            `json:"correctRtm"`               // Result for comparison of RTM in the Device Description and the provided RTM Manifest
	CorrectOs           Result            `json:"correctOs"`                // Result for comparison of OS in the Device Description and the provided OS Manifest
	CorrectApps         Result            `json:"correctApps"`              // Result for comparison of App List in the Device Description and the provided App Manifest
	RtmOsCompatibility  Result            `json:"rtmOsCompatibility"`       // Result for consistency check for mapping from OS Manifest to RTM Manifest
	OsAppsCompatibility Result            `json:"osAppCompatibility"`       // Result for consistency check for mapping from App Manifests to OS Manifest
	SignatureCheck      []SignatureResult `json:"signatureValidation"`      // Results for validation of the Device Description Signature(s) and the used certificates
	OpAffiliation       Result            `json:"operatorAffiliationCheck"` // Result for comparison of the device and the operator affiliation (based on "organization" field in the identity certificates)
}

DevDescResult represents the results of the validation of the Device Description in the Attestation Report

type DeviceDescription added in v0.2.0 

type DeviceDescription struct {
	Type            string               `json:"type"`
	Fqdn            string               `json:"fqdn"`
	Description     string               `json:"description"`
	Location        string               `json:"location"`
	RtmManifest     string               `json:"rtmManifest"`
	OsManifest      string               `json:"osManifest"`
	AppDescriptions []AppDescription     `json:"appDescriptions"`
	Internal        []InternalConnection `json:"internalConnections"`
	External        []ExternalInterface  `json:"externalEndpoints"`
}

DeviceDescription represents the JSON attestation report element of type 'Device Description'

type ExternalInterface 

type ExternalInterface struct {
	Type        string `json:"type"`
	AppEndpoint string `json:"appEndpoint"` // Links to Type 'App Manifest'->'Endpoint'
	Interface   string `json:"interface"`   // Links to Type 'App Description'->'Name'
	Port        int    `json:"port"`        // Links to Type 'App Manifest'->'Endpoint'
}

ExternalInterface represents the JSON attestation report element of type 'External Interface'

type HashChainElem 

type HashChainElem struct {
	Type   string   `json:"type"`
	Pcr    int32    `json:"pcr"`
	Sha256 []string `json:"sha256"`
}

HashChainElem represents the JSON attestation report element of type 'Hash Chain' embedded in 'TPM Measurement'

type InternalConnection 

type InternalConnection struct {
	Type         string `json:"type"`
	NameAppA     string `json:"nameAppA"`     // Links to Type 'App Description'->'Name'
	EndpointAppA string `json:"endpointAppA"` // Links to Type 'App Manifest'->'Endpoint'
	NameAppB     string `json:"nameAppB"`     // Links to Type 'App Description'->'Name'
	EndpointAppB string `json:"endpointAppB"` // Links to Type 'App Manifest'->'Endpoint'
}

InternalConnection represents the JSON attestation report element of type 'Internal Connection'

type JSONType 

type JSONType struct {
	Type string `json:"type"`
}

JSONType is a helper struct for just extracting the JSON 'Type'

type JwsResult added in v0.2.0 

type JwsResult struct {
	Summary        Result            `json:"resultSummary"`
	SignatureCheck []SignatureResult `json:"signatureValidation"`
}

JwsResult is a helper struct for the validation of JWS focussing on the validation of the provided signatures

type ManifestResult added in v0.2.0 

type ManifestResult struct {
	Name           string            `json:"name"`
	Summary        Result            `json:"resultSummary"`
	SignatureCheck []SignatureResult `json:"signatureValidation"` // Results for validation of the Manifest Signatures and the used certificates
	ValidityCheck  Result            `json:"validityCheck"`       // Result from checking the validity of the manifest
}

ManifestResult represents the results of the validation of a manifest provided in the Attestation Report

type Measurement 

type Measurement interface{}

Measurement is a generic interface for a Measurement, such as a TpmMeasurement

type MeasurementParams 

type MeasurementParams interface{}

MeasurementParams is a generic interface for measurement parameters

type MeasurementResult added in v0.2.0 

type MeasurementResult struct {
	TpmMeasResult TpmMeasurementResult  `json:"tpm,omitempty"`
	SwMeasResult  []SwMeasurementResult `json:"sw,omitempty"`
}

MeasurementResult represents the results of the comparison of verifications and measurements. The used attributes depend on the technologies used for calculating the measurements

type Measurer 

type Measurer interface {
	Measure(mp MeasurementParams) (Measurement, error)
}

Measurer is an interface implementing the Measure method for each type of measurement Each type of interface that is capable of providing measurements (such as the tpmw module) is expected to implement this method. The attestationreport module will call this method to retrieve the measurements of the platform during attestation report generation.

type Name 

type Name struct {
	CommonName         string        `json:"commonName,omitempty"`
	Country            string        `json:"country,omitempty"`
	Organization       string        `json:"organization,omitempty"`
	OrganizationalUnit string        `json:"organizationalUnit,omitempty"`
	Locality           string        `json:"locality,omitempty"`
	Province           string        `json:"province,omitempty"`
	StreetAddress      string        `json:"streetAddress,omitempty"`
	PostalCode         string        `json:"postalCode,omitempty"`
	Names              []interface{} `json:"names,omitempty"`
}

Name is the PKIX Name for CertParams

type OsManifest 

type OsManifest struct {
	Type               string            `json:"type"`
	Name               string            `json:"name"`
	DevCommonName      string            `json:"developerCommonName"`
	Version            string            `json:"version"`
	Rtms               []string          `json:"rtms"` // Links to Type 'RTM Manifest'->'Name'
	Description        string            `json:"description"`
	CertificationLevel int               `json:"certificationLevel"`
	Validity           Validity          `json:"validity"`
	Verifications      []TpmVerification `json:"verifications"`
}

OsManifest represents the JSON attestation report element of type 'OsManifest'

type PcrResult added in v0.2.0 

type PcrResult struct {
	Pcr     int      `json:"pcr"` // Number for the PCR which was validated
	Success bool     `json:"success"`
	Details []string `json:"details,omitempty"`
}

PcrResult represents the results for the recalculation of a specific PCR

type Result added in v0.2.0 

type Result struct {
	Success bool   `json:"success"`
	Details string `json:"details,omitempty"` // Details on the issue which was detected during validation, remains empty if validation was successful
}

Result is a generic type for storing a boolean result value and some details on the validation

type RtmManifest 

type RtmManifest struct {
	Type               string            `json:"type"`
	Name               string            `json:"name"`
	DevCommonName      string            `json:"developerCommonName"`
	Version            string            `json:"version"`
	Description        string            `json:"description"`
	CertificationLevel int               `json:"certificationLevel"`
	Validity           Validity          `json:"validity"`
	Verifications      []TpmVerification `json:"verifications"`
}

RtmManifest represents the JSON attestation report element of type 'RTM Manifest'

type SignatureResult added in v0.2.0 

type SignatureResult struct {
	Name         string   `json:"commonName"`            // Name of the certificate used for calculating the signature
	Organization []string `json:"organization"`          // Name of the organization the signer belongs to
	Signature    Result   `json:"signatureVerification"` // Result from checking the signature has been calculated with this certificate
	CertCheck    Result   `json:"certChainValidation"`   // Result from validatint the certification chain back to a shared root of trust
	RoleCheck    *Result  `json:"roleCheck,omitempty"`   // Result for checking the role in the certificate (optional)
}

SignatureResults represents the results for validation of a provided signature and the used certificates

type SignerRoles added in v0.2.0 

type SignerRoles struct {
	ManifestSigners    []string
	CompanyDescSigners []string
	ArSigners          []string
	ConnDescSigners    []string
}

In IDS contexts, the different certificates used for signing meta-data must have appropriate roles so that e.g. an operator cannot impersonate an evaluator. This is an optional feature. If used, the corresponding roles must be set in the OrganizationalUnit (OU) field in the x.509 certificates

type SwMeasurement 

type SwMeasurement struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Sha256 string `json:"sha256"`
}

SwMeasurement represents the JSON attestation report element of type 'Software Measurement'

type SwMeasurementResult added in v0.2.0 

type SwMeasurementResult struct {
	MeasName string `json:"measurementName"` // Name associated with the measurement used for validation
	AppName  string `json:appName`           // Name of the App manifest used for validation
	VerName  string `json:verificationName`  // Name of the verification information used for validation
	Success  bool   `json:"success"`
	Details  string `json:"details,omitempty"`
}

SwMeasurementResult represents the results for the verification of a software measurement (currently only used for app verifications)

type SwParams 

type SwParams struct{}

SwParams are parameters for retrieving SW measurements. Currently none required

type SwVerification 

type SwVerification struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Sha256 string `json:"sha256"`
}

SwVerification represents the JSON attestation report element of type 'Software Verification'

type TpmCerts 

type TpmCerts struct {
	AkCert        string   `json:"akCert"`
	Intermediates []string `json:"akIntermediates"`
	CaCert        string   `json:"caCertificate"`
}

TpmCerts is a helper struct for the AK certificate chain

type TpmMeasurement 

type TpmMeasurement struct {
	Type      string           `json:"type"`
	Message   string           `json:"message"`
	Signature string           `json:"signature"`
	Certs     TpmCerts         `json:"certs"`
	HashChain []*HashChainElem `json:"hashChain"`
}

TpmMeasurement represents the JSON attestation report element of type 'TPM Measurement'

type TpmMeasurementResult added in v0.2.0 

type TpmMeasurementResult struct {
	Summary          Result          `json:"resultSummary"`
	PcrRecalculation []PcrResult     `json:"pcrRecalculation"` // Result for validation whether the measured PCR values match the provided verifications
	AggPcrQuoteMatch Result          `json:"aggPcrQuoteMatch"` // Result for comparing the aggregated PCR values with the value in the TPM Quote
	QuoteFreshness   Result          `json:"quoteFreshness"`   // Result for comparison of the expected nonce to the one provided in the TPM Quote
	QuoteSignature   SignatureResult `json:"quoteSignature"`   // Results for validation of the TPM Quote Signature and the used certificates
}

TpmMeasurementResults represents the results of the validation of the provided TPM Quote and its comparison to the verifications in the manifests

type TpmParams 

type TpmParams struct {
	Nonce  []byte
	Pcrs   []int
	Certs  TpmCerts
	UseIma bool
	ImaPcr int32
}

TpmParams are Parameters for retrieving TPM measurements: The nonce is embedded into the quote. Pcrs must be set to the PCRs that should be embedded into the quote. Certs represent the AK certificate chain including EK and CA. UseIma species if the kernel's Integrity Measurement Architecture (IMA) should be used and ImaPcr specifies the PCR used by the IMA (kernel config)

type TpmVerification 

type TpmVerification struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Pcr    int    `json:"pcr"`
	Sha256 string `json:"sha256"`
}

TpmVerification represents the JSON attestation report element of type 'TPM Verification'

type Validity 

type Validity struct {
	NotBefore string `json:"notBefore"`
	NotAfter  string `json:"notAfter"`
}

Validity is a helper struct for JSON 'Validity'

type VerificationResult 

type VerificationResult struct {
	Type            string            `json:"type"`
	Success         bool              `json:"raSuccessful"`         // Summarizing value illustrating whether any issues were detected during validation
	SwCertLevel     int               `json:"swCertLevel"`          // Overall certification level for the entire software stack (the minimum of all CertificationLevels in the used manifests)
	FreshnessCheck  Result            `json:"freshnessCheck"`       // Result for comparison of the expected nonce to the one provided in the attestation report
	ReportSignature []SignatureResult `json:"reportSignatureCheck"` // Result for validation of the overall report signature
	CompDescResult  CompDescResult    `json:"companyValidation,omitempty"`
	RtmResult       ManifestResult    `json:"rtmValidation"`
	OsResult        ManifestResult    `json:"osValidation"`
	AppResults      []ManifestResult  `json:"appValidation,omitempty"`
	MeasResult      MeasurementResult `json:"measurementValidation"`
	DevDescResult   DevDescResult     `json:"deviceDescValidation"`
	ProcessingError string            `json:"processingError,omitempty"`  // used to document any processing errors (dependent from provided Attestation Report) which hindered a complete validation
	InternalError   bool              `json:"internalError,omitempty"`    // used to document if internal errors (independent from provided Attestation Report) occured which hindered a complete validation
	PlainAttReport  ArPlain           `json:"validatedAttestationReport"` // The unpacked and validated attestation report content for further processing
}

VerificationResult represents the results of all steps taken during the validation of an attestation report

func Verify added in v0.2.0 

func Verify(arRaw string, nonce, caCertPem []byte, roles *SignerRoles) VerificationResult

Verify verifies an attestation report in full serialized JWS format against the supplied nonce and CA certificate. Verifies the certificate chains of all attestation report elements as well as the measurements against the verifications and the compatibility of software artefacts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.