]> The Swedish Internet Foundation

stefan.halen@internetstiftelsen.se

Kirei AB

jakob@kirei.se

machine-to-machine trust framework mutual TLS mTLS public key pinning SPKI federation metadata federation This Informational Independent Submission to the RFC Series describes a means to use TLS 1.3 to perform machine-to-machine mutual authentication within federations. This memo is not a standard. It does not modify the TLS protocol in any way, nor does it require changes to common TLS libraries. TLS is specified and standardized by the IETF's TLS Working Group. The framework enables interoperable trust management for federated machine-to-machine communication. It introduces a centrally managed trust anchor and a controlled metadata publication process, ensuring that only authorized members are identifiable within the federation. These mechanisms support unambiguous entity identification and reduce the risk of impersonation, promoting secure and policy-aligned interaction across organizational boundaries.

Introduction This document describes the Mutually Authenticating TLS in Federations (MATF) framework, developed to complement multilateral Security Assertion Markup Language (SAML) federations within the education sector. These federations often rely on just-in-time provisioning, where user accounts are created at first login based on information from the SAML assertion. However, educators need to be able to manage resources and classes before students access the service. MATF bridges this gap by using secure machine-to-machine communication, enabling pre-provisioning of user information with a trust model and metadata structure inspired by SAML federations. MATF is designed specifically for secure authentication in machine- to-machine contexts, such as RESTful APIs (where "RESTful" refers to the Representational State Transfer (REST) architecture) and service-to-service interactions, and is not intended for browser-based authentication. Because its applicability in a browser environment has not been studied, using MATF within browsers is not recommended. Doing so may introduce risks that differ from those typically addressed by standard browser security models. This work is not a product of the IETF, does not represent a standard, and has not achieved community consensus. It aims to address specific federation challenges and provide a framework for secure communication. TLS is specified by the IETF TLS Working Group. TLS 1.3 is defined in . Additional information about the TLS Working Group is available at .

Reserved Words This document is an Informational RFC, which means it offers information and guidance but does not specify mandatory standards. Therefore, the keywords used throughout this document are for informational purposes only and do not imply any specific requirements. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Federation:

A trusted network of entities that adhere to common security policies and standards, using MATF for secure communication.

Federation Member:

An entity that has been approved to join the federation and can leverage MATF for secure communication with other members.

Federation Operator:

The entity responsible for the overall operation and management of the federation, including managing the federation metadata, enforcing security policies, and onboarding new members.

Federation Metadata:

A cryptographically signed document containing information about all entities within the federation.

Metadata Repository:

A centralized repository storing information about all entities within the federation.

Member Metadata:

Information about entities associated with a specific member within the federation.

Member Vetting:

The process of verifying and approving applicants to join the federation, ensuring they meet security and trustworthiness requirements.

Trust Anchor:

The federation's root of trust is established by the public key used to verify federation metadata signatures, which allows participants to confidently rely on the information it contains.

Diverse Design Patterns MATF is designed to be flexible and adaptable to the varying needs of different federations. Federations can differ significantly in terms of size, scope, and security requirements, which makes it challenging to prescribe a one-size-fits-all trust framework and security measures. For instance, in the European Union, Regulation (EU) No 910/2014 (the electronic identification, authentication, and trust services (eIDAS) Regulation) establishes a regulatory framework for electronic identification and trust services for electronic transactions in the internal market. The eIDAS Regulation provides a basis for cross-border recognition of notified electronic identification schemes and for regulated trust services. Similarly, national federations, such as those found in education or healthcare sectors, often have their own specific trust frameworks and security measures tailored to their unique needs. These federations may leverage existing national identification systems or other trusted credentials to establish member identities and ensure secure interactions. Organizations may also set up their own federations, tailored to the specific security requirements and trust models relevant to their context. For example, a private business federation might establish its own vetting processes and trust framework based on the nature of its business and the sensitivity of the data being exchanged. By allowing federations the flexibility to tailor their trust frameworks and security measures, MATF can support a wide range of use cases. This flexibility is crucial for accommodating the diverse requirements and challenges faced by different federations, ensuring a secure and adaptable system for establishing trust and facilitating secure communication.

Trust Model The MATF framework operates on a trust model that is central to its design and functionality. This section outlines the key components of this trust model and its implications for federation members and the federation operator.

