Help us shape the future of Go! Take the 2026 Go Developer Survey

dcl

package
v0.8.2 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package dcl is the controller's client of the CSA Distributed Compliance Ledger: the port of matter.js packages/protocol/src/dcl/ at 0ceb202d (ADR 0020 stage 6) — Client is DclClient.ts, CertificateStore the parts of DclCertificateService.ts the attestation check consults (the PAA and CD signer trust store, refreshed daily, and the CRL revocation check of Matter Core §6.2.6.1), OTAVersions the parts of DclOtaUpdateService.ts that answer whether a software version is in the ledger and with which checksum.

Privacy: nothing in this package reaches the network unless the host constructs a Client and hands it over. With one, the ledger learns what the controller asks it: the subject key identifiers of the PAAs, PAIs and CD signers of the devices it attests (CD signers and revocation points are looked up by key identifier, on demand), and the vendor and product ids — and software versions — of the devices it checks for updates. The GitHub development-certificate fallback, which asks api.github.com, is off unless CertificateOptions.FetchGitHubCertificates turns it on. The embedded vendor names (eligibility/vendor_name.go) need no ledger at all.

Only net/http and the standard library are used; the REST shapes are those of DclRestApiTypes.ts.

Offline trust: package snapshot embeds the production PAAs and CD signers of the ledger, fetched with this package's Client by `make update-dcl-snapshot` — a review step like the schema refresh, run by hand and committed after reading the diff, never automatic; its SOURCE file names the ledger, the fetch time, the count per kind and the SHA-256 of every file. attestation.Trust layers it under a CertificateStore. Revocation stays online: the snapshot carries no CRL, and the CRL check is the CertificateStore's alone.

Index

Constants

View Source 
const (
	ProductionURL = "https://on.dcl.csa-iot.org"
	TestNetURL    = "https://on.test-net.dcl.csa-iot.org"
)

The ledger's REST endpoints — matter.js DclConfig.production and DclConfig.test (packages/protocol/src/dcl/DclConfig.ts:17-25 at 0ceb202d).

View Source 
const (
	SourceProduction = "dcl-prod"
	SourceTest       = "dcl-test"
)

Update sources — OtaUpdateSource (DclOtaUpdateService.ts:39).

View Source 
const CodeNotFound = 5

CodeNotFound is the gRPC NOT_FOUND code the ledger answers an absent record with (DclRestApiTypes.ts:20-38, DclErrorCodes.NotFound).

View Source 
const DefaultDownloadTimeout = 5 * time.Minute

DefaultDownloadTimeout bounds an image download — OTA_DOWNLOAD_TIMEOUT, Minutes(5) (DclOtaUpdateService.ts:53).

View Source 
const DefaultTimeout = 5 * time.Second

DefaultTimeout bounds one ledger request — DclClient.ts:39 (DEFAULT_DCL_TIMEOUT = Seconds(5)).

View Source 
const DefaultUpdateInterval = 24 * time.Hour

DefaultUpdateInterval is how often the trust store refreshes — matter.js DclCertificateService's updateInterval default, Days.one (DclCertificateService.ts:345-351).

View Source 
const RevocationTypeCRL = 1

RevocationTypeCRL is RevocationTypeEnum.Crl (packages/types/src/dcl/device-attestation-revocation.ts:9-14).

Variables

View Source 
var DefaultGitHubConfig = GitHubConfig{
	APIURL: "https://api.github.com",
	Owner:  "project-chip", Repo: "connectedhomeip", Branch: "master",
	CertPath:         "credentials/development/paa-root-certs",
	CDSignerCertPath: "credentials/development/cd-certs",
}

DefaultGitHubConfig is DclGithubConfig.defaults (DclConfig.ts:46-52): connectedhomeip's development certificates on master.

View Source 
var ErrCertificateNotFound = errors.New("dcl: certificate not found")

ErrCertificateNotFound is matter.js's MatterDclError "Certificate not found" (DclCertificateService.ts:604-610 at 862ad75f): no certificate with that key identifier, or one the trust policy filters out.

View Source 
var ErrInvalidRevocationSet = errors.New("dcl: invalid revocation set")

ErrInvalidRevocationSet wraps every refusal of ParseRevocationSet and CertificateStore.InstallRevocations (matter.js ImplementationError).

View Source 
var ErrSKIDMismatch = errors.New("dcl: subject key identifier mismatch")

ErrSKIDMismatch is a certificate whose own subject key identifier is not the one its source states for it.

View Source 
var ErrStoreClosed = errors.New("dcl: certificate store closed")

ErrStoreClosed is IsRevoked's answer on a store that is closing or closed — matter.js's ClosedError (DclCertificateService.ts:706-710).

Functions

func CheckTrustStoreCertificate added in v0.7.0 

func CheckTrustStoreCertificate(der []byte, kind Kind, statedSKID string) (*x509.Certificate, error)

