Skip to main content
Version: v0.13

Trust Framework Overview

The IDK provides a comprehensive trust validation framework for verifying the authenticity and trustworthiness of credentials, issuers, and certificate chains. This is essential for building applications that require high-assurance identity verification.

Why Trust Matters​

In digital identity systems, trust validation answers critical questions:

  • Is the issuer of this credential authorized to issue it?
  • Is the certificate chain valid and properly rooted?
  • Has the credential or certificate been revoked?
  • Does the issuer meet regulatory requirements?

Without proper trust validation, credentials from unauthorized sources could be accepted, undermining the entire identity ecosystem.

Trust Components​

The IDK trust framework consists of several integrated components:

ComponentPurpose
Trust ListsPublished lists of authorized issuers and their metadata
Certificate ValidationX.509 certificate chain verification
Revocation CheckingCRL and OCSP verification for certificate status
Trust PoliciesConfigurable rules for trust decisions

Trust Validation Flow​

Trust Validation Flow

Core Components​

// Access trust components from session
val trustValidator = session.component.trustValidator
val certificateValidator = session.component.certificateValidator
val trustListService = session.component.trustListService

Basic Trust Validation​

// Validate trust for an issuer certificate
val trustResult = trustValidator.validateTrust(
    certificate = issuerCertificate,
    purpose = TrustPurpose.CREDENTIAL_ISSUER
)

when (trustResult) {
    is TrustResult.Trusted -> {
        println("Issuer is trusted")
        println("Trust level: ${trustResult.trustLevel}")
        println("Trust list: ${trustResult.trustListName}")
    }
    is TrustResult.NotTrusted -> {
        println("Issuer is not trusted: ${trustResult.reason}")
    }
    is TrustResult.Unknown -> {
        println("Trust status could not be determined")
    }
}

Trust Purposes​

Different validation contexts require different trust evaluations:

PurposeDescription
CREDENTIAL_ISSUEREntity issuing identity credentials
DOCUMENT_SIGNEREntity signing mDoc documents
TLS_SERVERServer providing TLS/HTTPS
TLS_CLIENTClient authenticating via mTLS
SIGNATUREGeneral document/data signing
ENCRYPTIONKey used for encryption
// Validate for mDoc document signing
val mdocTrust = trustValidator.validateTrust(
    certificate = documentSignerCert,
    purpose = TrustPurpose.DOCUMENT_SIGNER
)

// Validate for credential issuance
val issuerTrust = trustValidator.validateTrust(
    certificate = issuerCert,
    purpose = TrustPurpose.CREDENTIAL_ISSUER
)

Trust Levels​

The framework supports different trust levels:

LevelDescription
HIGHGovernment-approved, heavily audited issuers
MEDIUMCommercially trusted, audited issuers
LOWSelf-asserted or minimally verified issuers
NONENot trusted
// Require minimum trust level
val trustResult = trustValidator.validateTrust(
    certificate = issuerCertificate,
    purpose = TrustPurpose.CREDENTIAL_ISSUER,
    minimumTrustLevel = TrustLevel.MEDIUM
)

if (trustResult is TrustResult.Trusted) {
    // Only accepts HIGH or MEDIUM trust levels
    val level = trustResult.trustLevel
    if (level >= TrustLevel.HIGH) {
        // High assurance credential
    }
}

Trust Anchors​

Configure root trust anchors for certificate validation:

// Configure trust anchors
val trustConfig = TrustConfiguration {
    // Add root CA certificates
    trustAnchors {
        // From file
        certificate(loadCertificate("/path/to/root-ca.pem"))

        // From resource
        certificateResource("certificates/root-ca.pem")

        // PEM string
        certificatePem("""
            -----BEGIN CERTIFICATE-----
            MIICxjCCAa6gAwIBAgIIQx...
            -----END CERTIFICATE-----
        """.trimIndent())
    }

    // Trust IACA certificates for mDoc
    iacaTrustAnchors {
        certificate(loadCertificate("/path/to/iaca-root.pem"))
    }
}

val trustValidator = TrustValidator(trustConfig)

Trust Policies​

Define custom trust policies for specific requirements:

val policy = TrustPolicy {
    name = "Production Policy"

    // Require certificates from specific issuers
    allowedIssuers {
        issuer("CN=Government Root CA, O=Government, C=US")
        issuer("CN=Acme Identity CA, O=Acme Corp, C=US")
    }

    // Require specific certificate extensions
    requiredExtensions {
        extension(OID.EXTENDED_KEY_USAGE)
        extension(OID.KEY_USAGE)
    }

    // Minimum key strength
    minimumKeySize = 2048

    // Required signature algorithms
    allowedSignatureAlgorithms = setOf(
        SignatureAlgorithm.ES256,
        SignatureAlgorithm.ES384,
        SignatureAlgorithm.RS256
    )

    // Revocation checking
    revocationCheck = RevocationCheckPolicy.REQUIRE_VALID
}

val trustValidator = TrustValidator(
    configuration = trustConfig,
    policy = policy
)

Configuration​

Configure trust validation via properties:

# Trust anchors
trust.anchors.path=/path/to/trust-anchors/
trust.anchors.include-system=true

# IACA trust for mDoc
trust.iaca.path=/path/to/iaca-certs/

# Trust lists
trust.lists.etsi.enabled=true
trust.lists.etsi.url=https://trust.example.com/tsl.xml
trust.lists.etsi.refresh-interval-hours=24

# Revocation checking
trust.revocation.enabled=true
trust.revocation.prefer-ocsp=true
trust.revocation.cache-duration-hours=1

# Policy
trust.policy.minimum-key-size=2048
trust.policy.minimum-trust-level=MEDIUM

Next Steps​