Role of the Federation Operator The federation operator plays a critical role in the MATF framework. This entity is responsible for:

• Managing the central trust anchor, which is used to establish trust across different domains within the federation.
• Vetting federation members to ensure they meet the required standards and policies.
• Maintaining and securing the federation metadata, which includes public key pins , issuer certificates, and other essential information.

Additionally, the federation operator SHOULD develop their own threat models to proactively identify potential risks and threats. This process involves examining the operating environment, evaluating both internal and external threats, and understanding how vulnerabilities can be exploited. The goal of the threat model is to enable the federation operator to establish mitigation strategies that address the identified risks. The security and stability of the federation rely on the integrity and competence of the federation operator. Members must be able to fully trust this central authority, as its role is essential to maintaining the federation's reliability and security.

Federation Members' Responsibilities Federation members share the responsibility of maintaining trust and security within the federation.Their responsibilities include:

• Adhering to the federation's security policies and procedures.
• Ensuring the accuracy and timeliness of their metadata submissions.
• Cooperating with the federation operator's vetting and security measures.

By fulfilling these responsibilities, federation members help sustain the trust framework that enables secure and reliable communication within the federation. Federation members submit member metadata to the federation. As part of federation operations, the federation MUST ensure the authenticity and integrity of submitted member metadata and the authenticity of the submitting member.

Chain of Trust Each federation operates within a trust framework that encompasses its own security policies and procedures. This framework is designed to ensure the integrity, authenticity, and confidentiality of communications within the federation. Key components of this framework include:

• Public key pinning and preloading to thwart on-path attacks by rejecting peers whose public key in the presented certificate does not match a pin published in the federation metadata.
• Regular updates and verification of federation metadata to prevent the use of outdated or compromised information.

The federation operator aggregates, signs, and publishes the federation metadata, which combines all members' member metadata along with additional federation-specific information. By placing trust in the federation and its associated federation metadata signature verification key, federation members trust the information contained within the federation metadata. The trust anchor for the federation is established through the federation metadata signature verification key, a critical component requiring secure distribution and verification. To achieve this, the signature verification key material is distributed using a JSON Web Key (JWK) Set , providing a flexible framework for exposing multiple public keys, including the current signature verification key and keys for rollover. This structured approach ensures members can readily access the necessary keys for verification purposes. An additional layer of security is introduced through thumbprint verification , where federation members can independently verify the key's authenticity. This involves comparing the calculated cryptographic thumbprint of the key with a trusted value, ensuring its integrity. Importantly, this verification process can be conducted through channels separate from the JWK Set itself, enhancing security by eliminating reliance on a single distribution mechanism. This trust framework is essential for enabling seamless and secure interoperability across different trust domains within the federation.

Member Vetting To ensure the security and integrity of the MATF framework, a member vetting process is essential. Detailed vetting processes are beyond the scope of this document but can be guided by established frameworks such as eIDAS and eduGAIN. The following are non-normative references to established frameworks:

• eIDAS: The eIDAS regulation can provide guidance for member vetting and identity assurance practices.
• eduGAIN: eduGAIN is an interfederation service connecting identity federations worldwide, primarily within the research and education sector. eduGAIN documentation on participation requirements and federation practices can inform member vetting processes .

Metadata Authenticity Ensuring the authenticity of metadata is necessary for maintaining the security and trustworthiness of the MATF framework. This document specifies mechanisms for protecting and verifying the authenticity of federation metadata, including JWS signing. Operational procedures for authenticating member metadata submissions are outside the scope of this document and are defined by the federation operator or applicable regulatory bodies.

Metadata Repository The MATF metadata repository acts as a central vault, securely storing all information about all participating federation members and their respective entities. This information, known as federation metadata, is presented as a JSON Web Signature (JWS) to ensure its authenticity and integrity. The metadata repository is subject to stringent security measures to safeguard the integrity of the stored information. This MAY involve:

• Member management: The federation operator can centrally enforce security policies and vet new members before they are added to the repository.
• Access controls: Access to repository management functions and member metadata submission endpoints SHOULD be restricted to authorized federation members.
• Regular backups: Robust backup procedures ensure data recovery in case of unforeseen circumstances.