CheckTrustStoreCertificate is #parseAndCheckSkid (DclCertificateService.ts: 492-515) for a source outside the store, a snapshot: der parses as kind (parseTrustStoreCertificate, :48-52) and carries statedSKID — hex, colons allowed, any case — as its own subject key identifier, else ErrSKIDMismatch. It returns the parsed certificate.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether err is the ledger's NOT_FOUND answer.

func PEMToDER added in v0.7.0 

func PEMToDER(pem string) ([]byte, error)

PEMToDER is matter.js Pem.asDer for a certificate the ledger returns PEM encoded (Certificate.PEMCert) — packages/general/src/crypto/Pem.ts:35-73.

func VerifyImage 

func VerifyImage(r io.Reader, u SoftwareVersion, log *slog.Logger) (otaimage.Header, error)

VerifyImage reads the whole image r and checks it against the ledger's record u — #verifyUpdate (DclOtaUpdateService.ts:388-424) with OtaImageReader.file (ota/OtaImageReader.ts:65-110): the image parses and carries its payload, the whole-file checksum matches when the ledger states one (its type defaulting to SHA-256, an unsupported type an error), the total size matches the ledger's file size unless the checksum matched, and the header names u's vendor, product and version.

Types

type Certificate 

type Certificate struct {
	// PEMCert is the certificate, PEM encoded.
	PEMCert string `json:"pemCert"`
	// SerialNumber is the serial as a decimal string.
	SerialNumber     string `json:"serialNumber"`
	Issuer           string `json:"issuer"`
	AuthorityKeyID   string `json:"authorityKeyId"`
	RootSubject      string `json:"rootSubject"`
	RootSubjectKeyID string `json:"rootSubjectKeyId"`
	IsRoot           bool   `json:"isRoot"`
	Owner            string `json:"owner"`
	// Subject is the base64 subject DN, SubjectAsText its text form.
	Subject       string `json:"subject"`
	SubjectAsText string `json:"subjectAsText"`
	// SubjectKeyID is colon-separated uppercase hex.
	SubjectKeyID    string `json:"subjectKeyId"`
	CertificateType string `json:"certificateType"`
	// VID is 0 for a PAA not scoped to one vendor.
	VID           uint16 `json:"vid"`
	SchemaVersion int    `json:"schemaVersion"`
}

Certificate is a PAA or PAI record — ProductAttestationDclSchema (packages/types/src/dcl/attestation-certificate.ts:48-154), the fields this module reads.

type CertificateMetadata 

type CertificateMetadata struct {
	Subject       string    `json:"subject,omitempty"`
	SubjectAsText string    `json:"subjectAsText,omitempty"`
	SubjectKeyID  string    `json:"subjectKeyId"`
	SerialNumber  string    `json:"serialNumber"`
	VID           uint16    `json:"vid"`
	IsRoot        bool      `json:"isRoot"`
	IsProduction  bool      `json:"isProduction"`
	Kind          Kind      `json:"kind,omitempty"`
	FetchedAt     time.Time `json:"fetchedAt"`
}

CertificateMetadata is a stored certificate's record — matter.js DclCertificateService.CertificateMetadata (DclCertificateService.ts: 2094-2108).

type CertificateOptions 

type CertificateOptions struct {
	// Client asks the production ledger. nil is matter.js's offline
	// (:2061-2070): no update, no CRL, no certificate fetched on demand —
	// the store holds what Store and AddCertificate gave it.
	Client *Client
	// TestClient asks the test-net ledger when FetchTestCertificates is
	// set; nil is Client's settings against [TestNetURL] (DclConfig.test).
	TestClient *Client
	// FetchTestCertificates also fetches the test-net ledger's roots
	// (fetchTestCertificates, default false).
	FetchTestCertificates bool
	// AcceptTestCertificates trusts test roots as such; nil is
	// FetchTestCertificates (acceptsTestCertificates, :418-420).
	AcceptTestCertificates *bool
	// FetchGitHubCertificates also fetches connectedhomeip's development
	// PAAs and CD signers from GitHub, with FetchTestCertificates. Off by
	// default — matter.js turns it on with fetchTestCertificates
	// (:1000-1001); this module asks no third party unless told to.
	FetchGitHubCertificates bool
	// GitHub is the development-certificate repository; the zero value is
	// [DefaultGitHubConfig].
	GitHub GitHubConfig
	// UpdateInterval is the refresh period; 0 is [DefaultUpdateInterval],
	// a negative one refreshes never (updateInterval null).
	UpdateInterval time.Duration
	// Store keeps the trust store between runs; nil is a [MemoryStore].
	Store Store
	// Clock times the refresh and stamps FetchedAt; nil is the system
	// clock.
	Clock exchange.Clock
	// Logger receives the store's log; nil discards it.
	Logger *slog.Logger
	// Revocations is revocation information from outside the DCL,
	// installed before the first update as InstallRevocations does —
	// matter.js's revocations option (DclCertificateService.ts:328-330).
	Revocations []RevocationSetEntry
}

