AX.TrustStore.SDK 2.0.0

AstreaX Public Trust Store SDK

This SDK downloads, signature-validates, and parses the AstreaX Public Trust Store payloads, returning typed models for VICAL (ISO/IEC 18013-5 Annex C), proximity RICAL (Annex F), and website RICAL (ISO/IEC 18013-7).

Trust Stores

Setup

Register services in your DI container. AddTrustStoreServices wires IHttpClientFactory, IMemoryCache, and ITrustStoreClient automatically.

var logger = builder.Services.BuildServiceProvider().GetService<ILogger<TrustStoreClient>>();
builder.Services.AddTrustStoreServices(logger);

Usage

Inject ITrustStoreClient and call the method for the trust store you need:

public class MyService
{
 private ITrustStoreClient TrustStoreClient { get; }
 public MyService(ITrustStoreClient trustStoreClient)
 {
 this.TrustStoreClient = trustStoreClient;
 }
 public async Task ValidateMdlAsync(byte[] certificate)
 {
 // Returns a VicalModel — never throws; returns an empty model on failure.
 var vical = await this.TrustStoreClient.GetVicalAsync();
 foreach (var cert in vical.CertificateInfos)
 {
 // cert is a VicalCertificateInfoModel
 Console.WriteLine($"{cert.DisplayName} — {string.Join(", ", cert.DocType)}");
 }
 }
}

All three methods follow the same pattern:

VicalModel vical = await client.GetVicalAsync();
RicalModel rical = await client.GetRicalAsync();
RicalModel webRical = await client.GetWebRicalAsync();

Pass isTestEnvironment: true to target the test endpoints, or override the default 60-minute cache:

var vical = await client.GetVicalAsync(isTestEnvironment: true, cacheExpirationInMinutes: 5);

Model Hierarchy

TrustPayloadBase
├── VicalModel // VICAL (ISO 18013-5 Annex C)
│ └── CertificateInfos: List<VicalCertificateInfoModel>
└── RicalModel // RICAL / WebRICAL (Annex F / ISO 18013-7)
 └── CertificateInfos: List<RicalCertificateInfoModel>
CertificateInfoBase // common to all entries
├── VicalCertificateInfoModel
│ ├── DocType // e.g. ["org.iso.18013.5.1.mDL"]
│ ├── CertificateProfile
│ └── IssuingAuthority
└── RicalCertificateInfoModel
 ├── Type // collision-resistant type identifier
 ├── Name // human-readable CA name
 └── TrustConstraints: List<TrustConstraintModel>

TrustPayloadBase (shared fields)

VicalModel additional fields

RicalModel additional fields

CertificateInfoBase (all entries)

Signature Validation

Each payload is a COSE_Sign1 message. The client:

1. Downloads the .cbor blob over HTTPS.
2. Extracts the signer certificate chain from the x5chain header (header label 33).
3. Validates the chain up to the pinned AstreaX CA certificate (test or prod, selected by isTestEnvironment).
4. Verifies the ECDSA signature with the leaf cert's public key.

If validation fails or the endpoint is unreachable, an empty model is returned — the methods never throw.