Before member metadata is added to the federation's repository, the submitted metadata MUST undergo a validation process. This process verifies the accuracy, completeness, and validity of the information provided by a member. Metadata that does not pass validation MUST be rejected. The validation process MUST include, at a minimum, the following checks:

• Format validation: The submitted metadata is checked to ensure that it conforms to the schema and format specifications defined in and .
• Unique entity identifier: The submitted metadata is checked to ensure that the entity_id value, as defined in , is not already registered by another member.
• Unique public key pin digests: The submitted metadata is checked to ensure that pins entries, as defined in , do not introduce a digest value that is already registered to a different entity_id. While reuse of the same digest value within the same entity_id is permitted, uniqueness across different entities is REQUIRED to prevent identity collisions and to support the resolution of a unique entity_id from a derived pin, as specified in .
• Issuer certificate checks: The issuer certificates in issuers, as defined in , are checked to ensure that they are syntactically valid, not expired, and use algorithms that meet the federation's security requirements.
• Tag validation: Tags, as defined in , are checked to ensure that they conform to the defined tag syntax. If the federation defines an approved set of tag values, submitted tags are checked to ensure that they are members of that set.

The metadata repository provides a controlled location for storing member metadata and for producing federation metadata for distribution to federation members.

Metadata Submission It is up to the federation, through its governance and operational processes, to determine which channels are provided to members for submitting their metadata to the metadata repository. Members typically have the option to upload the metadata directly to the repository, provided such functionality exists, or to send it to the federation operator through a designated secure channel. If an insecure channel is used, additional measures MUST be taken to verify the authenticity and integrity of the metadata. Such measures may include verifying the checksum of the metadata through another channel. The choice of submission channel may depend on factors such as the federation's guidelines and the preferences of the member.

Maintaining Up-to-Date Metadata In a MATF federation, accurate and current metadata is essential for ensuring secure and reliable communication between members. This necessitates maintaining up-to-date metadata accessible by all members.

• Federation metadata: The federation operator publishes a JWS containing an aggregate of all entity metadata. This JWS serves as the source of truth for information about all members within the federation. Outdated information in the JWS can lead to issues such as failed connections, discovery challenges, and potential security risks.
• Local metadata: Each member maintains a local metadata store containing information about other members within the federation. This information is retrieved from the federation's publicly accessible JWS. Outdated data in the local store can hinder a member's ability to discover and connect with other relevant entities.

The following outlines the procedures for keeping metadata up to date:

• Federation Operator Role: The federation operator plays a crucial role in maintaining data integrity within the federation. Their responsibilities include:
  • Defining rules for metadata management that MUST include, at a minimum, expiration and cache time management.
  • Implementing mechanisms to update the published federation metadata, ensuring it adheres to the expiration time (exp as defined in ) and cache TTL (cache_ttl as defined in ) specifications.
• Member Responsibility: Members must follow the federation's metadata management rules and refresh their local metadata store according to the defined expiration and cache regulations.

By adhering to these responsibilities, the federation ensures that information remains valid for the defined timeframe and that caching mechanisms utilize up-to-date data effectively.

Authentication All communication established within the federation uses TLS 1.3 with mutual authentication. This mechanism ensures the authenticity of both communicating parties, establishing a robust foundation for secure data exchange.

Public Key Pinning MATF implements public key pinning based on . Public key pinning associates one or more public key pins with each federation endpoint. These pins are published in the federation metadata. During a connection, clients and servers extract the public key from the presented certificate and verify that it matches the preconfigured public key pins retrieved from the federation metadata.

Benefits of Public Key Pinning The decision to utilize public key pinning in the MATF framework was driven by several critical factors aimed at enhancing security and ensuring trust.

Interfederation Trust In interfederation environments, where multiple federations need to trust each other, public key pinning remains effective. Members can validate entities in other federations using pins published through shared metadata, ensuring trust across boundaries. Unlike private certificate chains, which can become complex and difficult to manage across multiple federations, public key pinning provides a straightforward mechanism for establishing trust. MATF interfederation addresses this challenge by aggregating metadata from all participating federations into a unified metadata repository. This shared metadata enables secure communication between entities in different federations, ensuring consistent key validation and robust cross-federation trust and security.

Fortifying Security Against Threats Public key pinning provides a robust defense mechanism by directly binding a peer to a specific public key. This ensures that only the designated key is trusted, preventing attackers from exploiting fraudulent certificates. By eliminating reliance on external trust intermediaries, this approach significantly enhances resilience against potential threats.