CertificateOptions configures a CertificateStore — the subset of matter.js DclCertificateService.Options (DclCertificateService.ts: 2016-2071) this port has.

type CertificateStore 

type CertificateStore struct {
	// contains filtered or unexported fields
}

CertificateStore is the controller's DCL trust store — matter.js DclCertificateService (packages/protocol/src/dcl/DclCertificateService.ts at 0ceb202d) for what the attestation check needs: the PAAs and CD signers fetched from the ledger, persisted and refreshed daily, the GitHub development-certificate fallback behind an option, and the CRL revocation check (revocation.go). It implements attestation.PAAStore and attestation.Revocations; commissioner.Context.Attestation takes it.

func OpenCertificateStore 

func OpenCertificateStore(ctx context.Context, opts CertificateOptions) (*CertificateStore, error)

OpenCertificateStore loads the stored trust store, runs the first update and starts the periodic one — the service's construction (DclCertificateService.ts:332-352). A failed update is logged, not returned (update :952-972); a store that cannot be read is an error.

func (*CertificateStore) AcceptsTestCertificates 

func (s *CertificateStore) AcceptsTestCertificates() bool

AcceptsTestCertificates implements attestation.PAAStore — acceptsTestCertificates (:418-420).

func (*CertificateStore) AddCertificate 

func (s *CertificateStore) AddCertificate(ctx context.Context, der []byte, kind Kind, production bool) (bool, error)

AddCertificate puts a PAA or CD signer into the trust store — matter.js addCertificate (:810-840). It reports false when a certificate with the same key identifier is stored already (the store is then unchanged).

func (*CertificateStore) CDSigner 

func (s *CertificateStore) CDSigner(skid []byte) (*ecdsa.PublicKey, bool)

CDSigner implements attestation.PAAStore — getOrFetchCdSigner (:851-891): a stored CD signer, else the production ledger's certificate with that key identifier, stored as a production CD signer.

func (*CertificateStore) Certificate added in v0.7.3 

func (s *CertificateStore) Certificate(skid string, o GetCertificateOptions) (CertificateMetadata, bool)

Certificate is a stored certificate's metadata by subject key identifier — hex, colons allowed, any case — unless the trust policy filters it out. Mirrors matter.js packages/protocol/src/dcl/ DclCertificateService.ts:400-407 (getCertificate) with :375-380 (#normalizeSubjectKeyId).

func (*CertificateStore) CertificateDER added in v0.7.3 

func (s *CertificateStore) CertificateDER(ctx context.Context, skid string, o GetCertificateOptions) ([]byte, error)

CertificateDER is the certificate's DER, ErrCertificateNotFound as CertificateStore.CertificatePEM. A stored certificate that no longer parses is re-fetched once from the ledger; if that fails the stored bytes are returned for the caller's validation to reject. Mirrors matter.js packages/protocol/src/dcl/DclCertificateService.ts:449-480 (getCertificateAsDer).

func (*CertificateStore) CertificatePEM added in v0.7.3 

func (s *CertificateStore) CertificatePEM(skid string, o GetCertificateOptions) (string, error)

CertificatePEM is the certificate as PEM text, ErrCertificateNotFound when the store holds none the trust policy lets through. Mirrors matter.js packages/protocol/src/dcl/DclCertificateService.ts:433-436 (getCertificateAsPem).

func (*CertificateStore) Certificates 

func (s *CertificateStore) Certificates() []CertificateMetadata

Certificates lists every stored certificate's metadata (certificates, :406-409).

func (*CertificateStore) Close 

func (s *CertificateStore) Close()

Close stops the periodic update and waits for a running one — close (:896-906).

func (*CertificateStore) DeleteCertificate added in v0.7.3 

func (s *CertificateStore) DeleteCertificate(ctx context.Context, skid string)

DeleteCertificate removes a certificate from the store; one it does not hold is no error. Mirrors matter.js packages/protocol/src/dcl/ DclCertificateService.ts:797-812 (deleteCertificate).

func (*CertificateStore) GetOrFetchCertificate added in v0.7.3 

func (s *CertificateStore) GetOrFetchCertificate(ctx context.Context, skid string, o GetOrFetchCertificateOptions) (CertificateMetadata, bool)

GetOrFetchCertificate is a certificate's metadata, fetched from the ledger's roots and stored when the store lacks it and is not offline; false when neither has it, the trust policy filters it out or the ledger fails. Mirrors matter.js packages/protocol/src/dcl/ DclCertificateService.ts:747-792 (getOrFetchCertificate).

func (*CertificateStore) InstallRevocations added in v0.7.3 

func (s *CertificateStore) InstallRevocations(entries []RevocationSetEntry) error

