verification

Documentation

Overview

Package apiclient/verification implements the interaction model described in https://github.com/veraison/veraison/tree/main/docs/api/challenge-response

Challenge-Response, atomic operation

Using this mode of operation the whole API client exchange is handled atomically through a single invocation of the Run() method.

The user provides the Evidence generation logics by implementing the EvidenceBuilder interface:

type MyEvidenceBuilder struct {
	// build context (e.g., signing key material, claims template, etc.)
}

func (eb MyEvidenceBuilder) BuildEvidence(nonce []byte, accept []string) ([]byte, string, error) {
	for _, ct := range accept {
		if ct == "application/my-evidence-media-type" {
			evidence, err := buildEvidence(nonce, eb)
			if err != nil { ... }

			return evidence, ct, nil
		}
	}

	return nil, "", errors.New("no match on accepted media types")
}

The user then creates a ChallengeResponseConfig object supplying the callback and either an explicit nonce:

cfg := ChallengeResponseConfig{
	Nonce:           []byte{0xde, 0xad, 0xbe, 0xef},
	EvidenceBuilder: MyEvidenceBuilder{...},
	NewSessionURI:   "http://veraison.example/challenge-response/v1/newSession",
}

or just the size of a nonce to be provided by the server side:

cfg := ChallengeResponseConfig{
	NonceSz:         32,
	EvidenceBuilder: MyEvidenceBuilder{...},
	NewSessionURI:   "http://veraison.example/challenge-response/v1/newSession",
}

The user can also supply a custom Client object, for example to appropriately configure the underlying TLS transport:

cfg.Client = &Client{
	HTTPClient: http.Client{
		Transport: myTLSConfig,
	}
}

The user can also request to explicitly delete the session resource at the server instead of letting it expire:

cfg.DeleteSession = true

Then the Run method is invoked on the instantiated ChallengeReponseConfig object to trigger the protocol FSM, hiding any details about the synchronus / async nature of the underlying exchange:

attestationResult, err := cfg.Run()

On success, the Attestation Result, is returned as a JSON string:

if err == nil {
	fmt.Println(string(attestationResult))
}

Challenge-Response, split operation

Using this mode of operation the client is responsible for dealing with each API call separately, invoking the right API method at the right time and place.

In this mode, users does not provide the Evidence generation logics through the EvidenceBuilder interface. Instead, they will need to plug in their Evidence building logics between the call to NewSession() and the subsequent ChallengeResponse().

Similarly to the atomic operation case, users create a ChallengeResponseConfig object supplying either an explicit nonce or the requested nonce size, and any other applicable configuration parameter, e.g., a custom Client:

cfg := ChallengeResponseConfig{
	Nonce:         []byte{0xde, 0xad, 0xbe, 0xef},
	NewSessionURI: "http://veraison.example/challenge-response/v1/newSession",
	Client: &Client{
		HTTPClient: http.Client{
			Transport: myTLSConfig,
		},
	},
}

Same as the atomic model, users can also request to explicitly delete the session resource on the server instead of letting it expire by setting the DeleteSession configuration parameter to true.

The NewSession() method is then invoked on the instantiated ChallengeReponseConfig object to trigger the creation of a new session resource on the server:

newSessionCtx, sessionURI, err := cfg.NewSession()

Users need to use the nonce returned in newSessionCtx.Nonce to trigger a challenge-response session with the Attester and obtain the Evidence. Users will typically make use of the acceptable Evidence formats advertised by the server in newSessionCtx.Accept as an additional input to the protocol with the Attester.

When the Evidence has been obtained, the ChallengeResponse() method can be invoked to submit it to the allocated session with the Verifier that, on success, will return the Attestation Result:

attestationResult, err := cfg.ChallengeResponse(evidence, mediaType, sessionURI)

Index

• type Blob
• type ChallengeResponseConfig
  • func (cfg ChallengeResponseConfig) ChallengeResponse(evidence []byte, mediaType string, uri string) ([]byte, error)
  • func (cfg ChallengeResponseConfig) NewSession() (*ChallengeResponseSession, string, error)
  • func (cfg ChallengeResponseConfig) Run() ([]byte, error)
  • func (cfg *ChallengeResponseConfig) SetClient(client *common.Client) error
  • func (cfg *ChallengeResponseConfig) SetDeleteSession(val bool)
  • func (cfg *ChallengeResponseConfig) SetEvidenceBuilder(evidenceBuilder EvidenceBuilder) error
  • func (cfg *ChallengeResponseConfig) SetNonce(nonce []byte) error
  • func (cfg *ChallengeResponseConfig) SetNonceSz(nonceSz uint) error
  • func (cfg *ChallengeResponseConfig) SetSessionURI(uri string) error
  • func (cfg *ChallengeResponseConfig) SetWrap(val CmwWrap) error