Use of Self-Signed Certificates The use of self-signed certificates within the federation leverages public key pinning to establish trust. By bypassing external Certificate Authorities (CAs), servers and clients rely on the federation's mechanisms to validate trust. Public key pinning ensures that only the specific self-signed public keys, identified by key pins in the metadata, are trusted.

Revocation In deployments that rely on certificate chains and certificate revocation mechanisms, revocation can be complex and slow. This complexity arises because a certificate that can no longer be trusted, and potentially other certificates within the chain, may need to be revoked and reissued. Public key pinning mitigates this complexity by allowing clients to base trust decisions on pinned public keys rather than on certificate chains. If a public key can no longer be trusted within a MATF federation, the associated pin is removed. Updated metadata is published. The updated metadata includes a new pin corresponding to the public key in the replacement certificate. This approach reduces reliance on certificate revocation mechanisms and shifts the trust relationship to the specific, updated public key identified by its pin.

Pin Discovery and Preloading Peers in the federation obtain public key pins from the federation metadata. These pins serve as preconfigured trust parameters used for validation, as specified in . The federation MUST define discovery rules. These rules describe how peers use federation metadata claims such as organization and tags to identify relevant endpoints and their pins. Before initiating or accepting a connection, a peer MUST preload the pins for the selected or authorized endpoints from its local metadata store. Maintenance of the local metadata store, including refresh behavior and expiry handling, is specified in . To support peer identification, the preloaded state MUST enable mapping from a derived pin to the corresponding entity_id. This may be achieved by maintaining a local index that maps each preloaded pin value to its associated entity_id. A server MAY preload only the pins for clients that satisfy the server's connection policy (for example, based on organization or tags). Pin validation enforces the resulting policy as specified in .

Verification of Received Certificates Upon connection establishment, both endpoints MUST verify that the public key in the presented peer certificate matches a pin published in the federation metadata. This validation MAY be performed by the TLS stack or by application logic. In architectures where an intermediary terminates the TLS session, pin validation MUST be performed by either the intermediary or the application. If the application performs pin validation, the intermediary MUST forward the peer certificate or a derived pin to the application. The application MUST be able to determine the peer entity_id from the forwarded information and the federation metadata. This resolution relies on the client pin digest uniqueness property specified in . If the intermediary performs pin validation, it MUST propagate the peer certificate, the derived pin, or the entity_id to the application to enable authorization. The channel between the intermediary and the application MUST be integrity protected and MUST provide endpoint authentication. Any conveyed certificate, pin, or identity used for this purpose MUST be derived directly from the TLS session. Implementations MUST NOT accept these values from peer-supplied application data. If the implementation permits disabling default CA-based certificate chain validation, it SHOULD do so while still enforcing pin validation. If chain validation is required, the trust anchors used for certificate chain validation MUST be selected from the issuers listed in the federation metadata. If no matching pin is found for a peer, the connection MUST be handled according to .

Failure to Validate A received certificate that fails validation MUST result in the immediate termination of the connection. This includes scenarios where the derived pin does not match any preloaded pin or where the peer identity cannot be resolved. This strict enforcement ensures that only authorized and secure communication channels are established within the federation.

Certificate Rotation To replace a certificate, whether due to expiration or other reasons, the following procedure MUST be followed:

1. Submitting updated metadata: When a certificate is scheduled for rotation, the federation member submits updated metadata that adds the pin for the new public key alongside the already published pins. The federation operator republishes the signed federation metadata aggregate, making the new pin available to all federation members.
2. Propagation period: Federation members MUST refresh their local metadata stores as specified in . The rotating member MUST allow sufficient time for peers to refresh and preload the new pin before switching to the new certificate.
3. Switching to the new certificate: After the propagation period has elapsed, the rotating member updates its TLS stack to present the new certificate. This allows peers that have preloaded the new pin to validate the rotated certificate.
4. Removing the old pin: Following a successful transition, the rotating member MUST submit updated metadata excluding the old pin. The federation operator republishes the aggregate, ensuring that only current public keys remain trusted within the federation.