InstallRevocations is installRevocations (:640-673): revocation information that did not come from the DCL, trusted as it stands (no signer chain, no CRL signature), held in memory for the life of the store and never persisted. A listed serial is revoked; every other one still goes to the DCL. Nothing is installed unless every entry reads; installing a set twice changes nothing. An entry that names no issuer matches on its key identifier alone.

func (*CertificateStore) InstalledRevocations added in v0.7.3 

func (s *CertificateStore) InstalledRevocations() map[string][]InstalledRevocation

InstalledRevocations is installedRevocations (:675-687): a copy of the installed revocation information by the key identifier it was stated for; the store's own can only be added to, through InstallRevocations.

func (*CertificateStore) IsRevoked 

func (s *CertificateStore) IsRevoked(akid, serial []byte, issuerDN string) (bool, error)

IsRevoked implements attestation.Revocations — isRevoked (:691-726): the CRLs the ledger names for the authority akid, fetched and validated on first use and cached for an hour, list serial (the DER INTEGER content) under the issuer issuerDN (uppercase hex of its Name DER). An offline store, or a lookup that failed, reports not revoked; a lookup that was incomplete is not kept.

func (*CertificateStore) PAA 

func (s *CertificateStore) PAA(skid []byte) (attestation.PAA, bool)

PAA implements attestation.PAAStore: the certificate whose key identifier is skid, test certificates considered — the validator's getCertificate and getCertificateAsDer with considerTestCertificates (DeviceAttestationValidator.ts:235, :269), the self-heal of CertificateStore.CertificateDER included.

func (*CertificateStore) Update 

func (s *CertificateStore) Update(ctx context.Context, force bool) bool

Update fetches the ledger's roots (and, with the options, the test ledger's and GitHub's) — update (:952-972). One update runs at a time; an offline or closed store does nothing. It reports false when the update failed (the failure is logged).

type Client 

type Client struct {
	// BaseURL is the ledger; empty is [ProductionURL].
	BaseURL string
	// HTTPClient sends the requests; nil is http.DefaultClient.
	HTTPClient *http.Client
	// Timeout bounds each request; 0 is [DefaultTimeout].
	Timeout time.Duration
	// Logger receives the client's debug and warning lines; nil discards
	// them.
	Logger *slog.Logger
}

Client reads the ledger's REST API — matter.js DclClient (DclClient.ts:55-299). The zero value asks the production ledger with the default HTTP client and timeout.

func NewClient 

func NewClient(baseURL string) *Client

NewClient returns a client of the ledger at baseURL.

func (*Client) CertificatesBySubjectKeyID 

func (c *Client) CertificatesBySubjectKeyID(ctx context.Context, skid string) ([]Certificate, error)

CertificatesBySubjectKeyID returns every certificate the ledger holds with the key identifier skid (hex, colons allowed) — DclClient. fetchCertificatesBySubjectKeyId (DclClient.ts:140-152): GET /dcl/pki/all-certificates?subjectKeyId=<AA:BB:…>, the groups and certificates of schema version 0. None is an empty list.

func (*Client) ComplianceInfo added in v0.7.3 

func (c *Client) ComplianceInfo(ctx context.Context, vid, pid uint16, softwareVersion uint32, certificationType string) (ComplianceInfo, error)

ComplianceInfo returns the compliance record of a software version for a certification program — DclClient.fetchComplianceInfo (DclClient.ts:229-257): GET /dcl/compliance/compliance-info/{vid}/{pid}/{softwareVersion}/{certificationType}, which must answer that vid, pid, version and program, schema version 0 or 1.

func (*Client) Model 

func (c *Client) Model(ctx context.Context, vid, pid uint16) (DeviceModel, error)

Model returns the device model of vid/pid — DclClient.fetchModelByVidPid (DclClient.ts:171-184): GET /dcl/model/models/{vid}/{pid}, which must answer that vid and pid, schema version 0.

func (*Client) ModelVersion 

func (c *Client) ModelVersion(ctx context.Context, vid, pid uint16, softwareVersion uint32) (SoftwareVersion, error)

ModelVersion returns the record of one software version — DclClient. fetchModelVersionByVidPidSoftwareVersion (DclClient.ts:201-222): GET /dcl/model/versions/{vid}/{pid}/{softwareVersion}, which must answer that vid, pid and version, schema version 0.

func (*Client) ModelVersions 

func (c *Client) ModelVersions(ctx context.Context, vid, pid uint16) ([]uint32, error)

ModelVersions lists the software versions of vid/pid — DclClient. fetchModelVersionsByVidPid (DclClient.ts:186-199): GET /dcl/model/versions/{vid}/{pid}, which must answer that vid and pid, schema version 0.

func (*Client) RevocationPoints 

func (c *Client) RevocationPoints(ctx context.Context) ([]RevocationPoint, error)