• type ChallengeResponseSession
• type CmwWrap
• type EvidenceBuilder

Types

type Blob

type Blob struct {
	Type  string `json:"type"`
	Value []byte `json:"value"`
}

Blob wraps a base64 encoded value together with its media type (used for evidence in rats-challenge-response-session+json)

type ChallengeResponseConfig

type ChallengeResponseConfig struct {
	Nonce           []byte              // an explicit nonce supplied by the user
	NonceSz         uint                // the size of a nonce to be provided by server
	EvidenceBuilder EvidenceBuilder     // Evidence generation logics supplied by the user
	NewSessionURI   string              // URI of the "/newSession" endpoint
	Client          *common.Client      // HTTP(s) client connection configuration
	DeleteSession   bool                // explicitly DELETE the session object after we are done
	Wrap            CmwWrap             // when set, wrap the supplied evidence as a Conceptual Message Wrapper(CMW)
	Auth            auth.IAuthenticator // when set, Auth supplies the Authorization header for requests
}

ChallengeResponseConfig holds the configuration for one or more challenge-response exchanges

func (ChallengeResponseConfig) ChallengeResponse

func (cfg ChallengeResponseConfig) ChallengeResponse(
	evidence []byte,
	mediaType string,
	uri string,
) ([]byte, error)

ChallengeResponse runs the second portion of the interaction protocol that deals with Evidence submission and retrieval of the associated Attestation Result. On success, the Attestation result in JSON format is returned.

func (ChallengeResponseConfig) NewSession

func (cfg ChallengeResponseConfig) NewSession() (*ChallengeResponseSession, string, error)

NewSession runs the first part of the interaction which deals with session creation, nonce and token format negotiation. On success, the session object is returned together with the URI of the new session endpoint

func (ChallengeResponseConfig) Run

func (cfg ChallengeResponseConfig) Run() ([]byte, error)

Run implements the challenge-response protocol FSM invoking the user callback. On success, the received Attestation Result is returned.

func (*ChallengeResponseConfig) SetClient

func (cfg *ChallengeResponseConfig) SetClient(client *common.Client) error

SetClient sets the HTTP(s) client connection configuration

func (*ChallengeResponseConfig) SetDeleteSession

func (cfg *ChallengeResponseConfig) SetDeleteSession(val bool)

SetDeleteSession sets the DeleteSession parameter using the supplied val

func (*ChallengeResponseConfig) SetEvidenceBuilder

func (cfg *ChallengeResponseConfig) SetEvidenceBuilder(evidenceBuilder EvidenceBuilder) error

SetEvidenceBuilder sets the Evidence Builder callback supplied by the user

func (*ChallengeResponseConfig) SetNonce

func (cfg *ChallengeResponseConfig) SetNonce(nonce []byte) error

SetNonce sets the Nonce supplied by the user

func (*ChallengeResponseConfig) SetNonceSz

func (cfg *ChallengeResponseConfig) SetNonceSz(nonceSz uint) error

SetNonceSz sets the nonce size supplied by the user

func (*ChallengeResponseConfig) SetSessionURI

func (cfg *ChallengeResponseConfig) SetSessionURI(uri string) error

SetSessionURI sets the New Session URI supplied by the user

func (*ChallengeResponseConfig) SetWrap

func (cfg *ChallengeResponseConfig) SetWrap(val CmwWrap) error

SetWrap sets the Wrap parameter using the supplied val

type ChallengeResponseSession

type ChallengeResponseSession struct {
	Nonce    []byte          `json:"nonce"`
	Expiry   string          `json:"expiry"`
	Accept   []string        `json:"accept"`
	Status   string          `json:"status"`
	Evidence Blob            `json:"evidence"`
	Result   json.RawMessage `json:"result"`
}

ChallengeResponseSession models the rats-challenge-response-session+json media type, i.e., the representation of the session resource server-side

type CmwWrap

type CmwWrap int

const (
	NoWrap CmwWrap = iota
	WrapCBOR
	WrapJSON
)

type EvidenceBuilder

type EvidenceBuilder interface {
	BuildEvidence(nonce []byte, accept []string) (evidence []byte, mediaType string, err error)
}

EvidenceBuilder is the interface between the challenge-response protocol FSM and the user. The user is given a nonce and the list of acceptable Evidence formats and is asked to return the serialized Evidence as a byte array together with its media type - or an error if anything goes wrong.