Implementation Guidelines The placement of pin validation depends on the deployment architecture. For clients, validation is typically performed by the component initiating the TLS connection. For servers using an intermediary, the communication channel between the intermediary and the application MUST be integrity protected to prevent tampering with forwarded peer identity material. When an intermediary propagates peer identity material (for example, the peer certificate, a derived pin, or the entity_id) using HTTP header fields, those header fields are the mechanism used to fulfill the requirements specified in . For each header field name used for this purpose, the intermediary MUST remove any instance of that header field received from the peer and then set the header field value itself. This ensures that the application only processes identity material derived directly from the TLS session, enabling the application to match the peer to the federation metadata and apply authorization policy based on federation metadata claims. Header fields that are not used to convey identity material are unaffected by this requirement. The communication channel between the intermediary and the application MUST provide integrity protection and endpoint authentication to prevent tampering with forwarded peer identity material. Implementations SHOULD, when possible, rely on libraries with built-in support for pinning. libcurl, for example, supports pinning via the CURLOPT_PINNEDPUBLICKEY option. In Python, the cryptography library can extract public keys, and application code can compare the derived pin to a configured value. Go provides crypto/tls and crypto/x509 for certificate inspection and public key extraction. In Java, java.security.cert.X509Certificate enables public key extraction, while java.net.http.HttpClient allows pinning enforcement using a custom SSLContext and TrustManager. The choice of library is left to the discretion of each implementation.

Federation Metadata Federation metadata is published as a JSON Web Signature (JWS) . The payload contains statements about entities of federation members. Metadata is used for authentication and service discovery. A client selects a server based on metadata claims such as organization and tags. To establish a connection, the client uses the base_uri, pins, and, if needed, issuers of the selected server.

Federation Metadata Claims This section defines the set of claims that can be included in metadata.

• iat (REQUIRED) Identifies the time at which the federation metadata was issued.
  • Data Type: Integer
  • Syntax: NumericDate as defined in .
  • Example: 1755514949
• exp (REQUIRED) Identifies the expiration time on or after which the federation metadata is no longer valid. Once the exp time has passed, the metadata MUST be rejected regardless of cache state.
  • Data Type: Integer
  • Syntax: NumericDate as defined in .
  • Example: 1756119888
• iss (REQUIRED) A URI uniquely identifying the issuing federation. This value differentiates federations, prevents ambiguity, and ensures that entities are recognized within their intended context. Verification of the iss claim enables recipients to determine the origin of the information and to establish trust with entities within the identified federation.
  • Data Type: String
  • Syntax: StringOrURI as defined in . In MATF, this value MUST be a URI.
  • Example: "https://federation.example.org"
• version (REQUIRED) Indicates the schema version of the federation metadata. This ensures compatibility between members of the federation by defining a clear versioning mechanism for interpreting metadata.
  • Data Type: String
  • Syntax: The value MUST follow Semantic Versioning (see ).
  • Example: "1.0.0"
• cache_ttl (OPTIONAL) Specifies the duration in seconds for caching downloaded federation metadata, allowing for independent caching outside of specific HTTP configurations. This is particularly useful when the communication mechanism is not based on HTTP. In the event of a metadata publication outage, members can rely on cached metadata until it expires, as indicated by the exp claim in the JWS payload, defined in . Once expired, metadata MUST no longer be trusted. If omitted, a mechanism to refresh metadata MUST still exist to ensure the metadata remains valid.
  • Data Type: Integer
  • Syntax: Integer representing the duration in seconds.
  • Example: 3600
• entities (REQUIRED) Contains the list of entities within the federation.
  • Data Type: Array of Objects
  • Syntax: Each object MUST conform to the entity definition, as specified in .

Entities Metadata contains a list of entities that may be used for communication within the federation. Each entity describes one or more endpoints owned by a member. An entity has the following properties:

• entity_id (REQUIRED) A URI that uniquely identifies the entity. This identifier MUST NOT collide with any other entity_id within the federation or within any other federation that the entity interacts with.
  • Data Type: String
  • Syntax: URI as defined in .
  • Example: "https://example.com"
• organization (OPTIONAL) A name identifying the organization that the entity's metadata represents. The federation operator MUST ensure that a mechanism is in place to verify that the organization claim corresponds to the rightful owner of the information exchanged between nodes. This is crucial for the trust model, ensuring certainty about the identities of the involved parties. The federation operator SHOULD choose an approach that best suits the specific needs and trust model of the federation.
  • Data Type: String
  • Syntax: A name identifying the organization represented by the entity.
  • Example: "Example Org"