RevocationPoints lists every revocation distribution point — DclClient. fetchRevocationDistributionPoints (DclClient.ts:271-280): GET /dcl/pki/revocation-points, paginated under PkiRevocationDistributionPoint, the records of schema version 0.

func (*Client) RevocationPointsByIssuer 

func (c *Client) RevocationPointsByIssuer(ctx context.Context, issuerSKID string) ([]RevocationPoint, error)

RevocationPointsByIssuer lists the revocation distribution points of the issuer with key identifier issuerSKID — DclClient. fetchRevocationDistributionPointsByIssuer (DclClient.ts:285-298): GET /dcl/pki/revocation-points/{issuerSubjectKeyId}; an answer without the record is no point, one of another schema version an error.

func (*Client) RootCertificateBySubject 

func (c *Client) RootCertificateBySubject(ctx context.Context, ref SubjectReference) ([]Certificate, error)

RootCertificateBySubject returns the approved certificates of one root — DclClient.fetchRootCertificateBySubject (DclClient.ts:154-169): GET /dcl/pki/certificates/{subject}/{subjectKeyId}, which must answer the subject and key identifier asked for, schema version 0.

func (*Client) RootCertificates 

func (c *Client) RootCertificates(ctx context.Context) ([]SubjectReference, error)

RootCertificates lists the approved root certificates (PAAs) by subject and key identifier — DclClient.fetchRootCertificateList (DclClient.ts:123-131): GET /dcl/pki/root-certificates, schema version 0.

func (*Client) Vendors added in v0.7.3 

func (c *Client) Vendors(ctx context.Context) ([]Vendor, error)

Vendors lists every vendor record — DclClient.fetchAllVendors (DclClient.ts:262-265): GET /dcl/vendorinfo/vendors, paginated under vendorInfo, the records of schema version 0.

type ComplianceHistoryItem added in v0.7.3 

type ComplianceHistoryItem struct {
	SoftwareVersionCertificationStatus uint8  `json:"softwareVersionCertificationStatus"`
	Date                               string `json:"date"`
	Reason                             string `json:"reason"`
	CDVersionNumber                    uint32 `json:"cDVersionNumber"`
	SchemaVersion                      int    `json:"schemaVersion"`
}

ComplianceHistoryItem is one entry of a compliance record's history — ComplianceHistoryItemDclSchema (device-software-compliance.ts:23-49).

type ComplianceInfo added in v0.7.3 

type ComplianceInfo struct {
	VID                                uint16                  `json:"vid"`
	PID                                uint16                  `json:"pid"`
	SoftwareVersion                    uint32                  `json:"softwareVersion"`
	SoftwareVersionString              string                  `json:"softwareVersionString"`
	CDVersionNumber                    uint32                  `json:"cDVersionNumber"`
	CDCertificateID                    string                  `json:"cDCertificateId"`
	CertificationType                  string                  `json:"certificationType"`
	SpecificationVersion               uint32                  `json:"specificationVersion"`
	SoftwareVersionCertificationStatus uint8                   `json:"softwareVersionCertificationStatus"`
	Date                               string                  `json:"date"`
	Owner                              string                  `json:"owner"`
	History                            []ComplianceHistoryItem `json:"history"`
	CertificationRoute                 string                  `json:"certificationRoute"`
	Reason                             string                  `json:"reason"`
	Transport                          string                  `json:"transport"`
	FamilyID                           string                  `json:"familyId"`
	SupportedClusters                  string                  `json:"supportedClusters"`
	ProgramType                        string                  `json:"programType"`
	ProgramTypeVersion                 string                  `json:"programTypeVersion"`
	ParentChild                        string                  `json:"parentChild"`
	SchemaVersion                      int                     `json:"schemaVersion"`
}

ComplianceInfo is a compliance record — DeviceSoftwareComplianceDclSchema (packages/types/src/dcl/device-software-compliance.ts:63-208). The four fields the specification deprecates are not read, as mapRawComplianceInfo drops them (DclClient.ts:360-381); an unset optional field is "" or 0.

type DeviceModel 

