rfc9932.original.xml   rfc9932.xml 
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Process
or - mmark.miek.nl" --> <!DOCTYPE rfc [
<rfc version="3" ipr="trust200902" docName="draft-halen-fedae-03" submissionType <!ENTITY nbsp "&#160;">
="independent" category="info" xml:lang="en" xmlns:xi="http://www.w3.org/2001/XI <!ENTITY zwsp "&#8203;">
nclude"> <!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;">
]>
<rfc version="3" ipr="trust200902" docName="draft-halen-fedae-03" number="9932"
submissionType="independent" category="info" xml:lang="en" xmlns:xi="http://www.
w3.org/2001/XInclude" updates="" obsoletes="" symRefs="true" sortRefs="true" toc
Include="true">
<front> <front>
<title abbrev="MATF">Mutually Authenticating TLS in the context of Federations</ <title abbrev="MATF">Mutually Authenticating TLS in the Context of Federations
title><seriesInfo value="draft-halen-fedae-03" stream="independent" status="info </title>
rmational" name="Internet-Draft"></seriesInfo> <seriesInfo name="RFC" value="9932"/>
<author initials="S." surname="Halén" fullname="Stefan Halén"><organization>The
Swedish Internet Foundation</organization><address><postal><street></street> <author initials="S." surname="Halén" fullname="Stefan Halén">
</postal><email>stefan.halen@internetstiftelsen.se</email> <organization>The Swedish Internet Foundation</organization>
</address></author> <address>
<author initials="J." surname="Schlyter" fullname="Jakob Schlyter"><organization <email>stefan.halen@internetstiftelsen.se</email>
>Kirei AB</organization><address><postal><street></street> </address>
</postal><email>jakob@kirei.se</email> </author>
</address></author>
<date year="2025" month="August" day="27"></date> <author initials="J." surname="Schlyter" fullname="Jakob Schlyter">
<area>Internet</area> <organization>Kirei AB</organization>
<workgroup></workgroup> <address>
<email>jakob@kirei.se</email>
</address>
</author>
<date year="2026" month="March"/>
<keyword>machine-to-machine</keyword>
<keyword>trust framework</keyword>
<keyword>mutual TLS</keyword>
<keyword>mTLS</keyword>
<keyword>public key pinning</keyword>
<keyword>SPKI</keyword>
<keyword>federation metadata</keyword>
<keyword>federation</keyword>
<abstract> <abstract>
<t>This informational independent submission to the RFC series describes a means to use TLS 1.3 to perform machine-to-machine mutual authentication within feder ations. 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 s tandardized by the IETF's TLS working group.</t> <t>This Informational Independent Submission to the RFC Series describes a means to use TLS 1.3 to perform machine-to-machine mutual authentication within feder ations. 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 s tandardized by the IETF's TLS Working Group.</t>
<t>The framework enables interoperable trust management for federated machine-to -machine communication. It introduces a centrally managed trust anchor and a con trolled 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.</t> <t>The framework enables interoperable trust management for federated machine-to -machine communication. It introduces a centrally managed trust anchor and a con trolled 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.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section anchor="introduction"><name>Introduction</name> <section anchor="introduction"><name>Introduction</name>
<t>This document describes the Mutually Authenticating TLS in the context of Fed <t>This document describes the Mutually Authenticating TLS in Federations (MATF)
erations (MATF) framework, developed to complement multilateral SAML federations framework, developed to complement multilateral Security Assertion Markup Langu
within the education sector. These federations often rely on just-in-time provi age (SAML) federations within the education sector. These federations often rely
sioning, where user accounts are created at first login based on information fro on just-in-time provisioning, where user accounts are created at first login ba
m the SAML assertion. However, educators need to be able to manage resources and sed on information from the SAML assertion. However, educators need to be able t
classes before students access the service. MATF bridges this gap by using secu o manage resources and classes before students access the service. MATF bridges
re machine-to-machine communication, enabling pre-provisioning of user informati this gap by using secure machine-to-machine communication, enabling pre-provisio
on using a trust model and metadata structure inspired by SAML federations.</t> ning of user information with a trust model and metadata structure inspired by S
<t>MATF is designed specifically for secure authentication in machine-to-machine AML federations.</t>
contexts, such as RESTful APIs and service-to-service interactions, and is not
intended for browser-based authentication. Because its applicability in a browse <t>MATF is designed specifically for secure authentication in machine-
r environment has not been studied, using MATF within browsers is not recommende to-machine contexts, such as RESTful APIs (where "RESTful" refers to the
d. Doing so may introduce risks that differ from those typically addressed by st Representational State Transfer (REST) architecture) and service-to-service
andard browser security models.</t> 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.</t>
<t>This work is not a product of the IETF, does not represent a standard, and ha s not achieved community consensus. It aims to address specific federation chall enges and provide a framework for secure communication.</t> <t>This work is not a product of the IETF, does not represent a standard, and ha s not achieved community consensus. It aims to address specific federation chall enges and provide a framework for secure communication.</t>
<t>TLS is specified by the IETF TLS Working Group. TLS 1.3 is defined in <xref t arget="RFC8446"></xref>. Additional information about the TLS Working Group is a vailable at <eref target="https://datatracker.ietf.org/wg/tls/about/">https://da tatracker.ietf.org/wg/tls/about/</eref>.</t> <t>TLS is specified by the IETF TLS Working Group. TLS 1.3 is defined in <xref t arget="RFC8446"/>. Additional information about the TLS Working Group is availab le at <eref target="https://datatracker.ietf.org/wg/tls/about/" brackets="angle" />.</t>
<section anchor="reserved-words"><name>Reserved Words</name> <section anchor="reserved-words"><name>Reserved Words</name>
<t>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 an y specific requirements.</t> <t>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 an y specific requirements.</t>
<t>The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, & <t>
quot;SHALL&quot;, &quot;SHALL NOT&quot;, &quot;SHOULD&quot;, &quot;SHOULD NOT&qu The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
ot;, &quot;RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
document are to be interpreted as described in <xref target="RFC2119"></xref>.</ ",
t> "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
be
interpreted as described in BCP&nbsp;14 <xref target="RFC2119"/> <xref
target="RFC8174"/> when, and only when, they appear in all capitals, as
shown here.
</t>
</section> </section>
<section anchor="terminology"><name>Terminology</name> <section anchor="terminology"><name>Terminology</name>
<ul> <dl>
<li>Federation: A trusted network of entities that adhere to common security pol <dt>Federation:</dt><dd>A trusted network of entities that adhere to common se
icies and standards, using MATF for secure communication.</li> curity policies and standards, using MATF for secure communication.</dd>
<li>Federation Member: An entity that has been approved to join the federation a <dt>Federation Member:</dt><dd>An entity that has been approved to join the fe
nd can leverage MATF for secure communication with other members.</li> deration and can leverage MATF for secure communication with other members.</dd>
<li>Federation Operator: The entity responsible for the overall operation and ma <dt>Federation Operator:</dt><dd>The entity responsible for the overall operat
nagement of the federation, including managing the federation metadata, enforcin ion and management of the federation, including managing the federation metadata
g security policies, and onboarding new members.</li> , enforcing security policies, and onboarding new members.</dd>
<li>Federation Metadata: A cryptographically signed document containing informat <dt>Federation Metadata:</dt><dd>A cryptographically signed document containin
ion about all entities within the federation.</li> g information about all entities within the federation.</dd>
<li>Metadata Repository: A centralized repository storing information about all <dt>Metadata Repository:</dt><dd>A centralized repository storing information
entities within the federation.</li> about all entities within the federation.</dd>
<li>Member Metadata: Information about entities associated with a specific membe <dt>Member Metadata:</dt><dd>Information about entities associated with a spec
r within the federation.</li> ific member within the federation.</dd>
<li>Member Vetting: The process of verifying and approving applicants to join th <dt>Member Vetting:</dt><dd>The process of verifying and approving applicants
e federation, ensuring they meet security and trustworthiness requirements.</li> to join the federation, ensuring they meet security and trustworthiness requirem
<li>Trust Anchor: The federation's root of trust is established by the federatio ents.</dd>
n metadata signing key, which verifies the federation metadata and allows partic <dt>Trust Anchor:</dt><dd>The federation's root of trust is established by the
ipants to confidently rely on the information it contains.</li> public key used to verify federation metadata signatures, which allows particip
</ul> ants to confidently rely on the information it contains.</dd>
</dl>
</section> </section>
</section> </section>
<section anchor="diverse-design-patterns"><name>Diverse Design Patterns</name> <section anchor="diverse-design-patterns"><name>Diverse Design Patterns</name>
<t>MATF is designed to be flexible and adaptable to the varying needs of differe nt federations. Federations can differ significantly in terms of size, scope, an d security requirements, which makes it challenging to prescribe a one-size-fits -all trust framework and security measures.</t> <t>MATF is designed to be flexible and adaptable to the varying needs of differe nt federations. Federations can differ significantly in terms of size, scope, an d security requirements, which makes it challenging to prescribe a one-size-fits -all trust framework and security measures.</t>
<t>For instance, in the European Union, the eIDAS (electronic Identification, Au thentication, and trust Services) regulation establishes a framework for electro nic identification and trust services for electronic transactions within the EU. This regulation provides a comprehensive set of standards for secure electronic interactions across member states. National federations within EU member states adhere to these standards, ensuring interoperability and mutual recognition of electronic IDs across different countries.</t> <t>For instance, in the European Union, Regulation (EU) No 910/2014 (the electro nic identification, authentication, and trust services (eIDAS) Regulation) <xref target="eIDAS"/> establishes a regulatory framework for electronic identificati on and trust services for electronic transactions in the internal market. The eI DAS Regulation provides a basis for cross-border recognition of notified electro nic identification schemes and for regulated trust services.</t>
<t>Similarly, national federations, such as those found in education or healthca re sectors, often have their own specific trust frameworks and security measures tailored to their unique needs. These federations may leverage existing nationa l identification systems or other trusted credentials to establish member identi ties and ensure secure interactions.</t> <t>Similarly, national federations, such as those found in education or healthca re sectors, often have their own specific trust frameworks and security measures tailored to their unique needs. These federations may leverage existing nationa l identification systems or other trusted credentials to establish member identi ties and ensure secure interactions.</t>
<t>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 trus t framework based on the nature of its business and the sensitivity of the data being exchanged.</t> <t>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 trus t framework based on the nature of its business and the sensitivity of the data being exchanged.</t>
<t>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 di fferent federations, ensuring a secure and adaptable system for establishing tru st and facilitating secure communication.</t> <t>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 di fferent federations, ensuring a secure and adaptable system for establishing tru st and facilitating secure communication.</t>
</section> </section>
<section anchor="trust-model"><name>Trust Model</name> <section anchor="trust-model"><name>Trust Model</name>
<t>The MATF framework operates on a trust model that is central to its design an d functionality. This section outlines the key components of this trust model an d its implications for federation members and the federation operator.</t> <t>The MATF framework operates on a trust model that is central to its design an d functionality. This section outlines the key components of this trust model an d its implications for federation members and the federation operator.</t>
<section anchor="role-of-the-federation-operator"><name>Role of the Federation O perator</name> <section anchor="role-of-the-federation-operator"><name>Role of the Federation O perator</name>
<t>The federation operator plays a critical role in the MATF framework. This ent ity is responsible for:</t> <t>The federation operator plays a critical role in the MATF framework. This ent ity is responsible for:</t>
<ul> <ul>
<li>Managing the central trust anchor, which is used to establish trust across d ifferent domains within the federation.</li> <li>Managing the central trust anchor, which is used to establish trust across d ifferent domains within the federation.</li>
<li>Vetting federation members to ensure they meet the required standards and po licies.</li> <li>Vetting federation members to ensure they meet the required standards and po licies.</li>
<li>Maintaining and securing the federation metadata, which includes public key pins <xref target="RFC7469"></xref>, issuer certificates, and other essential in formation.</li> <li>Maintaining and securing the federation metadata, which includes public key pins <xref target="RFC7469"/>, issuer certificates, and other essential informat ion.</li>
</ul> </ul>
<t>Additionally, the federation operator SHOULD develop their own threat models to proactively identify potential risks and threats. This process involves exami ning the operating environment, evaluating both internal and external threats, a nd understanding how vulnerabilities can be exploited. The goal of the threat mo del is to enable the federation operator to establish mitigation strategies that address the identified risks.</t> <t>Additionally, the federation operator <bcp14>SHOULD</bcp14> develop their own threat models to proactively identify potential risks and threats. This process involves examining the operating environment, evaluating both internal and exte rnal threats, and understanding how vulnerabilities can be exploited. The goal o f the threat model is to enable the federation operator to establish mitigation strategies that address the identified risks.</t>
<t>The security and stability of the federation rely on the integrity and compet ence of the federation operator. Members must be able to fully trust this centra l authority, as its role is essential to maintaining the federation's reliabilit y and security.</t> <t>The security and stability of the federation rely on the integrity and compet ence of the federation operator. Members must be able to fully trust this centra l authority, as its role is essential to maintaining the federation's reliabilit y and security.</t>
</section> </section>
<section anchor="federation-members-responsibilities"><name>Federation Members' Responsibilities</name> <section anchor="federation-members-responsibilities"><name>Federation Members' Responsibilities</name>
<t>Federation members share the responsibility of maintaining trust and security within the federation. Their responsibilities include:</t> <t>Federation members share the responsibility of maintaining trust and security within the federation.</t><t>Their responsibilities include:</t>
<ul> <ul>
<li>Adhering to the federation's security policies and procedures.</li> <li>Adhering to the federation's security policies and procedures.</li>
<li>Ensuring the accuracy and timeliness of their metadata submissions.</li> <li>Ensuring the accuracy and timeliness of their metadata submissions.</li>
<li>Cooperating with the federation operator's vetting and security measures.</l i> <li>Cooperating with the federation operator's vetting and security measures.</l i>
</ul> </ul>
<t>By fulfilling these responsibilities, federation members help sustain the ove <t>By fulfilling these responsibilities, federation members help sustain the tru
rall trust framework that enables secure and reliable communication within the f st framework that enables secure and reliable communication within the federatio
ederation. Federation members submit member metadata to the federation. Both the n.</t>
authenticity of the submitted member metadata and the submitting member need to <t>Federation members submit member metadata to the federation. As part of feder
be ensured by the federation.</t> ation operations, the federation <bcp14>MUST</bcp14> ensure the authenticity and
integrity of submitted member metadata and the authenticity of the submitting m
ember.</t>
</section> </section>
<section anchor="chain-of-trust"><name>Chain of Trust</name> <section anchor="chain-of-trust"><name>Chain of Trust</name>
<t>Each federation operates within a trust framework that encompasses its own se curity policies and procedures. This framework is designed to ensure the integri ty, authenticity, and confidentiality of communications within the federation. K ey components of this framework include:</t> <t>Each federation operates within a trust framework that encompasses its own se curity policies and procedures. This framework is designed to ensure the integri ty, authenticity, and confidentiality of communications within the federation. K ey components of this framework include:</t>
<ul> <ul>
<li>Public key pinning <xref target="RFC7469"></xref> and preloading to thwart m an-in-the-middle attacks by ensuring validated certificates.</li> <li>Public key pinning <xref target="RFC7469"/> and preloading to thwart on-path attacks by rejecting peers whose public key in the presented certificate does n ot match a pin published in the federation metadata.</li>
<li>Regular updates and verification of federation metadata to prevent the use o f outdated or compromised information.</li> <li>Regular updates and verification of federation metadata to prevent the use o f outdated or compromised information.</li>
</ul> </ul>
<t>The federation operator aggregates, signs, and publishes the federation metad <t>The federation operator aggregates, signs, and publishes the federation metad
ata, which combines all members' member metadata along with additional federatio ata, which combines all members' member metadata along with additional federatio
n-specific information. By placing trust in the federation and its associated si n-specific information. By placing trust in the federation and its associated fe
gning key, federation members trust the information contained within the federat deration metadata signature verification key, federation members trust the infor
ion metadata.</t> mation contained within the federation metadata.</t>
<t>The trust anchor for the federation is established through the federation's s <t>The trust anchor for the federation is established through the federation met
igning key, a critical component requiring secure distribution and verification. adata signature verification key, a critical component requiring secure distribu
To achieve this, the federation's signing key is distributed using a JSON Web K tion and verification. To achieve this, the signature verification key material
ey Set (JWKS) <xref target="RFC7517"></xref>, providing a flexible framework for is distributed using a JSON Web Key (JWK) Set <xref target="RFC7517"/>, providin
exposing multiple keys, including the signing key and keys for rollover. This s g a flexible framework for exposing multiple public keys, including the current
tructured approach ensures members can readily access the necessary keys for ver signature verification key and keys for rollover. This structured approach ensur
ification purposes.</t> es members can readily access the necessary keys for verification purposes.</t>
<t>An additional layer of security is introduced through thumbprint verification <t>An additional layer of security is introduced through thumbprint verification
<xref target="RFC7638"></xref>, where federation members can independently veri <xref target="RFC7638"/>, where federation members can independently verify the
fy the key's authenticity. This involves comparing the calculated cryptographic key's authenticity. This involves comparing the calculated cryptographic thumbp
thumbprint of the key with a trusted value, ensuring its integrity. Importantly, rint of the key with a trusted value, ensuring its integrity. Importantly, this
this verification process can be conducted through channels separate from the J verification process can be conducted through channels separate from the JWK Set
WKS itself, enhancing security by eliminating reliance on a single distribution itself, enhancing security by eliminating reliance on a single distribution mec
mechanism.</t> hanism.</t>
<t>This trust framework is essential for enabling seamless and secure interopera bility across different trust domains within the federation.</t> <t>This trust framework is essential for enabling seamless and secure interopera bility across different trust domains within the federation.</t>
</section> </section>
<section anchor="member-vetting"><name>Member Vetting</name> <section anchor="member-vetting"><name>Member Vetting</name>
<t>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 do cument but can be guided by established frameworks such as eIDAS and eduGAIN.</t > <t>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 do cument but can be guided by established frameworks such as eIDAS and eduGAIN.</t >
<t>The following are non-normative references to established frameworks:</t> <t>The following are non-normative references to established frameworks:</t>
<ul> <ul>
<li><t>eIDAS: The eIDAS regulation establishes a framework for electronic identi fication and trust services within the European Union. It ensures secure and sta ndardized electronic interactions across member states, facilitating mutual reco gnition of electronic IDs. Operators can refer to the eIDAS framework for guidan ce on robust authentication and identity verification processes <xref target="eI DAS"></xref>.</t> <li><t>eIDAS: The eIDAS regulation can provide guidance for member vetting and i dentity assurance practices.</t>
</li> </li>
<li><t>eduGAIN: eduGAIN is an interfederation service connecting identity federa tions worldwide, primarily within the research and education sectors. It ensures high standards of security and interoperability, allowing institutions to colla borate seamlessly. eduGAIN's processes for vetting, as described in <xref target ="eduGAIN"></xref>, can serve as a useful reference.</t> <li><t>eduGAIN: eduGAIN is an interfederation service connecting identity federa tions worldwide, primarily within the research and education sector. eduGAIN doc umentation on participation requirements and federation practices can inform mem ber vetting processes <xref target="eduGAIN"/>.</t>
</li> </li>
</ul> </ul>
</section> </section>
<section anchor="metadata-authenticity"><name>Metadata Authenticity</name> <section anchor="metadata-authenticity"><name>Metadata Authenticity</name>
<t>Ensuring the authenticity of metadata is crucial for maintaining the security and trustworthiness of the MATF framework. The specific mechanisms for ensuring metadata authenticity are beyond the scope of this document and must be defined by the federation or regulatory bodies.</t> <t>Ensuring the authenticity of metadata is necessary for maintaining the securi ty 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 submissi ons are outside the scope of this document and are defined by the federation ope rator or applicable regulatory bodies.</t>
</section> </section>
</section> </section>
<section anchor="metadata-repository"><name>Metadata Repository</name> <section anchor="metadata-repository"><name>Metadata Repository</name>
<t>The MATF metadata repository acts as a central vault, securely storing all in <t>The MATF metadata repository acts as a central vault, securely storing all in
formation about all participating federation members and their respective entiti formation about all participating federation members and their respective entiti
es. This information, known as federation metadata, is presented as a JWS <xref es. This information, known as federation metadata, is presented as a JSON Web S
target="RFC7515"></xref>to ensure its authenticity and integrity.</t> ignature (JWS) <xref target="RFC7515"/> to ensure its authenticity and integrity
<t>The metadata repository is subject to stringent security measures to safeguar .</t>
d the integrity of the stored information. This MAY involve:</t> <t>The metadata repository is subject to stringent security measures to safeguar
d the integrity of the stored information. This <bcp14>MAY</bcp14> involve:</t>
<ul> <ul>
<li>Member Management: The federation operator can centrally enforce security po <li>Member management: The federation operator can centrally enforce security po
licies and vet new members before they are added to the repository.</li> licies and vet new members before they are added to the repository.</li>
<li>Access Controls: Only authorized members within the federation should have a <li>Access controls: Access to repository management functions and member metada
ccess to the repository.</li> ta submission endpoints <bcp14>SHOULD</bcp14> be restricted to authorized federa
<li>Regular Backups: Robust backup procedures ensure data recovery in case of un tion members.</li>
foreseen circumstances.</li> <li>Regular backups: Robust backup procedures ensure data recovery in case of un
foreseen circumstances.</li>
</ul> </ul>
<t>Before member metadata is added to the federation's repository, the submitted metadata MUST undergo a validation process. This process aims to verify the acc uracy, completeness, and validity of the information provided by a member. The v alidation process MUST include, at a minimum but not limited to, the following c hecks:</t> <t>Before member metadata is added to the federation's repository, the submitted metadata <bcp14>MUST</bcp14> undergo a validation process. This process verifie s the accuracy, completeness, and validity of the information provided by a memb er. Metadata that does not pass validation <bcp14>MUST</bcp14> be rejected. The validation process MUST include, at a minimum, the following checks:</t>
<ul> <ul>
<li>Format Validation: The system checks if the submitted metadata adheres to th <li>Format validation: The submitted metadata is checked to ensure that it confo
e defined schema and format specifications.</li> rms to the schema and format specifications defined in <xref target="metadata-sc
<li>Unique Entity ID: Checks are performed to ensure that the entity_id in the s hema"/> and <xref target="json-schema-for-matf-metadata"/>.</li>
ubmitted metadata is not already registered by another member. Each entity withi <li>Unique entity identifier: The submitted metadata is checked to ensure that t
n the federation must have a unique identifier.</li> he <tt>entity_id</tt> value, as defined in <xref target="entities"/>, is not alr
<li>Unique Public Key Pins: Public key pins <xref target="RFC7469"></xref> are u eady registered by another member.</li>
sed to identify client entities within the federation metadata during the connec <li>Unique public key pin digests: The submitted metadata is checked to ensure t
tion validation process. When a server validates a client's TLS connection, it e hat <tt>pins</tt> entries, as defined in <xref target="servers-clients"/>, do no
xtracts the pin from the client's TLS certificate and matches it against entries t introduce a <tt>digest</tt> value that is already registered to a different <t
in the federation metadata. The requirements for pin uniqueness and usage are d t>entity_id</tt>. While reuse of the same <tt>digest</tt> value within the same
etailed in <xref target="servers-clients"></xref>.</li> <tt>entity_id</tt> is permitted, uniqueness across different entities is <bcp14>
<li>Certificate Verification: The issuer certificates listed in the metadata are REQUIRED</bcp14> to prevent identity collisions and to support the resolution of
validated to ensure that the algorithms used in the certificates are well-known a unique <tt>entity_id</tt> from a derived pin, as specified in <xref target="p
and secure, and that the certificates are currently valid and have not expired< in-discovery-and-preloading"/>.</li>
/li> <!-- [rfced]
<li>Tag Validation: Ensures that tags, as defined in <xref target="servers-clien
ts"></xref> in the metadata adhere to the defined tag structure, verifying both Original:
mandatory and optional tags. This process is crucial for maintaining consistency
and preventing unauthorized tags within a federation.</li> * Issuer certificate checks: The issuer certificates in issuers, as
defined in Section 6.1.1, are checked to ensure that they are
syntactically valid, not expired, and use algorithms that meet the
federation's security requirements.
<tt>issuers</tt>
Perhaps:
-->
<li>Issuer certificate checks: The issuer certificates in <tt>issuers</tt>, as d
efined in <xref target="entities"/>, are checked to ensure that they are syntact
ically valid, not expired, and use algorithms that meet the federation's securit
y requirements.</li>
<li>Tag validation: Tags, as defined in <xref target="servers-clients"/>, are ch
ecked to ensure that they conform to the defined tag syntax. If the federation d
efines an approved set of tag values, submitted tags are checked to ensure that
they are members of that set.</li>
</ul> </ul>
<t>The MATF metadata repository serves as the vital foundation for establishing trust and enabling secure communication within a MATF environment. By providing a central, secure, and controlled repository for critical information, the metad ata repository empowers members to confidently discover other trusted entities, and establish secure connections for seamless interaction.</t> <t>The metadata repository provides a controlled location for storing member met adata and for producing federation metadata for distribution to federation membe rs.</t>
<section anchor="metadata-submission"><name>Metadata Submission</name> <section anchor="metadata-submission"><name>Metadata Submission</name>
<t>It is up to the federation to determine which channels should be provided to members for submitting their metadata to the metadata repository. Members typica lly have the option to either upload the metadata directly to the repository, pr ovided such functionality exists, or to send it to the federation operator throu gh a designated secure channel. If an insecure channel is used, additional measu res MUST be taken to verify the authenticity and integrity of the metadata. Such measures may include verifying the checksum of the metadata through another cha nnel. The choice of submission channel may depend on factors such as the federat ion's guidelines and the preferences of the member.</t> <t>It is up to the federation, through its governance and operational processes, to determine which channels are provided to members for submitting their metada ta to the metadata repository. Members typically have the option to upload the m etadata directly to the repository, provided such functionality exists, or to se nd it to the federation operator through a designated secure channel. If an inse cure channel is used, additional measures <bcp14>MUST</bcp14> be taken to verify the authenticity and integrity of the metadata. Such measures may include verif ying the checksum of the metadata through another channel. The choice of submiss ion channel may depend on factors such as the federation's guidelines and the pr eferences of the member.</t>
</section> </section>
<section anchor="maintaining-up-to-date-metadata"><name>Maintaining Up-to-Date M etadata</name> <section anchor="maintaining-up-to-date-metadata"><name>Maintaining Up-to-Date M etadata</name>
<t>In a MATF federation, accurate and current metadata is essential for ensuring secure and reliable communication between members. This necessitates maintainin g up-to-date metadata accessible by all members.</t> <t>In a MATF federation, accurate and current metadata is essential for ensuring secure and reliable communication between members. This necessitates maintainin g up-to-date metadata accessible by all members.</t>
<ul> <ul>
<li>Federation Metadata: The federation operator publishes a JWS containing an a <li>Federation metadata: The federation operator publishes a JWS containing an a
ggregate of all entity metadata. This JWS serves as the source of truth for info ggregate of all entity metadata. This JWS serves as the source of truth for info
rmation about all members within the federation. Outdated information in the JWS rmation about all members within the federation. Outdated information in the JWS
can lead to issues like failed connections, discovery challenges, and potential can lead to issues such as failed connections, discovery challenges, and potent
security risks.</li> ial security risks.</li>
<li>Local Metadata: Each member maintains a local metadata store containing info <li>Local metadata: Each member maintains a local metadata store containing info
rmation about other members within the federation. This information is retrieved rmation about other members within the federation. This information is retrieved
from the federation's publicly accessible JWS. Outdated data in the local store 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 entit can hinder a member's ability to discover and connect with other relevant entit
ies.</li> ies.</li>
</ul> </ul>
<t>The following outlines the procedures for keeping metadata up-to-date:</t> <t>The following outlines the procedures for keeping metadata up to date:</t>
<ul> <ul>
<li><t>Federation Operator Role: The federation operator plays a crucial role in maintaining data integrity within the federation. Their responsibilities includ e:</t> <li><t>Federation Operator Role: The federation operator plays a crucial role in maintaining data integrity within the federation. Their responsibilities includ e:</t>
<ul> <ul>
<li>Defining regulations for metadata management that MUST include, at a minimum <li>Defining rules for metadata management that <bcp14>MUST</bcp14> include, at
but not limited to, expiration and cache time management.</li> a minimum, expiration and cache time management.</li>
<li>Implementing mechanisms to update the published federation metadata, ensurin <li>Implementing mechanisms to update the published federation metadata, ensurin
g it adheres to the expiration time (exp as defined in <xref target="metadata-si g it adheres to the expiration time (<tt>exp</tt> as defined in <xref target="fe
gning"></xref>) and cache TTL (cache_ttl as defined in <xref target="federation- deration-metadata-claims"/>) and cache TTL (<tt>cache_ttl</tt> as defined in <xr
metadata-claims"></xref>) specifications.</li> ef target="federation-metadata-claims"/>) specifications.</li>
</ul></li> </ul></li>
<li><t>Member Responsibility: Members must follow the federation's metadata mana gement regulations and refresh their local metadata store according to the defin ed expiration and cache regulations.</t> <li><t>Member Responsibility: Members must follow the federation's metadata mana gement rules and refresh their local metadata store according to the defined exp iration and cache regulations.</t>
</li> </li>
</ul> </ul>
<t>By adhering to these responsibilities, the Federation ensures that informatio n remains valid for the defined timeframe and that caching mechanisms utilize up -to-date data effectively.</t> <t>By adhering to these responsibilities, the federation ensures that informatio n remains valid for the defined timeframe and that caching mechanisms utilize up -to-date data effectively.</t>
</section> </section>
</section> </section>
<section anchor="authentication"><name>Authentication</name> <section anchor="authentication"><name>Authentication</name>
<t>All communication established within the federation leverages mutual TLS auth entication, as defined in <xref target="RFC8446"></xref>. This mechanism ensures the authenticity of both communicating parties, establishing a robust foundatio n for secure data exchange.</t> <t>All communication established within the federation uses TLS 1.3 <xref target ="RFC8446"/> with mutual authentication. This mechanism ensures the authenticity of both communicating parties, establishing a robust foundation for secure data exchange.</t>
<section anchor="public-key-pinning"><name>Public Key Pinning</name> <section anchor="public-key-pinning"><name>Public Key Pinning</name>
<t>MATF implements public key pinning as specified in <xref target="RFC7469"></x ref>. Public key pinning associates one or more unique public keys with each end point within the federation, stored in the federation metadata. During a connect ion, clients and servers extract the public key from the received certificate an d validate it against the pre-configured public key pins retrieved from the fede ration metadata.</t> <t>MATF implements public key pinning based on <xref target="RFC7469"/>. Public key pinning associates one or more unique public keys with each federation endpo int, which are stored in the federation metadata. During a connection, clients a nd servers extract the public key from the presented certificate and verify that it matches the preconfigured public key pins retrieved from the federation meta data.</t>
<section anchor="benefits-of-public-key-pinning"><name>Benefits of Public Key Pi nning</name> <section anchor="benefits-of-public-key-pinning"><name>Benefits of Public Key Pi nning</name>
<t>The decision to utilize public key pinning in the MATF framework was driven b y several critical factors aimed at enhancing security and ensuring trust:</t> <t>The decision to utilize public key pinning in the MATF framework was driven b y several critical factors aimed at enhancing security and ensuring trust.</t>
<section anchor="interfederation-trust"><name>Interfederation Trust</name> <section anchor="interfederation-trust"><name>Interfederation Trust</name>
<t>In interfederation environments, where multiple federations need to trust eac h other, public key pinning remains effective. Each federation can pin the publi c keys of entities in other federations, ensuring trust across boundaries. Unlik e private certificate chains, which can become complex and difficult to manage a cross multiple federations, public key pinning provides a straightforward mechan ism for establishing trust. MATF interfederation addresses this challenge by agg regating metadata from all participating federations into a unified metadata rep ository. This shared metadata enables secure communication between entities in d ifferent federations, ensuring consistent key validation and robust cross-federa tion trust and security.</t> <t>In interfederation environments, where multiple federations need to trust eac h other, public key pinning remains effective. Members can validate entities in other federations using pins published through shared metadata, ensuring trust a cross boundaries. Unlike private certificate chains, which can become complex an d difficult to manage across multiple federations, public key pinning provides a straightforward mechanism for establishing trust. MATF interfederation addresse s this challenge by aggregating metadata from all participating federations into a unified metadata repository. This shared metadata enables secure communicatio n between entities in different federations, ensuring consistent key validation and robust cross-federation trust and security.</t>
</section> </section>
<section anchor="fortifying-security-against-threats"><name>Fortifying Security Against Threats</name> <section anchor="fortifying-security-against-threats"><name>Fortifying Security Against Threats</name>
<t>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 trus ted, preventing attackers from exploiting fraudulent certificates. By eliminatin g reliance on external trust intermediaries, this approach significantly enhance s resilience against potential threats.</t> <t>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 trus ted, preventing attackers from exploiting fraudulent certificates. By eliminatin g reliance on external trust intermediaries, this approach significantly enhance s resilience against potential threats.</t>
</section> </section>
<section anchor="use-of-self-signed-certificates"><name>Use of Self-Signed Certi ficates</name> <section anchor="use-of-self-signed-certificates"><name>Use of Self-Signed Certi ficates</name>
<t>The use of self-signed certificates within the federation leverages public ke y pinning to establish trust. By bypassing external CAs, servers and clients rel y on the federation's mechanisms to validate trust. Public key pinning ensures t hat only the specific self-signed public keys, identified by key pins in the met adata, are trusted.</t> <t>The use of self-signed certificates within the federation leverages public ke y pinning to establish trust. By bypassing external Certificate Authorities (CAs ), servers and clients rely on the federation's mechanisms to validate trust. Pu blic key pinning ensures that only the specific self-signed public keys, identif ied by key pins in the metadata, are trusted.</t>
</section> </section>
<section anchor="revocation"><name>Revocation</name> <section anchor="revocation"><name>Revocation</name>
<t>If any certificate in a certificate chain is compromised, the revocation proc <t>In deployments that rely on certificate chains and certificate revocation mec
ess can be complex and slow. This complexity arises because not only the comprom hanisms, revocation can be complex and slow. This complexity arises because a ce
ised certificate but potentially multiple certificates within rtificate that can no longer be trusted, and potentially
the chain might need to be revoked and reissued. Public key pinning mitigates th other certificates within the chain, may need to be revoked and reissued. Public
is complexity by allowing clients to explicitly trust a specific public key, the key pinning mitigates this complexity by allowing clients to base trust decisio
reby reducing dependency on the entire certificate chain's integrity.</t> ns on pinned public keys rather than on certificate chains.</t>
<t>If a leaf certificate is compromised within a MATF federation, the revocation <t>If a public key can no longer be trusted within a MATF federation, the associ
process involves removing the pin associated with the compromised certificate a ated pin is removed. Updated metadata is published. The updated metadata include
nd publishing updated metadata that includes a new pin corresponding to the repl s a new pin corresponding to the public key in the replacement certificate. This
acement certificate. This approach eliminates reliance on traditional certificat approach reduces reliance on certificate revocation mechanisms and shifts the t
e revocation mechanisms and shifts the trust relationship to the specific, updat rust relationship to the specific, updated public key identified by its pin.</t>
ed public key identified by its pin.</t>
</section> </section>
</section> </section>
</section> </section>
<section anchor="pin-discovery-and-preloading"><name>Pin Discovery and Preloadin g</name> <section anchor="pin-discovery-and-preloading"><name>Pin Discovery and Preloadin g</name>
<t>Peers in the federation retrieve these unique public key pins, serving as pre <t>Peers in the federation obtain public key pins from the federation metadata.
-configured trust parameters, from the federation metadata. The federation MUST These pins serve as preconfigured trust parameters used for validation, as speci
facilitate the discovery process, allowing peers to identify the relevant pins f fied in <xref target="verification-of-received-certificates"/>.</t>
or each endpoint. Information such as organization, tags, and descriptions withi <t>The federation <bcp14>MUST</bcp14> define discovery rules. These rules descr
n the federation metadata supports this discovery.</t> ibe how peers use federation metadata claims such as organization and tags to id
<t>Before initiating any connection, clients and servers MUST preload the design entify relevant endpoints and their pins.</t>
ated pins from the federation metadata. This aligns with the principle described <t>Before initiating or accepting a connection, a peer <bcp14>MUST</bcp14> prelo
in Section 2.7 of <xref target="RFC7469"></xref>, which introduces optional sou ad the pins for the selected or authorized endpoints from its local metadata sto
rces for pinning information, with the federation metadata serving as one such s re. Maintenance of the local metadata store, including refresh behavior and expi
ource. Preloading pins restricts connections to endpoints with matching public k ry handling, is specified in <xref target="maintaining-up-to-date-metadata"/>.</
eys, mitigating the risks posed by fraudulent certificates.</t> t>
<t>To support peer identification, the preloaded state <bcp14>MUST</bcp14> enabl
e mapping from a derived pin to the corresponding entity_id. This may be achieve
d by maintaining a local index that maps each preloaded pin value to its associa
ted <tt>entity_id</tt>.</t>
<t>A server <bcp14>MAY</bcp14> preload only the pins for clients that satisfy th
e server's connection policy (for example, based on <tt>organization</tt> or <tt
>tags</tt>). Pin validation enforces the resulting policy as specified in <xref
target="verification-of-received-certificates"/>.</t>
</section> </section>
<section anchor="verification-of-received-certificates"><name>Verification of Re ceived Certificates</name> <section anchor="verification-of-received-certificates"><name>Verification of Re ceived Certificates</name>
<t>Upon connection establishment, both endpoints, client and server, must either <t>Upon connection establishment, both endpoints <bcp14>MUST</bcp14> verify that
leverage public key pinning or validate the received certificate against the pu the public key in the presented peer certificate matches a pin published in the
blished pins. Additionally, the federation metadata contains issuer information, federation metadata. This validation <bcp14>MAY</bcp14> be performed by the TLS
which implementations MAY optionally use to verify certificate issuers. This st stack or by application logic.</t>
ep remains at the discretion of each individual implementation.</t> <t>In architectures where an intermediary terminates the TLS session, pin valida
<t>In scenarios where a TLS session terminates independent of the application (e tion <bcp14>MUST</bcp14> be performed by either the intermediary or the applicat
.g., via a reverse proxy), the termination point can utilize optional untrusted ion. If the application performs pin validation, the intermediary <bcp14>MUST</b
TLS client certificate authentication or validate the certificate issuer itself. cp14> forward the peer certificate or a derived pin to the application. The appl
Depending on the specific implementation, pin validation can then be deferred t ication <bcp14>MUST</bcp14> be able to determine the peer <tt>entity_id</tt> fro
o the application itself, assuming the peer certificate is appropriately transfe m the forwarded information and the federation metadata. This resolution relies
rred (e.g., via an HTTP header).</t> on the client pin digest uniqueness property specified in <xref target="servers-
clients"/>.</t>
<t>If the intermediary performs pin validation, it <bcp14>MUST</bcp14> propagate
the peer certificate, the derived pin, or the <tt>entity_id</tt> to the applica
tion to enable authorization.</t>
<t>The channel between the intermediary and the application MUST be integrity pr
otected and <bcp14>MUST</bcp14> provide endpoint authentication.</t>
<t>Any conveyed certificate, pin, or identity used for this purpose <bcp14>MUST<
/bcp14> be derived directly from the TLS session. Implementations <bcp14>MUST NO
T</bcp14> accept these values from peer-supplied application data.</t>
<t>If the implementation permits disabling default CA-based certificate chain va
lidation, it <bcp14>SHOULD</bcp14> do so while still enforcing pin validation. I
f chain validation is required, the trust anchors used for certificate chain val
idation <bcp14>MUST</bcp14> be selected from the issuers listed in the federatio
n metadata.</t>
<t>If no matching pin is found for a peer, the connection <bcp14>MUST</bcp14> be
handled according to <xref target="failure-to-validate"/>.</t>
</section> </section>
<section anchor="failure-to-validate"><name>Failure to Validate</name> <section anchor="failure-to-validate"><name>Failure to Validate</name>
<t>A received certificate that fails validation MUST result in the immediate ter mination of the connection. This strict enforcement ensures that only authorized and secure communication channels are established within the federation.</t> <t>A received certificate that fails validation <bcp14>MUST</bcp14> result in th e immediate termination of the connection. This includes scenarios where the der ived pin does not match any preloaded pin or where the peer identity cannot be r esolved. This strict enforcement ensures that only authorized and secure communi cation channels are established within the federation.</t>
</section> </section>
<section anchor="certificate-rotation"><name>Certificate Rotation:</name> <section anchor="certificate-rotation"><name>Certificate Rotation</name>
<t>To replace a certificate, whether due to expiration or other reasons, the fol <t>To replace a certificate, whether due to expiration or other reasons, the fol
lowing procedure must be followed:</t> lowing procedure <bcp14>MUST</bcp14> be followed:</t>
<ol> <ol>
<li>Publishing New Metadata: When a certificate needs to be changed, federation <li>Submitting updated metadata. When a certificate is scheduled for rotation, t
members publish new metadata containing the pin (SHA256 thumbprint) of the new p he federation member submits updated metadata that adds the <tt>pin</tt> for the
ublic key. This ensures that the new pin is available to all federation members. new public key alongside the already published <tt>pins</tt>. The federation op
</li> erator republishes the signed federation metadata aggregate, making the new pin
<li>Propagation Period: Allow time for the updated metadata to propagate through available to all federation members.</li>
out the federation before switching to the new certificate. This overlap period <li>Propagation period. Federation members <bcp14>MUST</bcp14> refresh their loc
ensures that all nodes recognize the new pin and avoid connection issues.</li> al metadata stores as specified in <xref target="maintaining-up-to-date-metadata
<li>Switching to the New Certificate: After ensuring the new metadata has propag "/>. The rotating member <bcp14>MUST</bcp14> allow sufficient time for peers to
ated, members switch to the new certificate in their TLS stack.</li> refresh and preload the new pin before switching to the new certificate.</li>
<li>Removing Old Pin: After successfully switching to the new certificate, membe <li>Switching to the new certificate. After the propagation period has elapsed,
rs must publish updated metadata that excludes the old pin. This final step ensu the rotating member updates its TLS stack to present the new certificate. This a
res that only the current public keys are trusted.</li> llows peers that have preloaded the new pin to validate the rotated certificate.
</li>
<li>Removing the old pin. Following a successful transition, the rotating member
<bcp14>MUST</bcp14> submit updated metadata excluding the old pin. The federati
on operator republishes the aggregate, ensuring that only current public keys re
main trusted within the federation.</li>
</ol> </ol>
</section> </section>
<section anchor="implementation-guidelines"><name>Implementation Guidelines</nam e> <section anchor="implementation-guidelines"><name>Implementation Guidelines</nam e>
<t>Public key validation MUST always be enforced, either through direct pinning <t>The placement of pin validation depends on the deployment architecture. For c
or by deferring validation to the application.</t> lients, validation is typically performed by the component initiating the TLS co
<t>For clients, public key validation typically occurs within the application ha nnection. For servers using an intermediary, the communication channel between t
ndling the TLS session, either by enforcing direct pinning or by extracting and he intermediary and the application <bcp14>MUST</bcp14> be integrity protected t
validating the public key against the published pins.</t> o prevent tampering with forwarded peer identity material.</t>
<t>For servers, validation depends on deployment. If the application terminates <t>When an intermediary propagates peer identity material (for example, the peer
the TLS session, it performs direct pinning or extracts and validates the public certificate, a derived pin, or the <tt>entity_id</tt>) using HTTP header fields
key. If a reverse proxy terminates the TLS session, it can enforce direct pinni , those header fields are the mechanism used to fulfill the requirements specifi
ng or forward the certificate to the application (e.g., via an HTTP header) for ed in <xref target="verification-of-received-certificates"/>. For each header fi
validation.</t> eld name used for this purpose, the intermediary <bcp14>MUST</bcp14> remove any
<t>Implementations SHOULD, when possible, rely on libraries with native support instance of that header field received from the peer and then set the header fie
for pinning. Libcurl, for example, supports pinning via the PINNEDPUBLICKEY opti ld value itself. This ensures that the application only processes identity mater
on. In Python, the cryptography library can extract public keys, while the reque ial derived directly from the TLS session, enabling the application to match the
sts package together with urllib3 can intercept certificates. Go provides crypto peer to the federation metadata and apply authorization policy based on federat
/tls and crypto/x509 for certificate inspection and public key extraction. In Ja ion metadata claims. Header fields that are not used to convey identity material
va, java.security.cert.X509Certificate enables public key extraction, while java are unaffected by this requirement. The communication channel between the inter
.net.http.HttpClient allows pinning enforcement using a custom SSLContext and Tr mediary and the application MUST provide integrity protection and endpoint authe
ustManager. The choice of library is left to the discretion of each implementati ntication to prevent tampering with forwarded peer identity material.</t>
on.</t> <t>Implementations <bcp14>SHOULD</bcp14>, when possible, rely on libraries with
<t>If bypassing standard CA validation is possible, it SHOULD be done. If not, t built-in support for pinning. libcurl, for example, supports pinning via the CUR
he issuers listed in the federation metadata MUST be used as the trust store to LOPT_PINNEDPUBLICKEY option. In Python, the cryptography library can extract pub
validate certificate issuers while still enforcing key pinning. Without issuer v lic keys, and application code can compare the derived pin to a configured value
alidation against issuers in metadata, self-signed certificates would not be acc . Go provides crypto/tls and crypto/x509 for certificate inspection and public k
epted. These mechanisms ensure compatibility with existing TLS infrastructure wh ey extraction. In Java, java.security.cert.X509Certificate enables public key ex
ile maintaining strict security guarantees.</t> traction, while java.net.http.HttpClient allows pinning enforcement using a cust
om SSLContext and TrustManager. The choice of library is left to the discretion
of each implementation.</t>
</section> </section>
</section> </section>
<section anchor="federation-metadata"><name>Federation Metadata</name> <section anchor="federation-metadata"><name>Federation Metadata</name>
<t>Federation metadata is published as a JWS <xref target="RFC7515"></xref>. The <t>Federation metadata is published as a JSON Web Signature (JWS) <xref target="
payload contains statements RFC7515"/>. The payload contains statements about entities of federation members
about federation members entities.</t> .</t>
<t>Metadata is used for authentication and service discovery. A client selects a <t>Metadata is used for authentication and service discovery. A client selects a
server based on metadata claims (e.g., organization, tags). The client then use server based on metadata claims, such as <tt>organization</tt> and <tt>tags</tt
s the selected server claims base_uri, pins and if needed issuers to establish a >. To establish a connection, the client uses the <tt>base_uri</tt>, <tt>pins</t
connection.</t> t>, and, if needed, <tt>issuers</tt> of the selected server.</t>
<t>Upon receiving a connection, a server validates the received client certifica
te using the client's published pins. Server MAY also check other claims such as
organization and tags to determine if the connection is accepted or terminated.
</t>
<section anchor="federation-metadata-claims"><name>Federation Metadata Claims</n ame> <section anchor="federation-metadata-claims"><name>Federation Metadata Claims</n ame>
<t>This section defines the set of claims that can be included in metadata.</t> <t>This section defines the set of claims that can be included in metadata.</t>
<ul> <ul>
<li><t>iat (REQUIRED)</t> <li><t>iat (<bcp14>REQUIRED</bcp14>)</t>
<t>Identifies the time at which the federation metadata was issued.</t> <t>Identifies the time at which the federation metadata was issued.</t>
<ul>
<ul> <li>Data Type: Integer</li>
<li>Data Type: Integer</li> <li>Syntax: NumericDate as defined in <xref target="RFC7519" sectionFormat="
<li>Syntax: NumericDate as defined in <xref target="RFC7519"></xref>, Section 4. comma" section="4.1.6"/>.</li>
1.6</li> <li>Example: <tt>1755514949</tt></li>
<li>Example: <tt>1755514949</tt></li> </ul></li>
</ul></li> <li><t>exp (<bcp14>REQUIRED</bcp14>)</t>
<li><t>exp (REQUIRED)</t> <t>Identifies the expiration time on or after which the federation metadata is
<t>Identifies the expiration time on or after which the federation metadata is n no longer valid. Once the <tt>exp</tt> time has passed, the metadata
o longer valid. Once the exp time has passed, the metadata MUST be rejected rega <bcp14>MUST</bcp14> be rejected regardless of cache state.</t>
rdless of cache state.</t>
<ul> <ul>
<li>Data Type: Integer</li> <li>Data Type: Integer</li>
<li>Syntax: NumericDate as defined in <xref target="RFC7519"></xref>, Section 4. <li>Syntax: NumericDate as defined in <xref target="RFC7519" sectionFormat="co
1.4</li> mma" section="4.1.4"/>.</li>
<li>Example: <tt>1756119888</tt></li> <li>Example: <tt>1756119888</tt></li>
</ul></li> </ul></li>
<li><t>iss (REQUIRED)</t> <li><t>iss (<bcp14>REQUIRED</bcp14>)</t>
<t>A URI uniquely identifying the issuing federation. This value differentiates <t>A URI uniquely identifying the
federations, prevents ambiguity, and ensures that entities are recognized within issuing federation. This value differentiates federations, prevents
their intended context. Verification of the iss claim enables recipients to det ambiguity, and ensures that entities are recognized within their intended
ermine the origin of the information and to establish trust with entities within context. Verification of the <tt>iss</tt> claim enables recipients to determine
the identified federation.</t> the
origin of the information and to establish trust with entities within the
identified federation.</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: URI, as defined in <xref target="RFC7519"></xref>, Section 4.1.1</li <li>Syntax: StringOrURI as defined in <xref target="RFC7519" sectionFormat="co
> mma" section="4.1.1"/>. In MATF, this value <bcp14>MUST</bcp14> be a URI.</li>
<li>Example: <tt>&quot;https://federation.example.org&quot;</tt></li> <li>Example: <tt>"https://federation.example.org"</tt></li>
</ul></li> </ul></li>
<li><t>version (REQUIRED)</t> <li><t>version (<bcp14>REQUIRED</bcp14>)</t>
<t>Indicates the schema version of the federation metadata. This ensures compati bility between members of the federation by defining a clear versioning mechanis m for interpreting metadata.</t> <t>Indicates the schema version of the federation metadata. This ensures compati bility between members of the federation by defining a clear versioning mechanis m for interpreting metadata.</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: Must adhere to Semantic Versioning (<eref target="https://semver.org <li>Syntax: The value <bcp14>MUST</bcp14> follow Semantic Versioning (see <eref
">https://semver.org</eref>).</li> target="https://semver.org" brackets="angle"/>).</li>
<li>Example: <tt>&quot;1.0.0&quot;</tt></li> <li>Example: <tt>"1.0.0"</tt></li>
</ul></li> </ul></li>
<li><t>cache_ttl (OPTIONAL)</t> <li><t>cache_ttl (<bcp14>OPTIONAL</bcp14>)</t>
<t>Specifies the duration in seconds for caching downloaded federation metadata, <t>
allowing for independent caching outside of specific HTTP configurations, parti Specifies the duration in seconds for caching downloaded federation metadata, al
cularly useful when the communication mechanism isn't HTTP-based. In the event o lowing for independent caching outside of specific HTTP configurations. This is
f a metadata publication outage, members can rely on cached metadata until it ex particularly useful when the communication mechanism is not based on HTTP. In th
pires, as indicated by the exp claim in the JWS payload, defined in <xref target e event of a metadata publication outage, members can rely on cached metadata un
="metadata-signing"></xref>. Once expired, metadata MUST no longer be trusted. I til it expires, as indicated by the <tt>exp</tt> claim in the JWS payload, defin
f omitted, a mechanism to refresh metadata MUST still exist to ensure the metada ed in <xref target="federation-metadata-claims"/>. Once expired, metadata <bcp14
ta remains valid.</t> >MUST</bcp14> no longer be trusted. If omitted, a mechanism to refresh metadata
<bcp14>MUST</bcp14> still exist to ensure the metadata remains valid.</t>
<ul> <ul>
<li>Data Type: Integer</li> <li>Data Type: Integer</li>
<li>Syntax: Integer representing the duration in seconds.</li> <li>Syntax: Integer representing the duration in seconds.</li>
<li>Example: <tt>3600</tt></li> <li>Example: <tt>3600</tt></li>
</ul></li> </ul></li>
<li><t>entities (REQUIRED)</t> <li><t>entities (<bcp14>REQUIRED</bcp14>)</t>
<t>Contains the list of entities within the federation.</t> <t>Contains the list of entities within the federation.</t>
<ul> <ul>
<li>Data Type: Array of Objects</li> <li>Data Type: Array of Objects</li>
<li>Syntax: Each object MUST conform to the entity definition, as specified in < xref target="entities"></xref>.</li> <li>Syntax: Each object <bcp14>MUST</bcp14> conform to the entity definition, as specified in <xref target="entities"/>.</li>
</ul></li> </ul></li>
</ul> </ul>
<section anchor="entities"><name>Entities</name> <section anchor="entities"><name>Entities</name>
<t>Metadata contains a list of entities that may be used for communication withi n the federation. Each entity describes one or more endpoints owned by a member. An entity has the following properties:</t> <t>Metadata contains a list of entities that may be used for communication withi n the federation. Each entity describes one or more endpoints owned by a member. An entity has the following properties:</t>
<ul> <ul>
<li><t>entity_id (REQUIRED)</t> <li><t>entity_id (<bcp14>REQUIRED</bcp14>)</t>
<t>A URI that uniquely identifies the entity. This identifier MUST NOT collide w <t>A URI that uniquely identifies the entity. This identifier <bcp14>MUST NOT</b
ith any other entity_id within the federation or within any other federation tha cp14> collide with any other <tt>entity_id</tt> within the federation or within
t the entity interacts with.</t> any other federation that the entity interacts with.</t>
<ul> <ul>
<li>Data Type: URI</li> <li>Data Type: String</li>
<li>Syntax: A valid URI.</li> <li>Syntax: A URI as defined in <xref target="RFC3986"/>.</li>
<li>Example: <tt>&quot;https://example.com&quot;</tt></li> <li>Example: <tt>"https://example.com"</tt></li>
</ul></li> </ul></li>
<li><t>organization (OPTIONAL)</t> <li><t>organization (<bcp14>OPTIONAL</bcp14>)</t>
<t>A name identifying the organization that the entity's metadata represents. Th <t>A name identifying the organization that the entity's metadata represents. Th
e federation operator MUST ensure a mechanism is in place to verify that the org e federation operator <bcp14>MUST</bcp14> ensure that a mechanism is in place to
anization claim corresponds to the rightful owner of the information exchanged b verify that the <tt>organization</tt> claim corresponds to the rightful owner o
etween nodes. This is crucial for the trust model, ensuring certainty about the f the information exchanged between nodes. This is crucial for the trust model,
identities of the involved parties. The federation operator SHOULD choose an app ensuring certainty about the identities of the involved parties. The federation
roach that best suits the specific needs and trust model of the federation.</t> operator <bcp14>SHOULD</bcp14> choose an approach that best suits the specific n
eeds and trust model of the federation.</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: A name identifying the organization represented by the entity.</li> <li>Syntax: A name identifying the organization represented by the entity.</li>
<li>Example: <tt>&quot;Example Org&quot;</tt></li> <li>Example: <tt>"Example Org"</tt></li>
</ul></li> </ul></li>
<li><t>issuers (REQUIRED)</t> <li><t>issuers (<bcp14>REQUIRED</bcp14>)</t>
<t>A list of certificate issuers allowed to issue certificates for the entity's <t>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 endpoints. For each issuer, the issuer's root CA certificate <bcp14>MUST</bcp14>
the x509certificate property, PEM-encoded. Certificate verification relies on p be included in the <tt>x509certificate</tt> property and be encoded using the P
ublic key pinning, with the list of allowed issuers used only when a certificate rivacy-Enhanced Mail (PEM) format. Certificate verification relies on public key
chain validation mechanism is unavoidable. For self-signed certificates, the ce pinning, with the list of allowed issuers used only when a certificate chain va
rtificate itself acts as its own issuer and MUST be listed as such in the metada lidation mechanism is unavoidable. For self-signed certificates, the certificate
ta.</t> itself acts as its own issuer and <bcp14>MUST</bcp14> be listed as such in the
metadata.</t>
<ul> <ul>
<li>Data Type: List of Objects</li> <li>Data Type: Array of Objects</li>
<li>Syntax: Each object contains a issuer certificate, PEM-encoded.</li> <li>Syntax: Each object contains an issuer certificate encoded as PEM, as specif
ied in <xref target="RFC7468"/>. The Base64 content <bcp14>MUST</bcp14> be wrapp
ed so that each line consists of exactly 64 characters, except for the final lin
e. In JSON text, line breaks in the PEM value are represented using the "\n" esc
ape sequence.</li>
<li><t>Example: Issuer truncated for readability.</t> <li><t>Example: Issuer truncated for readability.</t>
<artwork><![CDATA[
"issuers": [{
"x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDD"
}]]]></artwork>
<artwork>&quot;issuers&quot;: [{
&quot;x509certificate&quot;: &quot;-----BEGIN CERTIFICATE-----\nMIIDDD&quot;
}]
</artwork>
</li> </li>
</ul></li> </ul></li>
<li><t>servers (OPTIONAL)</t> <li><t>servers (<bcp14>OPTIONAL</bcp14>)</t>
<t>Contains the list of servers within the entity.</t> <t>Contains the list of servers within the entity.</t>
<ul> <ul>
<li>Data Type: Array of Objects</li> <li>Data Type: Array of Objects</li>
<li>Syntax: Each object MUST conform to the server definition, as specified in < xref target="servers-clients"></xref>.</li> <li>Syntax: Each object <bcp14>MUST</bcp14> conform to the server definition, as specified in <xref target="servers-clients"/>.</li>
</ul></li> </ul></li>
<li><t>clients (OPTIONAL)</t> <li><t>clients (<bcp14>OPTIONAL</bcp14>)</t>
<t>Contains the list of clients within the entity.</t> <t>Contains the list of clients within the entity.</t>
<ul> <ul>
<li>Data Type: Array of Objects</li> <li>Data Type: Array of Objects</li>
<li>Syntax: Each object MUST conform to the client definition, as specified in < xref target="servers-clients"></xref>.</li> <li>Syntax: Each object <bcp14>MUST</bcp14> conform to the client definition, as specified in <xref target="servers-clients"/>.</li>
</ul></li> </ul></li>
</ul> </ul>
<section anchor="servers-clients"><name>Servers / Clients</name> <section anchor="servers-clients"><name>Servers / Clients</name>
<t>A list of the entity's servers and clients.</t> <t>The entity's servers and clients are listed below.</t>
<ul> <ul>
<li><t>description (OPTIONAL)</t> <li><t>description (<bcp14>OPTIONAL</bcp14>)</t>
<t>A human readable text describing the server or client.</t> <t>A human-readable text describing the server or client.</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: Free-form text describing the server or client.</li> <li>Syntax: Free-form text describing the server or client.</li>
<li>Example: <tt>&quot;SCIM Server 1&quot;</tt></li> <li>Example: <tt>"SCIM Server 1"</tt></li>
</ul></li> </ul></li>
<li><t>base_uri (OPTIONAL)</t> <li><t>base_uri (<bcp14>REQUIRED</bcp14> for servers, <bcp14>OPTIONAL</bcp14> fo
<t>The base URL of the server, which is required for endpoints that describe ser r clients)</t>
ver.</t> <t>The base URL of the server. This claim is <bcp14>REQUIRED</bcp14> for server
endpoints. The value <bcp14>MUST</bcp14> be an absolute URI as defined in <xref
target="RFC3986" section="4.3"/>. The value serves as the base URI for resolving
relative references to server resources, as described in <xref target="RFC3986"
section="5"/>.</t>
<ul> <ul>
<li>Data Type: URI</li> <li>Data Type: String</li>
<li>Syntax: A valid URL.</li> <li>Syntax: An absolute URI as defined in <xref target="RFC3986" section="4.3"/>
<li>Example: <tt>&quot;https://scim.example.com/&quot;</tt></li> that is used as a URL.</li>
<li>Example: <tt>"https://scim.example.com/"</tt></li>
</ul></li> </ul></li>
<li><t>pins (REQUIRED)</t> <li><t>pins (<bcp14>REQUIRED</bcp14>)</t>
<t>A list of objects representing Public Key Pins <xref target="RFC7469"></xref> <t>A list of objects representing public key pins <xref target="RFC7469"/>.</t>
.</t>
<ul> <ul>
<li>Data Type: Array of Objects</li> <li>Data Type: Array of Objects</li>
<li><t>Syntax: A list of objects, where each object represents a single public k ey pin with the following properties:</t> <li><t>Syntax: A list of objects, where each object represents a single public k ey pin with the following properties:</t>
<ul> <ul>
<li><t>alg (REQUIRED)</t> <li><t>alg (<bcp14>REQUIRED</bcp14>)</t>
<t>The name of the cryptographic hash algorithm. Currently, the RECOMMENDED valu <t>The name of the cryptographic hash algorithm. Currently, the <bcp14>RECOMMEND
e is 'sha256'. As more secure algorithms are developed over time, federations sh ED</bcp14> value is 'sha256'. As more secure algorithms are developed over time,
ould be ready to adopt these newer options for enhanced security.</t> federations should be ready to adopt these newer options for enhanced security.
</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: The name of the algorithm.</li> <li>Syntax: The name of the algorithm.</li>
<li>Example: <tt>&quot;sha256&quot;</tt></li> <li>Example: <tt>"sha256"</tt></li>
</ul></li> </ul></li>
<li><t>digest (REQUIRED)</t> <li><t>digest (<bcp14>REQUIRED</bcp14>)</t>
<t>The public key of the end-entity certificate converted to a Subject Public Ke <t>The public key of the end-entity certificate, converted to a Subject Public K
y Information (SPKI) fingerprint, as specified in Section 2.4 of <xref target="R ey Information (SPKI) fingerprint, as specified in <xref target="RFC7469" sectio
FC7469"></xref>. For clients, the digest MUST be globally unique for unambiguous n="2.4"/>. For clients, the <tt>digest</tt> value MUST be unique across entities
identification. However, within the same entity_id object, the same digest MAY in the federation metadata to enable unambiguous identification of the peer. Wi
be assigned to multiple clients.</t> thin the same entity, the same <tt>digest</tt> value MAY be assigned to multiple
clients.</t>
<ul> <ul>
<li>Data Type: String</li> <li>Data Type: String</li>
<li>Syntax: SPKI fingerprint.</li> <li>Syntax: SPKI fingerprint.</li>
<li>Example: <tt>&quot;+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=&quot;</tt></ li> <li>Example: <tt>"+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="</tt></li>
</ul></li> </ul></li>
</ul></li> </ul></li>
<li><t>Example:</t> <li><t>Example:</t>
<artwork>&quot;pins&quot;: [{ <artwork><![CDATA[
&quot;alg&quot;: &quot;sha256&quot;, "pins": [{
&quot;digest&quot;: &quot;+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=&quot; "alg": "sha256",
}] "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
</artwork> }]]]></artwork>
</li> </li>
</ul></li> </ul></li>
<li><t>tags (OPTIONAL)</t> <li><t>tags (<bcp14>OPTIONAL</bcp14>)</t>
<t>A list of strings that describe the endpoint's capabilities.</t> <t>A list of strings that describe the endpoint's capabilities.</t>
<ul> <ul>
<li>Data Type: Array of Strings</li> <li>Data Type: Array of Strings</li>
<li>Syntax: Strings describing endpoint capabilities.</li> <li>Syntax: Strings describing endpoint capabilities.</li>
<li>Pattern: <tt>^[a-z0-9]{1,64}$</tt></li> <li>Pattern: <tt>^[a-z0-9]{1,64}$</tt></li>
<li>Example: <tt>[&quot;scim&quot;, &quot;xyzzy&quot;]</tt></li> <li>Example: <tt>["scim", "xyzzy"]</tt></li>
</ul> </ul>
<t>Tags are fundamental for discovery within a federation, aiding both servers a nd clients in identifying appropriate connections.</t> <t>Tags are fundamental for discovery within a federation, aiding both servers a nd clients in identifying appropriate connections.</t>
<ul> <ul>
<li><t>Server Tags: Tags associated with servers are used by clients to discover servers offering the services they require. Clients can search for servers base d on tags that indicate supported protocols or the type of data they handle, ena bling discovery of compatible servers.</t> <li><t>Server Tags: Tags associated with servers are used by clients to discover servers offering the services they require. Clients can search for servers base d on tags that indicate supported protocols or the type of data they handle, ena bling discovery of compatible servers.</t>
</li> </li>
<li><t>Client Tags: Tags associated with clients are used by servers to identify clients with specific characteristics or capabilities. For instance, a server m ight only accept connections from clients that support particular protocols. By filtering incoming requests based on these tags, servers can identify suitable c lients.</t> <li><t>Client Tags: Tags associated with clients are used by servers to identify clients with specific characteristics or capabilities. For instance, a server m ight only accept connections from clients that support particular protocols. By filtering incoming requests based on these tags, servers can identify suitable c lients.</t>
</li> </li>
</ul> </ul>
<t>Federation-Specific Considerations</t> <t>Federation-Specific Considerations: While tags are tied to individual federat
<t>While tags are tied to individual federations and serve distinct purposes wit ions and serve distinct purposes within each, several key considerations are cru
hin each, several key considerations are crucial to ensure clarity and promote c cial to ensure clarity and promote consistent tag usage:</t>
onsistent tag usage:</t>
<ul> <ul>
<li><t>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 re gistry of approved tags is essential for the federation.</t> <li><t>Well-Defined Scope: Each federation <bcp14>MUST</bcp14> establish a clear scope for its tags, detailing their intended use, allowed tag values, associate d meanings, and any relevant restrictions. Maintaining a well-defined and readil y accessible registry of approved tags is essential for the federation.</t>
</li> </li>
<li><t>Validation Mechanisms: Implementing validation mechanisms for tags is hig hly recommended. This may involve a dedicated operation or service verifying tag validity and compliance with the federation's regulations. Such validation ensu res consistency within the federation by preventing the use of unauthorized or i rrelevant tags.</t> <li><t>Validation Mechanisms: Implementing validation mechanisms for tags is hig hly recommended. This can involve a dedicated operation or service verifying tag validity and compliance with the federation's regulations. Such validation ensu res consistency within the federation by preventing the use of unauthorized or i rrelevant tags.</t>
</li> </li>
</ul></li> </ul></li>
</ul> </ul>
</section> </section>
</section> </section>
</section> </section>
<section anchor="metadata-schema"><name>Metadata Schema</name> <section anchor="metadata-schema"><name>Metadata Schema</name>
<t>The MATF metadata schema is defined in <xref target="json-schema-for-matf-met <t>The MATF metadata schema is defined in <xref target="json-schema-for-matf-met
adata"></xref>. This schema specifies the format for describing entities involve adata"/>. This schema specifies the format for describing entities involved in M
d in MATF and their associated information.</t> ATF and their associated information.</t>
<t>Note: The schema in Appendix A is folded due to line length limitations as sp <aside><t>Note: The schema in <xref target="json-schema-for-matf-metadata"/> is
ecified in <xref target="RFC8792"></xref>.</t> folded due to line length limitations as specified in <xref target="RFC8792"/>.<
/t></aside>
</section> </section>
<section anchor="example-metadata"><name>Example Metadata</name> <section anchor="example-metadata"><name>Example Metadata</name>
<t>The following is a non-normative example of a metadata statement. Line breaks within the issuers' claim is for readability only.</t> <t>The following is a non-normative example of a metadata statement. Line breaks in the example of the <tt>issuers</tt> claim are for readability only.</t>
<sourcecode type="json">{ <sourcecode type="json"><![CDATA[
&quot;exp&quot;: 1755514949, {
&quot;iat&quot;: 1756119888, "iat": 1755514949,
&quot;iss&quot;: &quot;https://federation.example.org&quot;, "exp": 1756119888,
&quot;version&quot;: &quot;1.0.0&quot;, "iss": "https://federation.example.org",
&quot;cache_ttl&quot;: 3600, "version": "1.0.0",
&quot;entities&quot;: [{ "cache_ttl": 3600,
&quot;entity_id&quot;: &quot;https://example.com&quot;, "entities": [{
&quot;organization&quot;: &quot;Example Org&quot;, "entity_id": "https://example.com",
&quot;issuers&quot;: [{ "organization": "Example Org",
&quot;x509certificate&quot;: &quot;-----BEGIN CERTIFICATE-----\nMIIDDDCCAf "issuers": [{
"x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDDCCAf
SgAwIBAgIJAIOsfJBStJQhMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAM SgAwIBAgIJAIOsfJBStJQhMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAM
MEHNjaW0uZXhhbXBsZS5jb20wHhcNMTcwNDA2MDc1MzE3WhcNMTcwNTA2MD MEHNjaW0uZXhhbXBsZS5jb20wHhcNMTcwNDA2MDc1MzE3WhcNMTcwNTA2MD
c1\nMzE3WjAbMRkwFwYDVQQDDBBzY2ltLmV4YW1wbGUuY29tMIIBIjANBgk c1\nMzE3WjAbMRkwFwYDVQQDDBBzY2ltLmV4YW1wbGUuY29tMIIBIjANBgk
qhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAyr+3dXTC8YXoi0LDJTH0lTfv qhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAyr+3dXTC8YXoi0LDJTH0lTfv
8omQivWFOr3+/PBE\n6hmpLSNXK/EZJBD6ZT4Q+tY8dPhyhzT5RFZCVlrDs 8omQivWFOr3+/PBE\n6hmpLSNXK/EZJBD6ZT4Q+tY8dPhyhzT5RFZCVlrDs
e/kY00F4yoflKiqx9WSuCrq\nZFr1AUtIfGR/LvRUvDFtuHo1MzFttiK8Wr e/kY00F4yoflKiqx9WSuCrq\nZFr1AUtIfGR/LvRUvDFtuHo1MzFttiK8Wr
wskMYZrw1zLHTIVwBkfMw1qr2XzxFK\njt0CcDmFxNdY5Q8kuBojH9+xt5s wskMYZrw1zLHTIVwBkfMw1qr2XzxFK\njt0CcDmFxNdY5Q8kuBojH9+xt5s
ZbrJ9AVH/OI8JamSqDjk9ODyGg+GrEZFClP/B\nxa4Fsl04En/9GfaJnCU1 ZbrJ9AVH/OI8JamSqDjk9ODyGg+GrEZFClP/B\nxa4Fsl04En/9GfaJnCU1
NpU0cqvWbVUlLOy8DaQMN14HIdkTdmegEsg2LR/XrJkt\nho16diAXrgS25 NpU0cqvWbVUlLOy8DaQMN14HIdkTdmegEsg2LR/XrJkt\nho16diAXrgS25
3xbkdD3T5d6lHiZCL6UxkBh4ZHRcoftSwIDAQABo1MwUTAdBgNV\nHQ4EFg 3xbkdD3T5d6lHiZCL6UxkBh4ZHRcoftSwIDAQABo1MwUTAdBgNV\nHQ4EFg
QUs1dXuhGhGc2UNb7ikn3t6cBuU34wHwYDVR0jBBgwFoAUs1dXuhGhGc2U\ QUs1dXuhGhGc2UNb7ikn3t6cBuU34wHwYDVR0jBBgwFoAUs1dXuhGhGc2U\
nNb7ikn3t6cBuU34wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAA nNb7ikn3t6cBuU34wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAA
OCAQEA\nrR9wxPhUa2XfQ0agAC0oC8TFf8wbTYb0ElP5Ej834xMMW/wWTSA OCAQEA\nrR9wxPhUa2XfQ0agAC0oC8TFf8wbTYb0ElP5Ej834xMMW/wWTSA
N8/3WqOWNQJ23\nf0vEeYQwfvbD2fjLvYTyM2tSPOWrtQpKuvulIrxV7Zz8 N8/3WqOWNQJ23\nf0vEeYQwfvbD2fjLvYTyM2tSPOWrtQpKuvulIrxV7Zz8
A61NIjblE3rfea1eC8my\nTkDOlMKV+wlXXgUxirride+6ubOWRGf92fgze A61NIjblE3rfea1eC8my\nTkDOlMKV+wlXXgUxirride+6ubOWRGf92fgze
DGJWkmm/a9tj0L/3e0xIXeujxC7\nMIt3p99teHjvnZQ7FiIBlvGc1o8FD1 DGJWkmm/a9tj0L/3e0xIXeujxC7\nMIt3p99teHjvnZQ7FiIBlvGc1o8FD1
FKmFYd74s7RxrAusBEAAmBo3xyB89cFU0d\nKB2fkH2lkqiqkyOtjrlHPoy FKmFYd74s7RxrAusBEAAmBo3xyB89cFU0d\nKB2fkH2lkqiqkyOtjrlHPoy
6ws6g1S6U/Jx9n0NEeEqCfzXnh9jEpxisSO+fBZER\npCwj2LMNPQxZBqBF 6ws6g1S6U/Jx9n0NEeEqCfzXnh9jEpxisSO+fBZER\npCwj2LMNPQxZBqBF
oxbFPw==\n-----END CERTIFICATE-----&quot; oxbFPw==\n-----END CERTIFICATE-----"
}], }],
&quot;servers&quot;: [{ "servers": [{
&quot;description&quot;: &quot;SCIM Server 1&quot;, "description": "SCIM Server 1",
&quot;base_uri&quot;: &quot;https://scim.example.com/&quot;, "base_uri": "https://scim.example.com/",
&quot;pins&quot;: [{ "pins": [{
&quot;alg&quot;: &quot;sha256&quot;, "alg": "sha256",
&quot;digest&quot;: &quot;+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=&q "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
uot;
}], }],
&quot;tags&quot;: [ "tags": [
&quot;scim&quot; "scim"
] ]
}], }],
&quot;clients&quot;: [{ "clients": [{
&quot;description&quot;: &quot;SCIM Client 1&quot;, "description": "SCIM Client 1",
&quot;pins&quot;: [{ "pins": [{
&quot;alg&quot;: &quot;sha256&quot;, "alg": "sha256",
&quot;digest&quot;: &quot;+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=&q "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
uot;
}] }]
}] }]
}] }]
} }]]></sourcecode>
</sourcecode>
</section> </section>
<section anchor="metadata-signing"><name>Metadata Signing</name> <section anchor="metadata-signing"><name>Metadata Signing</name>
<t>Federation metadata is signed using JWS and published using JWS JSON Serializ <t>Federation metadata is signed using JWS and published using JWS JSON Serializ
ation according to the General JWS JSON Serialization Syntax defined in <xref ta ation according to the general JWS JSON Serialization syntax defined in <xref ta
rget="RFC7515"></xref>. Federation metadata signatures are RECOMMENDED to be cre rget="RFC7515"/>. Federation metadata signatures are <bcp14>RECOMMENDED</bcp14>
ated using the algorithm <em>ECDSA using P-256 and SHA-256</em> (&quot;ES256&quo to be created using the algorithm ECDSA using P-256 and SHA-256 (&quot;ES256&quo
t;) as defined in <xref target="RFC7518"></xref>. However, to accommodate evolvi t;) as defined in <xref target="RFC7518"/>. However, to accommodate evolving cry
ng cryptographic standards, alternative algorithms MAY be used, provided they me ptographic standards, alternative algorithms <bcp14>MAY</bcp14> be used, provide
et the security requirements of the federation.</t> d they meet the security requirements of the federation.</t>
<t>The following protected JWS header parameters are REQUIRED:</t> <t>Federations may need to transition to post-quantum (PQ) cryptographic algorit
hms for federation metadata signatures and for endpoint certificate public key t
ypes. MATF can accommodate such transitions through key rollover and by updating
published pins as new key types are deployed.</t>
<t>The following JWS Protected Header parameters are <bcp14>REQUIRED</bcp14>:</t
>
<ul> <ul>
<li><t><tt>alg</tt> (Algorithm)</t> <li><t><tt>alg</tt> (Algorithm)</t>
<t>Identifies the algorithm used to generate the JWS signature <xref target="RFC 7515"></xref>, Section 4.1.1.</t> <t>Identifies the algorithm used to generate the JWS signature <xref target="RFC 7515" sectionFormat="comma" section="4.1.1"/>.</t>
</li> </li>
<li><t><tt>kid</tt> (Key Identifier)</t> <li><t><tt>kid</tt> (Key Identifier)</t>
<t>Identifies the signing key in the key set used to sign the JWS <xref target=" RFC7515"></xref>, Section 4.1.4.</t> <t>Identifies the key in the issuer's key set that was used to generate the JWS signature <xref target="RFC7515" sectionFormat="comma" section="4.1.4"/>.</t>
</li> </li>
</ul> </ul>
</section> </section>
<section anchor="example-signature-protected-header"><name>Example Signature Pro tected Header</name> <section anchor="example-signature-protected-header"><name>Example Signature Pro tected Header</name>
<t>The following is a non-normative example of a signature protected header.</t> <t>The following is a non-normative example of a signature protected header.</t>
<sourcecode type="json">{ <sourcecode type="json"><![CDATA[
&quot;alg&quot;: &quot;ES256&quot;, {
&quot;kid&quot;: &quot;c2fb760e-f4b6-4f7e-b17a-7115d2826d51&quot; "alg": "ES256",
} "kid": "c2fb760e-f4b6-4f7e-b17a-7115d2826d51"
</sourcecode> }]]></sourcecode>
</section> </section>
</section> </section>
<section anchor="example-usage-scenarios"><name>Example Usage Scenarios</name> <section anchor="example-usage-scenarios"><name>Example Usage Scenarios</name>
<t>The examples in this section are non-normative.</t> <t>The examples in this section are non-normative and illustrate the procedures
<t>The following example describes a scenario within the federation &quot;Skolfe described in <xref target="pin-discovery-and-preloading"/> and <xref target="ver
deration&quot; where MATF is already established. Both clients and servers are r ification-of-received-certificates"/>.</t>
egistered members of the federation. In this scenario, clients aim to manage cro <t>The following example describes a scenario within the federation &quot;Skolfe
ss-domain user accounts within the service. The standard used for account manage deration&quot; where MATF is deployed. Both clients and servers are registered m
ment is SS 12000:2018 (i.e., a SCIM extension).</t> embers of the federation. In this scenario, clients manage cross-domain user acc
ounts using SS 12000:2018, which is a System for Cross-domain Identity Managemen
t (SCIM) extension.</t>
<sourcecode type="ascii-art">+---------------------------------------------+ <artwork><![CDATA[
| | +------------------------------------------------------+
| Federation Metadata | | |
| | | Federation Metadata |
+---+--------------------------+--------------+ | |
| | +-----+-------------------------------+----------------+
(A) (A) | |
| | (A) (A)
v v | |
+---+----+ +------------+--------------+ v v
|Local MD| | Local MD | +-----------+ +--------------------------------+
+---+----+ +----+------------- ---+----+ | Local MD | | Local MD |
| | | +-----+-----+ +------+---------------------+---+
(B) (C) (F) | | |
| | | (B) (C) (F)
v v v | | |
+---+----+ +----+---+ +----+---+ v v v
| | | | | | +-----------+ +--------------+ +-------+
| Client | | Reverse| | App | | | | | | |
| +--(D)--&gt;+ Proxy +--(E)--&gt;+ | | Client +---(D)-->+ Intermediary +---(E)-->+ App |
| | | | | | | | | | | |
| | | | | | +-----------+ +--------------+ +-------+]]></artwork>
+--------+ +--------+ +--------+
</sourcecode>
<ol type="A"> <ol type="A">
<li>Entities collect member metadata from the federation metadata.</li> <li>Clients and servers retrieve federation metadata and update their local meta
<li>The client pins the server's public key pins.</li> data stores as described in <xref target="maintaining-up-to-date-metadata"/>.</l
<li>The reverse proxy trust anchor is setup with the clients' certificate issuer i>
s.</li> <li>The client selects a server endpoint based on metadata claims and preloads t
<li>The client establishes a connection with the server using the base_uri from he pins published for that endpoint.</li>
the federation metadata.</li> <li>If certificate chain validation is performed, the TLS client or intermediary
<li>The reverse proxy forwards the client certificate to the application.</li> configures its trust store using the <tt>issuers</tt> listed in the federation
<li>The application converts the certificate to a public key pin and checks the metadata for the selected entity.</li>
federation metadata for a matching pin. The entity's entity_id should be used as <li>The client initiates a TLS connection to the selected <tt>base_uri</tt> and
an identifier.</li> presents its client certificate.</li>
<li>If an intermediary terminates the TLS session, it forwards identity material
derived from the TLS session to the application as described in <xref target="v
erification-of-received-certificates"/> and <xref target="implementation-guideli
nes"/>.</li>
<li>The application maps the derived pin to a matching metadata entry and uses t
he associated <tt>entity_id</tt> for identification and authorization.</li>
</ol> </ol>
<section anchor="client"><name>Client</name> <section anchor="client-behavior"><name>Client Behavior</name>
<t>A certificate is issued for the client and the issuer is published in the fed <t>A certificate is issued for the client. The client's certificate issuer and p
eration metadata together with the client's certificate public key pins</t> ublic key <tt>pins</tt> are published in the federation metadata.</t>
<t>When the client wants to connect to a remote server (identified by an entity
identifier) the following steps need to be taken:</t>
<ol> <t>When a client initiates a connection to a remote server (identified by the se
<li>Find possible server candidates by filtering the remote entity's list of ser rver's <tt>entity_id</tt>), the following steps are performed:</t>
vers based on tags.</li>
<li>Connect to the server URI. Include the entity's list of certificate issuers <ol type="1">
in the TLS clients list of trusted CAs, or trust the listed pins explicitly.</li <li>The client selects a server endpoint from the identified entity's <tt>server
> s</tt> list whose <tt>tags</tt> match the required service capabilities.</li>
<li>If pinning is not used during the TLS handshake, the client MUST perform a p <li>The client preloads the selected endpoint's <tt>pins</tt> from its local met
ost-connection validation against the entity's published pins.</li> adata store. If certificate chain validation is performed, the client also loads
<li>Commence transactions.</li> the <tt>issuers</tt> listed for the entity.</li>
<li>The client initiates a TLS connection to the selected endpoint using the <tt
>base_uri</tt> and presents its client certificate.</li>
<li>The client performs pin validation for the server certificate as described i
n <xref target="verification-of-received-certificates"/>. This validation may be
performed by the TLS stack during the handshake or by application logic after t
he connection is established, but it completes before any application data is ex
changed.</li>
<li>If validation succeeds, the client proceeds with application transactions.</
li>
</ol> </ol>
</section> </section>
<section anchor="server"><name>Server</name> <section anchor="server-behavior"><name>Server Behavior</name>
<t>A certificate is issued for the server and the issuer is published in the fed <t>To accept inbound connections from a client, the server uses federation metad
eration metadata together with the server's name and certificate public key pin. ata to perform pin validation of the public key in the presented client certific
</t> ate. The federation metadata publishes client public key <tt>pins</tt> and, for
<t>When the server receives a connection from a remote client, the following ste deployments that perform certificate chain validation, the allowed <tt>issuers</
ps need to be taken:</t> tt>.</t>
<t>When the server receives a TLS connection attempt from a remote client, the f
ollowing steps are performed:</t>
<ol> <ol>
<li>Populate list of trusted CAs using all known entities' published issuers and <li>The server is configured to request or require a client certificate. If cert
required TLS client certificate authentication, or configure optional untrusted ificate chain validation is performed, the trust store is populated using the <t
TLS client certificate authentication (e.g., optional_no_ca).</li> t>issuers</tt> published in the federation metadata. Otherwise, the server reque
<li>Once a connection has been accepted, validate the received client certificat sts a client certificate without issuer validation (for example, <tt>optional_no
e using the client's published pins.</li> _ca</tt>).</li>
<li>Commence transactions.</li> <li>The server can prefilter the federation metadata to identify the set of clie
nts it is willing to communicate with and preload only the <tt>pins</tt> for tho
se clients, as described in <xref target="pin-discovery-and-preloading"/>.</li>
<li>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 matc
h is found, the server determines the client's <tt>entity_id</tt> from the corre
sponding metadata entry.</li>
<li>If pin validation succeeds, the server proceeds with application transaction
s. If pin validation fails, the server terminates the connection.</li>
</ol> </ol>
</section> </section>
<section anchor="spki-generation"><name>SPKI Generation</name> <section anchor="spki-generation"><name>SPKI Generation</name>
<t>Example of how to use OpenSSL to generate a SPKI fingerprint from a PEM-encod ed certificate.</t> <t>The following is an example of how to use OpenSSL to generate a SPKI fingerpr int from a PEM-encoded certificate.</t>
<sourcecode type="bash"> openssl x509 -in &lt;certificate.pem&gt; -pubkey -noou <sourcecode type="bash"><![CDATA[
t | \ openssl x509 -in <certificate.pem> -pubkey -noout | \
openssl pkey -pubin -outform der | \ openssl pkey -pubin -outform der | \
openssl dgst -sha256 -binary | \ openssl dgst -sha256 -binary | \
openssl enc -base64 openssl enc -base64]]></sourcecode>
</sourcecode>
</section> </section>
<section anchor="curl-and-public-key-pinning"><name>Curl and Public Key Pinning< /name> <section anchor="curl-and-public-key-pinning"><name>Curl and Public Key Pinning< /name>
<t>Example of public key pinning with curl. Line breaks are for readability only .</t> <t>The following is an example of public key pinning with curl.</t>
<sourcecode type="bash"> curl --cert client.pem --key client.key --pinnedpubkey <sourcecode type="bash"><![CDATA[
'sha256//0Ok curl --cert client.pem --key client.key \
2aNfcrCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' https://host.example.com --pinnedpubkey \
</sourcecode> 'sha256//0Ok2aNfcrCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' \
https://host.example.com]]></sourcecode>
</section> </section>
</section> </section>
<section anchor="deployments-of-the-matf-framework"><name>Deployments of the MAT F Framework</name> <section anchor="deployments-of-the-matf-framework"><name>Deployments of the MAT F Framework</name>
<t>The MATF framework has proven its practical value and robustness through succ essful deployments in several environments.</t> <t>The MATF framework has proven its practical value and robustness through succ essful deployments in several environments.</t>
<section anchor="skolfederation-moa"><name>Skolfederation Moa</name> <section anchor="skolfederation-moa"><name>Skolfederation Moa</name>
<t>Skolfederation Moa <xref target="Moa"></xref>, is a federation designed to se <t>Skolfederation Moa <xref target="Moa"/> is a federation designed to secure co
cure communication between digital educational resources and schools. MATF is de mmunication between digital educational resources and schools. MATF was develope
veloped to meet Moa's needs and enables secure data exchange for schools, munici d to meet Moa's needs and enables secure data exchange for schools, municipaliti
palities, educational platforms, and services across Sweden.</t> es, educational platforms, and services across Sweden.</t>
<t>The community plays a crucial role in this type of federation. Members are ac <t>The community plays a crucial role in this type of federation. Members are ac
tive participants, and the FO ensures the federation runs smoothly and serves th tive participants, and the federation operator ensures the federation runs smoot
eir needs. Moa's success highlights the importance of collaboration, with member hly and serves their needs. Moa's success highlights the importance of collabora
s and the FO working together to maintain trust, security, and interoperability tion, with members and the federation operator working together to maintain trus
in the education sector.</t> t, security, and interoperability in the education sector.</t>
<t>The deployment of MATF in the Swedish education sector has provided several k ey insights. Maintaining an accurate registry of metadata ownership with reliabl e contact information is essential for troubleshooting and ensuring accountabili ty. The deployment also demonstrated the importance of setting reasonable expira tion times for metadata. Too short an expiration can hinder the ability to imple ment contingency plans for publishing new metadata during outages.</t> <t>The deployment of MATF in the Swedish education sector has provided several k ey insights. Maintaining an accurate registry of metadata ownership with reliabl e contact information is essential for troubleshooting and ensuring accountabili ty. The deployment also demonstrated the importance of setting reasonable expira tion times for metadata. Too short an expiration can hinder the ability to imple ment contingency plans for publishing new metadata during outages.</t>
<t>Metadata validation is necessary to maintain a stable federation. While manua l validation may be sufficient in the early stages of a federation, it becomes u nmanageable as the federation scales. Without an automated validation process, i ncorrect metadata uploaded by members is likely to go undetected, leading to pub lication of incorrect metadata.</t> <t>Metadata validation is necessary to maintain a stable federation. While manua l validation may be sufficient in the early stages of a federation, it becomes u nmanageable as the federation scales. Without an automated validation process, i ncorrect metadata uploaded by members is likely to go undetected, leading to pub lication of incorrect metadata.</t>
<t>The signing key is needed to sign metadata. Under fallback scenarios, even if metadata can be retrieved from elsewhere, without access to the signing key, it is impossible to publish metadata. Therefore, secure and redundant management o f the signing key is crucial to enable fallback mechanisms and ensure reliable s igning and distribution of metadata. If metadata is retrieved from a location ot her than the official repository, it is mandatory to validate its signature to m aintain trust and ensure the authenticity of the metadata.</t> <t>The federation metadata signing private key is required to publish signed fed eration metadata. In fallback scenarios, federation metadata may be retrieved fr om an alternate location, but publishing updated federation metadata requires ac cess to the signing private key. Therefore, secure and redundant management of t he signing private key is necessary to support fallback mechanisms and reliable publication. Recipients <bcp14>MUST</bcp14> validate the JWS signature using the federation signature verification key before using federation metadata, regardl ess of where it is obtained.</t>
</section> </section>
<section anchor="swedish-national-agency-for-education"><name>Swedish National A gency for Education</name> <section anchor="swedish-national-agency-for-education"><name>Swedish National A gency for Education</name>
<t>The Swedish National Agency for Education <xref target="SkolverketMATF"></xre f> leverages MATF within its digital national test platform to establish a robus t authentication mechanism. The platform utilizes an API for client verification prior to secure data transfer to the agency's test service, ensuring the integr ity and confidentiality of educational data.</t> <t>The Swedish National Agency for Education <xref target="SkolverketMATF"/> lev erages MATF within its digital national test platform to establish a robust auth entication mechanism. The platform utilizes an API for client verification prior to secure data transfer to the agency's test service, ensuring the integrity an d confidentiality of educational data.</t>
</section> </section>
<section anchor="sambruk-s-egil"><name>Sambruk's EGIL</name> <section anchor="sambruk-s-egil"><name>Sambruk's EGIL</name>
<t>Sambruk's EGIL <xref target="EGIL"></xref>, a platform providing digital serv ices to municipalities, has successfully integrated the MATF framework. This dep loyment demonstrates the framework's adaptability to support a wide range of dig ital service infrastructures.</t> <t>Sambruk's EGIL <xref target="EGIL"/>, a platform providing digital services t o municipalities, has successfully integrated the MATF framework. This deploymen t demonstrates the framework's adaptability to support a wide range of digital s ervice infrastructures.</t>
<t>These deployments highlight the effectiveness of the MATF framework in enhanc ing security and interoperability within the educational sector.</t> <t>These deployments highlight the effectiveness of the MATF framework in enhanc ing security and interoperability within the educational sector.</t>
</section> </section>
</section> </section>
<section anchor="security-considerations"><name>Security Considerations</name> <section anchor="security-considerations"><name>Security Considerations</name>
<section anchor="security-risks-and-trust-management"><name>Security Risks and T rust Management</name> <section anchor="security-risks-and-trust-management"><name>Security Risks and T rust Management</name>
<t>The security risks associated with the MATF framework are confined to each in <t>The security risks associated with the MATF framework are confined to each in
dividual federation. Both the federation operator and federation members share t dividual federation. Both the federation operator and federation members share t
he responsibility of maintaining trust and security within the federation. Prope he responsibility of maintaining trust and security. Proper handling of metadata
r handling and management of metadata, as well as thorough vetting of federation and thorough vetting of members are crucial to sustaining this trust.</t>
members, are crucial to sustaining this trust and security. Each federation ope <t>Deployments that terminate a session at an intermediary and convey identity m
rates within a trust framework, which includes its own security policies and pro aterial to an application introduce a critical trust boundary. If the intermedia
cedures to ensure the integrity and reliability of the federation.</t> ry is compromised or fails to properly sanitize inbound headers, an attacker cou
ld spoof a peer's <tt>entity_id</tt>. Therefore, intermediaries that convey iden
tity material to an application <bcp14>MUST</bcp14> comply with the requirements
in <xref target="implementation-guidelines"/>.</t>
<t>Implementations <bcp14>SHOULD</bcp14> avoid logging conveyed certificates, pi
ns, or identity values unless required for diagnostics to prevent the accidental
exposure of session-specific identity material.</t>
</section> </section>
<section anchor="tls"><name>TLS</name> <section anchor="tls"><name>TLS</name>
<t>The security considerations for TLS 1.3 are detailed in Section 10 and Append ices C, D, and E of <xref target="RFC8446"></xref>.</t> <t>The security considerations for TLS 1.3 are detailed in Section <xref target= "RFC8446" section="10" sectionFormat="bare"/> and Appendices <xref target="RFC84 46" section="C" sectionFormat="bare"/>, <xref target="RFC8446" section="D" secti onFormat="bare"/>, and <xref target="RFC8446" section="E" sectionFormat="bare"/> of <xref target="RFC8446"/>.</t>
</section> </section>
<section anchor="federation-metadata-updates"><name>Federation Metadata Updates< /name> <section anchor="federation-metadata-updates"><name>Federation Metadata Updates< /name>
<t>Regularly updating the local copy of federation metadata is essential for acc essing the latest information about active entities, current public key pins <xr ef target="RFC7469"></xref>, 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.</t> <t>Regularly updating the local copy of federation metadata is essential for acc essing the latest information about active entities, current public key pins <xr ef target="RFC7469"/>, and valid issuer certificates. The use of outdated metada ta may expose systems to security risks, such as interaction with revoked entiti es or acceptance of manipulated data.</t>
</section> </section>
<section anchor="verifying-the-federation-metadata-signature"><name>Verifying th e Federation Metadata Signature</name> <section anchor="verifying-the-federation-metadata-signature"><name>Verifying th e Federation Metadata Signature</name>
<t>Ensuring data integrity and security within the MATF framework relies on veri fying the signature of downloaded federation metadata. This verification process confirms the data's origin, ensuring it comes from the intended source and has not been altered by unauthorized parties. By establishing the authenticity of th e metadata, trust is maintained in the information it contains, including valid member public key pins and issuer certificates. To achieve a robust implementati on, it is crucial to consider the security aspects outlined in <xref target="RFC 7515"></xref>, which describes security considerations related to algorithm sele ction, key compromise, and signature integrity.</t> <t>Ensuring data integrity and security within the MATF framework relies on veri fying the signature of downloaded federation metadata. This verification confirm s the origin of the metadata by validating the JWS signature using the federatio n signature verification key trusted by the recipient. It also confirms that the signed content has not been altered by unauthorized parties. By verifying the s ignature, trust is maintained in the integrity of the information used for valid ation, including member public key pins and issuer certificates. To achieve a ro bust implementation, it is important to consider the security aspects outlined i n <xref target="RFC7515"/>, which describes security considerations related to a lgorithm selection, key compromise, and signature integrity.</t>
</section> </section>
<section anchor="time-synchronization"><name>Time Synchronization</name> <section anchor="time-synchronization"><name>Time Synchronization</name>
<t>Maintaining synchronized clocks across all federation members is critical for <t>Maintaining synchronized clocks across all federation members is critical for
the security of the MATF framework. Inaccurate timestamps can compromise the va the security of the MATF framework. Inaccurate timestamps can compromise the va
lidity of digital signatures and certificates, hinder reliable log analysis, and lidity of digital signatures and certificates, hinder reliable log analysis, and
potentially expose the system to time-based attacks. Therefore, all federation potentially expose the system to time-based attacks. Therefore, all federation
members MUST employ methods to ensure their system clocks are synchronized with members <bcp14>MUST</bcp14> employ methods to ensure their system clocks are syn
a reliable time source.</t> chronized with a reliable time source.</t>
</section>
</section> </section>
<section anchor="acknowledgements"><name>Acknowledgements</name>
<t>This project was funded through the NGI0 PET Fund, a fund established by NLne
t with financial support from the European Commission's Next Generation Internet
programme, under the aegis of DG Communications Networks, Content and Technolog
y under grant agreement No 825310.</t>
<t>The authors thank the following people for the detailed review and suggestion
s:</t>
<ul>
<li>Rasmus Larsson</li>
<li>Mats Dufberg</li>
<li>Joe Siltberg</li>
<li>Stefan Norberg</li>
<li>Petter Blomberg</li>
</ul>
<t>The authors would also like to thank participants in the EGIL working group f
or their comments on this specification.</t>
</section> </section>
<section anchor="iana-considerations"><name>IANA Considerations</name> <section anchor="iana-considerations"><name>IANA Considerations</name>
<t>This document has no IANA actions.</t> <t>This document has no IANA actions.</t>
</section> </section>
</middle> </middle>
<back> <back>
<references><name>References</name>
<references><name>Normative References</name> <references><name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7469. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7515. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7517. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7469.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7518. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7468.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7519. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7515.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7638. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7517.xml"
xml"/> />
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8446. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7518.xml"
xml"/> />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml"
/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7638.xml"
/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"
/>
</references> </references>
<references><name>Informative References</name> <references><name>Informative References</name>
<reference anchor="EGIL" target="https://sambruk.se/egil-dnp/"> <reference quoteTitle="false" anchor="EGIL" target="https://sambruk.se/egil-dnp/ ">
<front> <front>
<title>EGIL – manage your school&#39;s digital user accounts efficiently</ti tle> <title>"EGIL – smidig hantering av skolans digitala användarkonton" [EGIL – manage your school's digital user accounts efficiently]</title>
<author> <author>
<organization>Sambruk</organization> <organization>Sambruk</organization>
</author> </author>
<date year="2022"></date>
</front> </front>
</reference> </reference>
<reference anchor="Moa" target="https://wiki.federationer.internetstiftelsen.se/ x/LYA5AQ"> <reference anchor="Moa" target="https://wiki.federationer.internetstiftelsen.se/ x/LYA5AQ">
<front> <front>
<title>Machine and Organization Authentication</title> <title>Machine and Organization Authentication</title>
<author> <author>
<organization>The Swedish Internet Foundation</organization> <organization>Internetstiftelsens Federationer [The Swedish Internet Found ation]</organization>
</author> </author>
<date year="2022"></date> <date day="6" month="10" year="2025"></date>
</front> </front>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8792. <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8792.xml"
xml"/> />
<reference anchor="SkolverketMATF" target="https://github.com/skolverket/dnp-use <reference quoteTitle="false" anchor="SkolverketMATF" target="https://github.com
rmanagement/blob/main/authentication-api/README.md"> /skolverket/dnp-usermanagement/blob/main/authentication-api/README.md">
<front> <front>
<title>Authentication API for User Management</title> <title>"API för autentisering" [Authentication API for User Management]</tit le>
<author> <author>
<organization>Swedish National Agency for Education</organization> <organization>Skolverket [Swedish National Agency for Education]</organiza tion>
</author> </author>
<date year="2023"></date> <date day="4" month="9" year="2025"></date>
</front> </front>
<refcontent>commit f8c2e93</refcontent>
</reference> </reference>
<reference anchor="eIDAS" target="https://eidas.ec.europa.eu/"> <reference anchor="eIDAS" target="https://eur-lex.europa.eu/eli/reg/2014/910/oj/ eng">
<front> <front>
<title>eIDAS: electronic Identification, Authentication and trust Services</ title> <title>Regulation (EU) No 910/2014 of the European Parliament and of the Cou ncil of 23 July 2014 on electronic identification and trust services for electro nic transactions in the internal market</title>
<author> <author>
<organization>European Commission</organization> <organization>European Union</organization>
</author> </author>
<date year="2014"></date> <date day="23" month="July" year="2014"/>
</front> </front>
<seriesInfo name="Official Journal of the European Union" value="L 257/73"/>
<seriesInfo name="ELI" value="http://data.europa.eu/eli/reg/2014/910/oj"/>
</reference> </reference>
<reference anchor="eduGAIN" target="https://edugain.org"> <reference anchor="eduGAIN" target="https://edugain.org">
<front> <front>
<title>eduGAIN: Interfederation service connecting research and education id entity federations worldwide</title> <title>eduGAIN: Interfederation service connecting research and education id entity federations worldwide</title>
<author> <author>
<organization>GÉANT Association</organization> <organization>eduGAIN</organization>
</author> </author>
<date year="2023"></date>
</front> </front>
</reference> </reference>
</references> </references>
</references>
<section anchor="json-schema-for-matf-metadata"><name>JSON Schema for MATF Metad ata</name> <section anchor="json-schema-for-matf-metadata"><name>JSON Schema for MATF Metad ata</name>
<t>The following JSON Schema defines the structure of MATF metadata. It conforms to draft 2020-12 of the JSON Schema standard.</t> <t>The following JSON Schema defines the structure of MATF metadata. It conforms to draft 2020-12 of the JSON Schema standard.</t>
<t>Version: 1.0.0</t> <t>Version: 1.0.0</t>
<sourcecode type="json">=============== NOTE: '\\' line wrapping per RFC 8792 == <sourcecode type="json"><![CDATA[
============= =============== NOTE: '\\' line wrapping per RFC 8792 ===============
{ {
&quot;$schema&quot;: &quot;https://json-schema.org/draft/2020-12/schema&quot "$schema": "https://json-schema.org/draft/2020-12/schema",
;, "$id": "https://mtlsfed.se/schema/matf-metadata-schema.json",
&quot;$id&quot;: &quot;https://mtlsfed.se/schema/matf-metadata-schema.json&q "title": "JSON Schema for Mutually Authenticating TLS in the con\
uot;, \text of Federations",
&quot;title&quot;: &quot;JSON Schema for Mutually Authenticating TLS in the "description": "Version: 1.0.0",
con\ "type": "object",
\text of Federations&quot;, "additionalProperties": true,
&quot;description&quot;: &quot;Version: 1.0.0&quot;, "required": [
&quot;type&quot;: &quot;object&quot;, "iat",
&quot;additionalProperties&quot;: true, "exp",
&quot;required&quot;: [ "iss",
&quot;iat&quot;, "version",
&quot;exp&quot;, "entities"
&quot;iss&quot;,
&quot;version&quot;,
&quot;entities&quot;
], ],
&quot;properties&quot;: { "properties": {
&quot;iat&quot;: { "iat": {
&quot;title&quot;: &quot;Issued at&quot;, "title": "Issued at",
&quot;description&quot;: &quot;Time at which the metadata was issued "description": "Time at which the metadata was issued (U\
(U\ \NIX timestamp)",
\NIX timestamp)&quot;, "type": "integer",
&quot;type&quot;: &quot;integer&quot;, "minimum": 0,
&quot;minimum&quot;: 0, "examples": [
&quot;examples&quot;: [
1755514949 1755514949
] ]
}, },
&quot;exp&quot;: { "exp": {
&quot;title&quot;: &quot;Expiration time&quot;, "title": "Expiration time",
&quot;description&quot;: &quot;Time at which the metadata expires (U "description": "Time at which the metadata expires (UNIX\
NIX\ \ timestamp)",
\ timestamp)&quot;, "type": "integer",
&quot;type&quot;: &quot;integer&quot;, "minimum": 0,
&quot;minimum&quot;: 0, "examples": [
&quot;examples&quot;: [
1756119888 1756119888
] ]
}, },
&quot;iss&quot;: { "iss": {
&quot;title&quot;: &quot;The federation issuing the metadata&quot;, "title": "The federation issuing the metadata",
&quot;description&quot;: &quot;A URI that uniquely identifies the fe "description": "A URI that uniquely identifies the feder\
der\ \ation that issued the metadata",
\ation that issued the metadata&quot;, "type": "string",
&quot;type&quot;: &quot;string&quot;, "format": "uri",
&quot;format&quot;: &quot;uri&quot;, "minLength": 1,
&quot;minLength&quot;: 1, "examples": [
&quot;examples&quot;: [ "https://example.com/federation"
&quot;https://example.com/federation&quot;
] ]
}, },
&quot;version&quot;: { "version": {
&quot;title&quot;: &quot;Metadata schema version&quot;, "title": "Metadata schema version",
&quot;description&quot;: &quot;Schema version follows semantic versi "description": "Schema version follows semantic versioni\
oni\ \ng (https://semver.org)",
\ng (https://semver.org)&quot;, "type": "string",
&quot;type&quot;: &quot;string&quot;, "pattern": "^\\d+\\.\\d+\\.\\d+$",
&quot;pattern&quot;: &quot;^\\d+\\.\\d+\\.\\d+$&quot;, "examples": [
&quot;examples&quot;: [ "1.0.0"
&quot;1.0.0&quot;
] ]
}, },
&quot;cache_ttl&quot;: { "cache_ttl": {
&quot;title&quot;: &quot;Metadata cache TTL&quot;, "title": "Metadata cache TTL",
&quot;description&quot;: &quot;How long in seconds to cache metadata "description": "How long in seconds to cache metadata. T\
. T\ \he effective maximum is bounded by the exp claim.",
\he effective maximum is bounded by the exp claim.&quot;, "type": "integer",
&quot;type&quot;: &quot;integer&quot;, "minimum": 0,
&quot;minimum&quot;: 0, "examples": [
&quot;examples&quot;: [
3600 3600
] ]
}, },
&quot;entities&quot;: { "entities": {
&quot;type&quot;: &quot;array&quot;, "type": "array",
&quot;minItems&quot;: 1, "minItems": 1,
&quot;items&quot;: { "items": {
&quot;$ref&quot;: &quot;#/$defs/entity&quot; "$ref": "#/$defs/entity"
} }
} }
}, },
&quot;$defs&quot;: { "$defs": {
&quot;entity&quot;: { "entity": {
&quot;type&quot;: &quot;object&quot;, "type": "object",
&quot;additionalProperties&quot;: true, "additionalProperties": true,
&quot;required&quot;: [ "required": [
&quot;entity_id&quot;, "entity_id",
&quot;issuers&quot; "issuers"
], ],
&quot;properties&quot;: { "properties": {
&quot;entity_id&quot;: { "entity_id": {
&quot;title&quot;: &quot;Entity identifier&quot;, "title": "Entity identifier",
&quot;description&quot;: &quot;Globally unique identifier fo "description": "Globally unique identifier for t\
r t\ \he entity.",
\he entity.&quot;, "type": "string",
&quot;type&quot;: &quot;string&quot;, "format": "uri",
&quot;format&quot;: &quot;uri&quot;, "examples": [
&quot;examples&quot;: [ "https://example.com"
&quot;https://example.com&quot;
] ]
}, },
&quot;organization&quot;: { "organization": {
&quot;title&quot;: &quot;Name of entity organization&quot;, "title": "Name of entity organization",
&quot;description&quot;: &quot;Name identifying the organiza "description": "Name identifying the organizatio\
tio\ \n that the entity's metadata represents.",
\n that the entity's metadata represents.&quot;, "type": "string",
&quot;type&quot;: &quot;string&quot;, "examples": [
&quot;examples&quot;: [ "Example Org"
&quot;Example Org&quot;
] ]
}, },
&quot;issuers&quot;: { "issuers": {
&quot;title&quot;: &quot;Entity certificate issuers&quot;, "title": "Entity certificate issuers",
&quot;description&quot;: &quot;A list of certificate issuers "description": "A list of certificate issuers th\
th\
\at are allowed to issue certificates for the entity's endpoints. Fo\ \at are allowed to issue certificates for the entity's endpoints. Fo\
\r each issuer, the issuer's root CA certificate is included in the \ \r each issuer, the issuer's root CA certificate is included in the \
\x509certificate property (PEM-encoded).&quot;, \x509certificate property (PEM-encoded).",
&quot;type&quot;: &quot;array&quot;, "type": "array",
&quot;minItems&quot;: 1, "minItems": 1,
&quot;items&quot;: { "items": {
&quot;$ref&quot;: &quot;#/$defs/cert_issuers&quot; "$ref": "#/$defs/cert_issuers"
} }
}, },
&quot;servers&quot;: { "servers": {
&quot;type&quot;: &quot;array&quot;, "type": "array",
&quot;items&quot;: { "items": {
&quot;$ref&quot;: &quot;#/$defs/endpoint&quot; "$ref": "#/$defs/endpoint"
} }
}, },
&quot;clients&quot;: { "clients": {
&quot;type&quot;: &quot;array&quot;, "type": "array",
&quot;items&quot;: { "items": {
&quot;$ref&quot;: &quot;#/$defs/endpoint&quot; "$ref": "#/$defs/endpoint"
} }
} }
} }
}, },
&quot;endpoint&quot;: { "endpoint": {
&quot;type&quot;: &quot;object&quot;, "type": "object",
&quot;additionalProperties&quot;: true, "additionalProperties": true,
&quot;required&quot;: [ "required": [
&quot;pins&quot; "pins"
], ],
&quot;properties&quot;: { "properties": {
&quot;description&quot;: { "description": {
&quot;title&quot;: &quot;Endpoint description&quot;, "title": "Endpoint description",
&quot;type&quot;: &quot;string&quot;, "type": "string",
&quot;examples&quot;: [ "examples": [
&quot;SCIM Server 1&quot; "SCIM Server 1"
] ]
}, },
&quot;tags&quot;: { "tags": {
&quot;title&quot;: &quot;Endpoint tags&quot;, "title": "Endpoint tags",
&quot;description&quot;: &quot;A list of strings that descri "description": "A list of strings that describe \
be \ \the endpoint's capabilities.",
\the endpoint's capabilities.&quot;, "type": "array",
&quot;type&quot;: &quot;array&quot;, "items": {
&quot;items&quot;: { "type": "string",
&quot;type&quot;: &quot;string&quot;, "pattern": "^[a-z0-9]{1,64}$",
&quot;pattern&quot;: &quot;^[a-z0-9]{1,64}$&quot;, "examples": [
&quot;examples&quot;: [ "xyzzy"
&quot;xyzzy&quot;
] ]
} }
}, },
&quot;base_uri&quot;: { "base_uri": {
&quot;title&quot;: &quot;Endpoint base URI&quot;, "title": "Endpoint base URI",
&quot;type&quot;: &quot;string&quot;, "type": "string",
&quot;format&quot;: &quot;uri&quot;, "format": "uri",
&quot;examples&quot;: [ "examples": [
&quot;https://scim.example.com&quot; "https://scim.example.com"
] ]
}, },
&quot;pins&quot;: { "pins": {
&quot;title&quot;: &quot;Certificate pin set&quot;, "title": "Certificate pin set",
&quot;type&quot;: &quot;array&quot;, "type": "array",
&quot;minItems&quot;: 1, "minItems": 1,
&quot;items&quot;: { "items": {
&quot;$ref&quot;: &quot;#/$defs/pin_directive&quot; "$ref": "#/$defs/pin_directive"
} }
} }
} }
}, },
&quot;cert_issuers&quot;: { "cert_issuers": {
&quot;title&quot;: &quot;Certificate issuers&quot;, "title": "Certificate issuers",
&quot;type&quot;: &quot;object&quot;, "type": "object",
&quot;additionalProperties&quot;: false, "additionalProperties": false,
&quot;required&quot;: [ "required": [
&quot;x509certificate&quot; "x509certificate"
], ],
&quot;properties&quot;: { "properties": {
&quot;x509certificate&quot;: { "x509certificate": {
&quot;title&quot;: &quot;X.509 Certificate (PEM)&quot;, "title": "X.509 Certificate (PEM)",
&quot;type&quot;: &quot;string&quot;, "type": "string",
&quot;pattern&quot;: &quot;^-----BEGIN CERTIFICATE-----(?:\\ "pattern": "^-----BEGIN CERTIFICATE-----(?:\\r?\\
r?\\
\\n)(?:[A-Za-z0-9+/=]{64}\\r?\\n)*(?:[A-Za-z0-9+/=]{1,64}\\r?\\n)---\ \\n)(?:[A-Za-z0-9+/=]{64}\\r?\\n)*(?:[A-Za-z0-9+/=]{1,64}\\r?\\n)---\
\--END CERTIFICATE-----(?:\\r?\\n)?$&quot; \--END CERTIFICATE-----(?:\\r?\\n)?$"
} }
} }
}, },
&quot;pin_directive&quot;: { "pin_directive": {
&quot;title&quot;: &quot;RFC 7469 pin directive&quot;, "title": "RFC 7469 pin directive",
&quot;type&quot;: &quot;object&quot;, "type": "object",
&quot;additionalProperties&quot;: false, "additionalProperties": false,
&quot;required&quot;: [ "required": [
&quot;alg&quot;, "alg",
&quot;digest&quot; "digest"
], ],
&quot;properties&quot;: { "properties": {
&quot;alg&quot;: { "alg": {
&quot;title&quot;: &quot;Directive name&quot;, "title": "Directive name",
&quot;type&quot;: &quot;string&quot;, "type": "string",
&quot;enum&quot;: [ "enum": [
&quot;sha256&quot; "sha256"
], ],
&quot;examples&quot;: [ "examples": [
&quot;sha256&quot; "sha256"
] ]
}, },
&quot;digest&quot;: { "digest": {
&quot;title&quot;: &quot;Directive value (Base64)&quot;, "title": "Directive value (Base64)",
&quot;type&quot;: &quot;string&quot;, "type": "string",
&quot;pattern&quot;: &quot;^[A-Za-z0-9+/]{43}=$&quot;, "pattern": "^[A-Za-z0-9+/]{43}=$",
&quot;examples&quot;: [ "examples": [
&quot;HiMkrb4phPSP+OvGqmZd6sGvy7AUn4k3XEe8OMBrzt8\ "HiMkrb4phPSP+OvGqmZd6sGvy7AUn4k3XEe8OMBrzt8\
\=&quot; \="
] ]
} }
} }
} }
} }
} }]]></sourcecode>
</sourcecode>
</section> </section>
</back> <section anchor="acknowledgements" numbered="false"><name>Acknowledgements</name
>
<t>This project was funded through the NGI0 PET Fund, a fund established by NLne
t with financial support from the European Commission's Next Generation Internet
programme, under the aegis of DG Communications Networks, Content and Technolog
y under grant agreement No 825310.</t>
<t>The authors thank the following people for the detailed review and suggestion
s:</t>
<ul>
<li><t><contact fullname="Rasmus Larsson"/></t></li>
<li><t><contact fullname="Mats Dufberg"/></t></li>
<li><t><contact fullname="Joe Siltberg"/></t></li>
<li><t><contact fullname="Stefan Norberg"/></t></li>
<li><t><contact fullname="Petter Blomberg"/></t></li>
</ul>
<t>The authors would also like to thank participants in the EGIL working group f
or their comments on this specification.</t>
</section>
</back>
</rfc> </rfc>
 End of changes. 166 change blocks. 
745 lines changed or deleted 863 lines changed or added

This html diff was produced by rfcdiff 1.48.