• issuers (REQUIRED) A list of certificate issuers allowed to issue certificates for the entity's endpoints. For each issuer, the issuer's root CA certificate MUST be included in the x509certificate property and be encoded using the Privacy-Enhanced Mail (PEM) format. Certificate verification relies on public key pinning, with the list of allowed issuers used only when a certificate chain validation mechanism is unavoidable. For self-signed certificates, the certificate itself acts as its own issuer and MUST be listed as such in the metadata.
  • Data Type: Array of Objects
  • Syntax: Each object contains an issuer certificate encoded as PEM, as specified in . The Base64 content MUST be wrapped so that each line consists of exactly 64 characters, except for the final line. In JSON text, line breaks in the PEM value are represented using the "\n" escape sequence.
  • Example: Issuer truncated for readability.
• servers (OPTIONAL) Contains the list of servers within the entity.
  • Data Type: Array of Objects
  • Syntax: Each object MUST conform to the server definition, as specified in .
• clients (OPTIONAL) Contains the list of clients within the entity.
  • Data Type: Array of Objects
  • Syntax: Each object MUST conform to the client definition, as specified in .

Servers / Clients The entity's servers and clients are listed below.

• description (OPTIONAL) A human-readable text describing the server or client.
  • Data Type: String
  • Syntax: Free-form text describing the server or client.
  • Example: "SCIM Server 1"
• base_uri (REQUIRED for servers, OPTIONAL for clients) The base URL of the server. This claim is REQUIRED for server endpoints. The value MUST be an absolute URI as defined in . The value serves as the base URI for resolving relative references to server resources, as described in .
  • Data Type: String
  • Syntax: An absolute URI as defined in that is used as a URL.
  • Example: "https://scim.example.com/"
• pins (REQUIRED) A list of objects representing public key pins .
  • Data Type: Array of Objects
  • Syntax: A list of objects, where each object represents a single public key pin with the following properties:
    • alg (REQUIRED) The name of the cryptographic hash algorithm. Currently, the RECOMMENDED value is 'sha256'. As more secure algorithms are developed over time, federations should be ready to adopt these newer options for enhanced security.
      • Data Type: String
      • Syntax: The name of the algorithm.
      • Example: "sha256"
    • digest (REQUIRED) The public key of the end-entity certificate, converted to a Subject Public Key Information (SPKI) fingerprint, as specified in . For clients, the digest value MUST be unique across entities in the federation metadata to enable unambiguous identification of the peer. Within the same entity, the same digest value MAY be assigned to multiple clients.
      • Data Type: String
      • Syntax: SPKI fingerprint.
      • Example: "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
  • Example:
• tags (OPTIONAL) A list of strings that describe the endpoint's capabilities.
  • Data Type: Array of Strings
  • Syntax: Strings describing endpoint capabilities.
  • Pattern: ^[a-z0-9]{1,64}$
  • Example: ["scim", "xyzzy"]
  Tags are fundamental for discovery within a federation, aiding both servers and clients in identifying appropriate connections.
  • Server Tags: Tags associated with servers are used by clients to discover servers offering the services they require. Clients can search for servers based on tags that indicate supported protocols or the type of data they handle, enabling discovery of compatible servers.
  • Client Tags: Tags associated with clients are used by servers to identify clients with specific characteristics or capabilities. For instance, a server might only accept connections from clients that support particular protocols. By filtering incoming requests based on these tags, servers can identify suitable clients.
  Federation-Specific Considerations: While tags are tied to individual federations and serve distinct purposes within each, several key considerations are crucial to ensure clarity and promote consistent tag usage:
  • Well-Defined Scope: Each federation MUST establish a clear scope for its tags, detailing their intended use, allowed tag values, associated meanings, and any relevant restrictions. Maintaining a well-defined and readily accessible registry of approved tags is essential for the federation.
  • Validation Mechanisms: Implementing validation mechanisms for tags is highly recommended. This can involve a dedicated operation or service verifying tag validity and compliance with the federation's regulations. Such validation ensures consistency within the federation by preventing the use of unauthorized or irrelevant tags.

Metadata Schema The MATF metadata schema is defined in . This schema specifies the format for describing entities involved in MATF and their associated information.