type DeviceModel struct {
	VID                                        uint16 `json:"vid"`
	PID                                        uint16 `json:"pid"`
	DeviceTypeID                               uint32 `json:"deviceTypeId"`
	ProductName                                string `json:"productName"`
	ProductLabel                               string `json:"productLabel"`
	PartNumber                                 string `json:"partNumber"`
	DiscoveryCapabilitiesBitmask               uint32 `json:"discoveryCapabilitiesBitmask"`
	CommissioningCustomFlow                    uint8  `json:"commissioningCustomFlow"`
	CommissioningCustomFlowURL                 string `json:"commissioningCustomFlowUrl"`
	CommissioningModeInitialStepsHint          uint32 `json:"commissioningModeInitialStepsHint"`
	CommissioningModeInitialStepsInstruction   string `json:"commissioningModeInitialStepsInstruction"`
	CommissioningModeSecondaryStepsHint        uint32 `json:"commissioningModeSecondaryStepsHint"`
	CommissioningModeSecondaryStepsInstruction string `json:"commissioningModeSecondaryStepsInstruction"`
	CommissioningFallbackURL                   string `json:"commissioningFallbackUrl"`
	UserManualURL                              string `json:"userManualUrl"`
	SupportURL                                 string `json:"supportUrl"`
	ProductURL                                 string `json:"productUrl"`
	LSFURL                                     string `json:"lsfUrl"`
	LSFRevision                                uint32 `json:"lsfRevision"`
	EnhancedSetupFlowOptions                   uint32 `json:"enhancedSetupFlowOptions"`
	EnhancedSetupFlowTCURL                     string `json:"enhancedSetupFlowTCUrl"`
	EnhancedSetupFlowTCRevision                uint32 `json:"enhancedSetupFlowTCRevision"`
	EnhancedSetupFlowTCDigest                  string `json:"enhancedSetupFlowTCDigest"`
	EnhancedSetupFlowTCFileSize                uint64 `json:"enhancedSetupFlowTCFileSize"`
	MaintenanceURL                             string `json:"maintenanceUrl"`
	ICDUserActiveModeTriggerHint               uint32 `json:"icdUserActiveModeTriggerHint"`
	ICDUserActiveModeTriggerInstruction        string `json:"icdUserActiveModeTriggerInstruction"`
	FactoryResetStepsHint                      uint32 `json:"factoryResetStepsHint"`
	FactoryResetStepsInstruction               string `json:"factoryResetStepsInstruction"`
	Creator                                    string `json:"creator"`
	SchemaVersion                              int    `json:"schemaVersion"`
}

DeviceModel is a device model record — DeviceModelDclSchema (packages/types/src/dcl/device.ts:53-314), the fields with a meaning once DclClient.mapRawDeviceModel (DclClient.ts:337-358) has cleared those that only count when their URL is set.

type Error 

type Error struct{ Message string }

Error is a ledger answer the client cannot use — matter.js MatterDclError (DclClient.ts:42).

func (*Error) Error 

func (e *Error) Error() string

type FileStore 

type FileStore struct {
	// Path is the file.
	Path string
}

FileStore is a Store in the file the host names, written through a temporary file and a rename.

func (FileStore) Load 

func (f FileStore) Load(context.Context) ([]byte, error)

Load implements Store; a missing file is nothing stored.

func (FileStore) Save 

func (f FileStore) Save(_ context.Context, data []byte) error

Save implements Store.

type GetCertificateOptions added in v0.7.3 

type GetCertificateOptions struct {
	// ConsiderTestCertificates also returns test PAAs; nil is
	// [CertificateStore.AcceptsTestCertificates].
	ConsiderTestCertificates *bool
}

GetCertificateOptions is DclCertificateService.GetCertificateOptions (DclCertificateService.ts:2026-2032 at 862ad75f).

type GetOrFetchCertificateOptions added in v0.7.3 

type GetOrFetchCertificateOptions struct {
	GetCertificateOptions
	// IsProduction asks the production ledger, false the test ledger; nil
	// is the production one.
	IsProduction *bool
}

GetOrFetchCertificateOptions is getOrFetchCertificate's options (DclCertificateService.ts:749 at 862ad75f).

type GitHubConfig 

type GitHubConfig struct {
	// APIURL is the GitHub API; empty is https://api.github.com.
	APIURL string
	// Owner, Repo and Branch name the repository.
	Owner, Repo, Branch string
	// CertPath is the directory of the PAA .der files, CDSignerCertPath
	// that of the CD signers.
	CertPath, CDSignerCertPath string
	// Timeout bounds each request; 0 is none, as matter.js's GitHub client
	// without a timeout option (packages/general/src/util/Github.ts:131-133).
	Timeout time.Duration
}

GitHubConfig names the development-certificate repository — matter.js DclGithubConfig (DclConfig.ts:34-53).

type InstalledRevocation added in v0.7.3 

type InstalledRevocation struct {
	// Serials are the revoked serials as canonical uppercase hex, sorted.
	Serials []string
	// IssuerDN is uppercase hex of the issuer Name DER; "" when the entry
	// named none.
	IssuerDN string
}

InstalledRevocation is DclCertificateService.InstalledRevocation (:2128-2132), as CertificateStore.InstalledRevocations reports it.

type Kind 

type Kind string

Kind is the kind of a trust-store entry — DclCertificateService. CertificateKind (DclCertificateService.ts:2089). 

const (
	KindPAA      Kind = "PAA"
	KindCDSigner Kind = "CDSigner"
)

The kinds.

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore is a Store in memory, the default: nothing survives the process.

func (*MemoryStore) Load 

func (m *MemoryStore) Load(context.Context) ([]byte, error)