Example Metadata The following is a non-normative example of a metadata statement. Line breaks in the issuers claim example are for readability only.

Metadata Signing Federation metadata is signed using JWS and published using JWS JSON Serialization according to the general JWS JSON Serialization syntax defined in . Federation metadata signatures are RECOMMENDED to be created using the algorithm ECDSA using P-256 and SHA-256 ("ES256") as defined in . However, to accommodate evolving cryptographic standards, alternative algorithms MAY be used, provided they meet the security requirements of the federation. Federations may need to transition to post-quantum cryptographic algorithms for federation metadata signatures and for endpoint certificate public key types. MATF can accommodate such transitions through key rollover and by updating published pins as new key types are deployed. The following JWS Protected Header parameters are REQUIRED:

• alg (Algorithm) Identifies the algorithm used to generate the JWS signature .
• kid (Key Identifier) Identifies the key in the issuer's key set that was used to generate the JWS signature .

Example Signature Protected Header The following is a non-normative example of a signature protected header.

Example Usage Scenarios The examples in this section are not normative and illustrate the procedures described in Sections and . The following example describes a scenario within the federation "Skolfederation" where MATF is deployed. Both clients and servers are registered members of the federation. In this scenario, clients manage cross-domain user accounts using SS 12000:2018, which is a System for Cross-domain Identity Management (SCIM) extension. + Intermediary +---(E)-->+ App | | | | | | | +-----------+ +--------------+ +-------+]]>

1. Clients and servers retrieve federation metadata and update their local metadata stores as described in .
2. The client selects a server endpoint based on metadata claims and preloads the pins published for that endpoint.
3. If certificate chain validation is performed, the TLS client or intermediary configures its trust store using the issuers listed in the federation metadata for the selected entity.
4. The client initiates a TLS connection to the selected base_uri and presents its client certificate.
5. If an intermediary terminates the TLS session, it forwards identity material derived from the TLS session to the application as described in Sections and .
6. The application maps the derived pin to a matching metadata entry and uses the associated entity_id for identification and authorization.

Client Behavior A certificate is issued for the client. The client's certificate issuer and public key pins are published in the federation metadata. When a client initiates a connection to a remote server (identified by the server's entity_id), the following steps are performed:

1. The client selects a server endpoint from the identified entity's servers list whose tags match the required service capabilities.
2. The client preloads the selected endpoint's pins from its local metadata store. If certificate chain validation is performed, the client also loads the issuers listed for the entity.
3. The client initiates a TLS connection to the selected endpoint using the base_uri and presents its client certificate.
4. The client performs pin validation for the server certificate as described in . This validation may be performed by the TLS stack during the handshake or by application logic after the connection is established, but it completes before any application data is exchanged.
5. If validation succeeds, the client proceeds with application transactions.

Server Behavior To accept inbound connections from a client, the server uses federation metadata to perform pin validation of the public key in the presented client certificate. The federation metadata publishes client public key pins, and for deployments that perform certificate chain validation, the allowed issuers. When the server receives a TLS connection attempt from a remote client, the following steps are performed:

1. The server is configured to request or require a client certificate. If certificate chain validation is performed, the trust store is populated using the issuers published in the federation metadata. Otherwise, the server requests a client certificate without issuer validation (for example, optional_no_ca).
2. The server can prefilter the federation metadata to identify the set of clients it is willing to communicate with and preload only the pins for those clients, as described in .
3. After the TLS handshake completes, the server derives the client's pin from the presented certificate and matches it against the preloaded pins. When a match is found, the server determines the client's entity_id from the corresponding metadata entry.
4. If pin validation succeeds, the server proceeds with application transactions. If pin validation fails, the server terminates the connection.

SPKI Generation The following is an example of how to use OpenSSL to generate a SPKI fingerprint from a PEM-encoded certificate. -pubkey -noout | \ openssl pkey -pubin -outform der | \ openssl dgst -sha256 -binary | \ openssl enc -base64]]>

Curl and Public Key Pinning The following is an example of public key pinning with curl.

Deployments of the MATF Framework The MATF framework has proven its practical value and robustness through successful deployments in several environments.

Skolfederation Moa Skolfederation Moa is a federation designed to secure communication between digital educational resources and schools. MATF was developed to meet Moa's needs and enables secure data exchange for schools, municipalities, educational platforms, and services across Sweden. The community plays a crucial role in this type of federation. Members are active participants, and the federation operator ensures the federation runs smoothly and serves their needs. Moa's success highlights the importance of collaboration, with members and the federation operator working together to maintain trust, security, and interoperability in the education sector. The deployment of MATF in the Swedish education sector has provided several key insights. Maintaining an accurate registry of metadata ownership with reliable contact information is essential for troubleshooting and ensuring accountability. The deployment also demonstrated the importance of setting reasonable expiration times for metadata. Too short an expiration can hinder the ability to implement contingency plans for publishing new metadata during outages. Metadata validation is necessary to maintain a stable federation. While manual validation may be sufficient in the early stages of a federation, it becomes unmanageable as the federation scales. Without an automated validation process, incorrect metadata uploaded by members is likely to go undetected, leading to publication of incorrect metadata. The federation metadata signing private key is required to publish signed federation metadata. In fallback scenarios, federation metadata may be retrieved from an alternate location, but publishing updated federation metadata requires access to the signing private key. Therefore, secure and redundant management of the signing private key is necessary to support fallback mechanisms and reliable publication. Recipients MUST validate the JWS signature using the federation signature verification key before using federation metadata, regardless of where it is obtained.

Swedish National Agency for Education The Swedish National Agency for Education leverages MATF within its digital national test platform to establish a robust authentication mechanism. The platform utilizes an API for client verification prior to secure data transfer to the agency's test service, ensuring the integrity and confidentiality of educational data.

Sambruk's EGIL Sambruk's EGIL , a platform providing digital services to municipalities, has successfully integrated the MATF framework. This deployment demonstrates the framework's adaptability to support a wide range of digital service infrastructures. These deployments highlight the effectiveness of the MATF framework in enhancing security and interoperability within the educational sector.

Security Considerations

Security Risks and Trust Management The security risks associated with the MATF framework are confined to each individual federation. Both the federation operator and federation members share the responsibility of maintaining trust and security. Proper handling of metadata and thorough vetting of members are crucial to sustaining this trust. Deployments that terminate a session at an intermediary and convey identity material to an application introduce a critical trust boundary. If the intermediary is compromised or fails to properly sanitize inbound headers, an attacker could spoof a peer's entity_id. Therefore, intermediaries that convey identity material to an application MUST comply with the requirements in . Implementations SHOULD avoid logging conveyed certificates, pins, or identity values unless required for diagnostics to prevent the accidental exposure of session-specific identity material.

TLS The security considerations for TLS 1.3 are detailed in Section and Appendices , , and of .

Federation Metadata Updates Regularly updating the local copy of federation metadata is essential for accessing the latest information about active entities, current public key pins , and valid issuer certificates. The use of outdated metadata may expose systems to security risks, such as interaction with revoked entities or acceptance of manipulated data.

Verifying the Federation Metadata Signature Ensuring data integrity and security within the MATF framework relies on verifying the signature of downloaded federation metadata. This verification confirms the origin of the metadata by validating the JWS signature using the federation signature verification key trusted by the recipient. It also confirms that the signed content has not been altered by unauthorized parties. By verifying the signature, trust is maintained in the integrity of the information used for validation, including member public key pins and issuer certificates. To achieve a robust implementation, it is important to consider the security aspects outlined in , which describes security considerations related to algorithm selection, key compromise, and signature integrity.

Time Synchronization Maintaining synchronized clocks across all federation members is critical for the security of the MATF framework. Inaccurate timestamps can compromise the validity of digital signatures and certificates, hinder reliable log analysis, and potentially expose the system to time-based attacks. Therefore, all federation members MUST employ methods to ensure their system clocks are synchronized with a reliable time source.

IANA Considerations This document has no IANA actions.

References Normative References Informative References Sambruk Internetstiftelsens Federationer [The Swedish Internet Foundation] Skolverket [Swedish National Agency for Education] commit f8c2e93 European Union eduGAIN

JSON Schema for MATF Metadata The following JSON Schema defines the structure of MATF metadata. It conforms to draft 2020-12 of the JSON Schema standard. Version: 1.0.0

Acknowledgements This project was funded through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310. The authors thank the following people for the detailed review and suggestions:

The authors would also like to thank participants in the EGIL working group for their comments on this specification.