Load implements Store.

func (*MemoryStore) Save 

func (m *MemoryStore) Save(_ context.Context, data []byte) error

Save implements Store.

type OTAError 

type OTAError struct {
	Message string
	Err     error
}

OTAError is an update check or download that failed — OtaUpdateError (DclOtaUpdateService.ts:33-37).

func (*OTAError) Error 

func (e *OTAError) Error() string

func (*OTAError) Unwrap 

func (e *OTAError) Unwrap() error

type OTAUpdate 

type OTAUpdate struct {
	SoftwareVersion
	Source string
}

OTAUpdate is an applicable software version and the ledger it came from — OtaUpdateInfo (DclOtaUpdateService.ts:43-51).

type OTAVersions 

type OTAVersions struct {
	// Client asks the production ledger; nil asks none.
	Client *Client
	// TestClient asks the test-net ledger; nil asks none.
	TestClient *Client
	// Logger receives the lookups' log; nil discards it.
	Logger *slog.Logger
}

OTAVersions answers an OTA provider's ledger questions — the parts of matter.js DclOtaUpdateService (packages/protocol/src/dcl/ DclOtaUpdateService.ts at 0ceb202d) that do not store images: which software version of a vendor and product the ledger offers over the current one, whether one version is applicable, its image download and the image's verification against the record. The provider's image catalogue stays the host's (cluster/core.OTAImageSource): a host's QueryImage calls OTAVersions.CheckForUpdate, downloads with OTAVersions.Download and checks with VerifyImage.

func (*OTAVersions) CheckForUpdate 

func (o *OTAVersions) CheckForUpdate(ctx context.Context, vid, pid uint16, current uint32, target *uint32) (OTAUpdate, bool)

CheckForUpdate returns the ledger's applicable update of vid/pid over current — checkForUpdate (DclOtaUpdateService.ts:292-386) without the stored images: the production ledger, then the test-net ledger, the highest version of the two. With target set only that version is considered. A failed lookup is logged and finds nothing.

func (*OTAVersions) CheckVersion 

func (o *OTAVersions) CheckVersion(ctx context.Context, c *Client, vid, pid uint16, version, current uint32) (SoftwareVersion, bool, error)

CheckVersion fetches the record of one software version and reports whether it is applicable over current — #checkSpecificVersion (:722-764). An applicable version carries the specification version of its compliance record, else the version record's.

func (*OTAVersions) Download 

func (o *OTAVersions) Download(ctx context.Context, u SoftwareVersion, w io.Writer) error

Download writes the image of u to w — downloadUpdate's network half (:667-709): an http or https OTA URL only, the GET bounded by DefaultDownloadTimeout. The caller verifies the image (VerifyImage) before it serves it.

func (*OTAVersions) IsApplicable 

func (o *OTAVersions) IsApplicable(v SoftwareVersion, current uint32) bool

IsApplicable is #isVersionApplicable (:786-819): a valid version with an https OTA URL whose applicable range holds current. The ledger states both bounds on every record, so a maximum of 0 applies to version 0 only.

func (*OTAVersions) Lookup 

func (o *OTAVersions) Lookup(ctx context.Context, vid, pid uint16, version uint32) (SoftwareVersion, bool, error)

Lookup returns the production ledger's record of one software version — "is this version in the ledger, with which checksum": false when the ledger has none (NOT_FOUND, or an answer for another version).

type ResponseError 

type ResponseError struct {
	// Path is the requested path.
	Path string
	// Code, Message and Details are DclApiErrorResponse
	// (DclRestApiTypes.ts:40-44).
	Code    int
	Message string
	Details []string
	// Err is the cause of a failed request, nil for a ledger error body.
	Err error
}

ResponseError is a request that failed — matter.js MatterDclResponseError (DclClient.ts:45-52): the ledger's error body when it answered one, code 500 with the cause's message when the request itself failed (DclClient.ts:109-119).

func (*ResponseError) Error 

func (e *ResponseError) Error() string

func (*ResponseError) Unwrap 

func (e *ResponseError) Unwrap() error

type RevocationPoint 

type RevocationPoint struct {
	VID uint16
	// PID is 0 when absent.
	PID   uint16
	IsPAA bool
	Label string
	// CRLSignerDelegator and CRLSignerCertificate are PEM; the delegator is
	// "" when absent.
	CRLSignerDelegator   string
	CRLSignerCertificate string
	// IssuerSubjectKeyID is uppercase hex without separators.
	IssuerSubjectKeyID string
	DataURL            string
	// DataFileSize is 0 when absent.
	DataFileSize uint64
	// DataDigest is base64, DataDigestType its IANA hash id; "" and 0
	// when absent.
	DataDigest     string
	DataDigestType uint8
	RevocationType int
	SchemaVersion  int
}

RevocationPoint is a revocation distribution point — DeviceAttestationPkiRevocationDclSchema (packages/types/src/dcl/device-attestation-revocation.ts:24-148).

type RevocationSetEntry added in v0.7.3 

type RevocationSetEntry struct {
	// IssuerSubjectKeyID is the key identifier of the certificate that
	// issued the revoked ones, hex with or without colons.
	IssuerSubjectKeyID string
	// IssuerName is base64 of the issuer's Name DER; "" matches on the key
	// identifier alone.
	IssuerName string
	// RevokedSerialNumbers are hex, with or without colons.
	RevokedSerialNumbers []string
}

RevocationSetEntry is DclCertificateService.RevocationSetEntry (DclCertificateService.ts:2092-2104): one authority's revoked serial numbers, as a revocation set states them.

func ParseRevocationSet added in v0.7.3 

func ParseRevocationSet(data []byte) ([]RevocationSetEntry, error)

ParseRevocationSet is parseRevocationSet (:1767-1800): the per-issuer list of revoked serial numbers connectedhomeip's generate_revocation_set.py writes — that tool's format, not a DCL wire format. Fields beyond the ones InstallRevocations needs are ignored.

type SettingStore 

type SettingStore struct {
	Settings Settings
	// Key is the setting's key.
	Key string
}

SettingStore is a Store under one key of a Settings store.

func (SettingStore) Load 

func (s SettingStore) Load(ctx context.Context) ([]byte, error)

Load implements Store.

func (SettingStore) Save 

func (s SettingStore) Save(ctx context.Context, data []byte) error

Save implements Store.

type Settings 

type Settings interface {
	GetSetting(ctx context.Context, key string) (string, bool, error)
	SetSetting(ctx context.Context, key, value string) error
}

Settings is a string key-value store — *store.Store's GetSetting and SetSetting, which SettingStore keeps the trust store under.

type SoftwareVersion 

type SoftwareVersion struct {
	VID                   uint16
	PID                   uint16
	SoftwareVersion       uint32
	SoftwareVersionString string
	CDVersionNumber       uint32
	Creator               string
	FirmwareInformation   string
	SoftwareVersionValid  bool
	// OTAURL is where the image is, "" when the ledger names none.
	OTAURL string
	// OTAFileSize is the image's size, 0 when unknown.
	OTAFileSize uint64
	// OTAChecksum is the base64 digest of the whole image, OTAChecksumType
	// its IANA Named Information hash id (1 is SHA-256); "" and 0 when the
	// ledger states none.
	OTAChecksum                  string
	OTAChecksumType              uint8
	MinApplicableSoftwareVersion uint32
	MaxApplicableSoftwareVersion uint32
	ReleaseNotesURL              string
	SpecificationVersion         uint32
	SchemaVersion                int
}

SoftwareVersion is a software version record — DeviceSoftwareVersionModelDclSchema (packages/types/src/dcl/device-software-version.ts:20-159).

type Store 

type Store interface {
	// Load returns what Save last stored; nil and no error when nothing is.
	Load(ctx context.Context) ([]byte, error)
	// Save replaces what is stored.
	Save(ctx context.Context, data []byte) error
}

Store keeps the trust store between runs — the "certificates" storage of matter.js's DclCertificateService (DclCertificateService.ts:333-335: the index and one DER per key identifier), here one blob the CertificateStore writes whole.

type SubjectReference 

type SubjectReference struct {
	Subject      string `json:"subject"`
	SubjectKeyID string `json:"subjectKeyId"`
}

SubjectReference names a root certificate — DclPkiRootCertificateSubjectReference (DclRestApiTypes.ts:46-49).

type Vendor added in v0.7.3 

type Vendor struct {
	VendorID             uint16 `json:"vendorID"`
	VendorName           string `json:"vendorName"`
	CompanyLegalName     string `json:"companyLegalName"`
	CompanyPreferredName string `json:"companyPreferredName"`
	VendorLandingPageURL string `json:"vendorLandingPageURL"`
	Creator              string `json:"creator"`
	SchemaVersion        int    `json:"schemaVersion"`
}

Vendor is a vendor record — VendorDclSchema (packages/types/src/dcl/vendor.ts:16-61); the optional preferred name and landing page are "" when unset (DclClient.ts:315-321).

Source Files

View all Source files

Directories

Path Synopsis
Package snapshot is the controller's offline DCL trust set: the production PAAs and Certification Declaration signers of the CSA Distributed Compliance Ledger as DER files with a SOURCE manifest, embedded from data/ and refreshed by `make update-dcl-snapshot` — a review step like the schema refresh, never automatic.
 Package snapshot is the controller's offline DCL trust set: the production PAAs and Certification Declaration signers of the CSA Distributed Compliance Ledger as DER files with a SOURCE manifest, embedded from data/ and refreshed by `make update-dcl-snapshot` — a review step like the schema refresh, never automatic.

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.