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;">
]>
<!-- [rfced] Would you like the references to be alphabetized
or left in their current order? -->
<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="false" to
cInclude="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="February"/>
<!-- [rfced] Please insert any keywords (beyond those that appear in
the title) for use on https://www.rfc-editor.org/search. -->
<keyword>example</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 the context of Fed
erations (MATF) framework, developed to complement multilateral SAML federations erations (MATF) framework, developed to complement multilateral Security Asserti
within the education sector. These federations often rely on just-in-time provi on Markup Language (SAML) federations within the education sector. These federat
sioning, where user accounts are created at first login based on information fro ions often rely on just-in-time provisioning, where user accounts are created at
m the SAML assertion. However, educators need to be able to manage resources and first login based on information from the SAML assertion. However, educators ne
classes before students access the service. MATF bridges this gap by using secu ed to be able to manage resources and classes before students access the service
re machine-to-machine communication, enabling pre-provisioning of user informati . MATF bridges this gap by using secure machine-to-machine communication, enabli
on using a trust model and metadata structure inspired by SAML federations.</t> ng pre-provisioning of user information using a trust model and metadata structu
re inspired by SAML federations.</t>
<t>MATF is designed specifically for secure authentication in machine-to-machine contexts, such as RESTful APIs and service-to-service interactions, and is not intended for browser-based authentication. Because its applicability in a browse r environment has not been studied, using MATF within browsers is not recommende d. Doing so may introduce risks that differ from those typically addressed by st andard browser security models.</t> <t>MATF is designed specifically for secure authentication in machine-to-machine contexts, such as RESTful APIs and service-to-service interactions, and is not intended for browser-based authentication. Because its applicability in a browse r environment has not been studied, using MATF within browsers is not recommende d. Doing so may introduce risks that differ from those typically addressed by st andard 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> federation metadata signing key, which verifies the federation metadata and all
</ul> ows participants 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, the electronic Identification, Authentic ation, and trust Services (eIDAS) 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>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 rall trust framework that enables secure and reliable communication within the f ederation. Federation members submit member metadata to the federation. Both the authenticity of the submitted member metadata and the submitting member need to be ensured by the federation.</t> <t>By fulfilling these responsibilities, federation members help sustain the ove rall trust framework that enables secure and reliable communication within the f ederation. Federation members submit member metadata to the federation. Both the authenticity of the submitted member metadata and the submitting member need to be ensured by the federation.</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 man-in- the-middle attacks by ensuring validated certificates.</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 ata, which combines all members' member metadata along with additional federatio n-specific information. By placing trust in the federation and its associated si gning key, federation members trust the information contained within the federat ion metadata.</t> <t>The federation operator aggregates, signs, and publishes the federation metad ata, which combines all members' member metadata along with additional federatio n-specific information. By placing trust in the federation and its associated si gning key, federation members trust the information contained within the federat ion 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's s
igning key, a critical component requiring secure distribution and verification. igning key, a critical component requiring secure distribution and verification.
To achieve this, the federation's signing key is distributed using a JSON Web K To achieve this, the federation's signing key is distributed using a JSON Web K
ey Set (JWKS) <xref target="RFC7517"></xref>, providing a flexible framework for ey (JWK) Set <xref target="RFC7517"/>, providing a flexible framework for exposi
exposing multiple keys, including the signing key and keys for rollover. This s ng multiple keys, including the signing key and keys for rollover. This structur
tructured approach ensures members can readily access the necessary keys for ver ed approach ensures members can readily access the necessary keys for verificati
ification purposes.</t> on 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 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"/>.</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 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"/>, can serve as a useful reference.</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 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>
</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 licies and vet new members before they are added to the repository.</li> <li>Member Management: The federation operator can centrally enforce security po 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 ccess to the repository.</li> <li>Access Controls: Only authorized members within the federation should have a ccess to the repository.</li>
<li>Regular Backups: Robust backup procedures ensure data recovery in case of un 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 aims to verify the accuracy, completeness, and validity of the information provided by a member. The validation process <bcp14>MUST</bcp14> include, at a minimum but n ot limited to, the following checks:</t>
<ul> <ul>
<li>Format Validation: The system checks if the submitted metadata adheres to th e defined schema and format specifications.</li> <li>Format Validation: The system checks if the submitted metadata adheres to th e defined schema and format specifications.</li>
<li>Unique Entity ID: Checks are performed to ensure that the entity_id in the s ubmitted metadata is not already registered by another member. Each entity withi n the federation must have a unique identifier.</li> <li>Unique Entity ID: Checks are performed to ensure that the entity_id in the s ubmitted metadata is not already registered by another member. Each entity withi n the federation must have a unique identifier.</li>
<li>Unique Public Key Pins: Public key pins <xref target="RFC7469"></xref> are u <li>Unique Public Key Pins: Public key pins <xref target="RFC7469"/> are used to
sed to identify client entities within the federation metadata during the connec identify client entities within the federation metadata during the connection v
tion validation process. When a server validates a client's TLS connection, it e alidation process. When a server validates a client's TLS connection, it extract
xtracts the pin from the client's TLS certificate and matches it against entries s the pin from the client's TLS certificate and matches it against entries in th
in the federation metadata. The requirements for pin uniqueness and usage are d e federation metadata. The requirements for pin uniqueness and usage are detaile
etailed in <xref target="servers-clients"></xref>.</li> d in <xref target="servers-clients"/>.</li>
<li>Certificate Verification: The issuer certificates listed in the metadata are <li>Certificate Verification: The issuer certificates listed in the metadata are
validated to ensure that the algorithms used in the certificates are well-known validated to ensure that the algorithms used in the certificates are well known
and secure, and that the certificates are currently valid and have not expired< and secure, and that the certificates are currently valid and have not expired.
/li> </li>
<li>Tag Validation: Ensures that tags, as defined in <xref target="servers-clien <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 ts"/>) in the metadata adhere to the defined tag structure, verifying both manda
mandatory and optional tags. This process is crucial for maintaining consistency tory and optional tags. This process is crucial for maintaining consistency and
and preventing unauthorized tags within a federation.</li> preventing unauthorized tags within a federation.</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 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>
<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 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 <bcp14>MUST</bcp14> be taken to verify the authenticity and integrity of the metadata. Such measures may include verifying the checksum of the metadata thro ugh another channel. The choice of submission channel may depend on factors such as the federation's guidelines and the preferences 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 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 can lead to issues like failed connections, discovery challenges, and potential security risks.</li> <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 rmation about all members within the federation. Outdated information in the JWS can lead to issues like failed connections, discovery challenges, and potential security risks.</li>
<li>Local Metadata: Each member maintains a local metadata store containing info rmation about other members within the federation. This information is retrieved from the federation's publicly accessible JWS. Outdated data in the local store can hinder a member's ability to discover and connect with other relevant entit ies.</li> <li>Local Metadata: Each member maintains a local metadata store containing info rmation about other members within the federation. This information is retrieved from the federation's publicly accessible JWS. Outdated data in the local store can hinder a member's ability to discover and connect with other relevant entit 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 <!-- [rfced] In the text below, should "as defined in Section 6.4" be "as
but not limited to, expiration and cache time management.</li> defined in Section 6.1" instead? We ask because "exp" appears to be defined in
<li>Implementing mechanisms to update the published federation metadata, ensurin Section 6.1, not Section 6.4.
g it adheres to the expiration time (exp as defined in <xref target="metadata-si
gning"></xref>) and cache TTL (cache_ttl as defined in <xref target="federation- Original:
metadata-claims"></xref>) specifications.</li>
- Implementing mechanisms to update the published federation
metadata, ensuring it adheres to the expiration time (exp as
defined in Section 6.4) and cache TTL (cache_ttl as defined in
Section 6.1) specifications.
Perhaps:
- Implementing mechanisms to update the published federation
metadata, ensuring it adheres to the expiration time (exp as
defined in Section 6.1) and cache TTL (cache_ttl as defined in
Section 6.1) specifications.
-->
<li>Defining regulations for metadata management that <bcp14>MUST</bcp14> includ
e, at a minimum but not limited to, expiration and cache time management.</li>
<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
gning"/>) and cache TTL (cache_ttl as defined in <xref target="federation-metada
ta-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 regulations and refresh their local metadata store according to the defin ed expiration 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 leverages mutual TLS auth entication, as defined in <xref target="RFC8446"/>. This mechanism ensures the a uthenticity 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 as specified in <xref target="RFC7469"/>. Public key pinning associates one or more unique public keys with each endpoint within the federation, stored in the federation metadata. During a connection, c lients and servers extract the public key from the received certificate and vali date it against the preconfigured public key pins retrieved from the federation metadata.</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. 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>
</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 (CA s), servers and clients rely on the federation's mechanisms to validate trust. P ublic key pinning ensures that only the specific self-signed public keys, identi fied 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 ess can be complex and slow. This complexity arises because not only the comprom ised certificate but potentially multiple certificates within <t>If any certificate in a certificate chain is compromised, the revocation proc ess can be complex and slow. This complexity arises because not only the comprom ised certificate but potentially multiple certificates within
the chain might need to be revoked and reissued. Public key pinning mitigates th is complexity by allowing clients to explicitly trust a specific public key, the reby reducing dependency on the entire certificate chain's integrity.</t> the chain might need to be revoked and reissued. Public key pinning mitigates th is complexity by allowing clients to explicitly trust a specific public key, the reby reducing dependency on the entire certificate chain's integrity.</t>
<t>If a leaf certificate is compromised within a MATF federation, the revocation process involves removing the pin associated with the compromised certificate a nd publishing updated metadata that includes a new pin corresponding to the repl acement certificate. This approach eliminates reliance on traditional certificat e revocation mechanisms and shifts the trust relationship to the specific, updat ed public key identified by its pin.</t> <t>If a leaf certificate is compromised within a MATF federation, the revocation process involves removing the pin associated with the compromised certificate a nd publishing updated metadata that includes a new pin corresponding to the repl acement certificate. This approach eliminates reliance on traditional certificat e revocation mechanisms and shifts the trust relationship to the specific, updat 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 retrieve these unique public key pins, serving as pre
-configured trust parameters, from the federation metadata. The federation MUST configured trust parameters, from the federation metadata. The federation <bcp14
facilitate the discovery process, allowing peers to identify the relevant pins f >MUST</bcp14> facilitate the discovery process, allowing peers to identify the r
or each endpoint. Information such as organization, tags, and descriptions withi elevant pins for each endpoint. Information such as organization, tags, and desc
n the federation metadata supports this discovery.</t> riptions within the federation metadata supports this discovery.</t>
<t>Before initiating any connection, clients and servers MUST preload the design <t>Before initiating any connection, clients and servers <bcp14>MUST</bcp14> pre
ated pins from the federation metadata. This aligns with the principle described load the designated pins from the federation metadata. This aligns with the prin
in Section 2.7 of <xref target="RFC7469"></xref>, which introduces optional sou ciple described in <xref target="RFC7469" section="2.7"/>, which introduces opti
rces for pinning information, with the federation metadata serving as one such s onal sources for pinning information, with the federation metadata serving as on
ource. Preloading pins restricts connections to endpoints with matching public k e such source. Preloading pins restricts connections to endpoints with matching
eys, mitigating the risks posed by fraudulent certificates.</t> public keys, mitigating the risks posed by fraudulent 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 leverage public key pinning or validate the received certificate against the pu blished pins. Additionally, the federation metadata contains issuer information, which implementations MAY optionally use to verify certificate issuers. This st ep remains at the discretion of each individual implementation.</t> <t>Upon connection establishment, both endpoints, client and server, must either leverage public key pinning or validate the received certificate against the pu blished pins. Additionally, the federation metadata contains issuer information, which implementations <bcp14>MAY</bcp14> optionally use to verify certificate i ssuers. This step remains at the discretion of each individual implementation.</ t>
<t>In scenarios where a TLS session terminates independent of the application (e .g., via a reverse proxy), the termination point can utilize optional untrusted TLS client certificate authentication or validate the certificate issuer itself. Depending on the specific implementation, pin validation can then be deferred t o the application itself, assuming the peer certificate is appropriately transfe rred (e.g., via an HTTP header).</t> <t>In scenarios where a TLS session terminates independent of the application (e .g., via a reverse proxy), the termination point can utilize optional untrusted TLS client certificate authentication or validate the certificate issuer itself. Depending on the specific implementation, pin validation can then be deferred t o the application itself, assuming the peer certificate is appropriately transfe rred (e.g., via an HTTP header).</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 strict enforcement ensures that only authorized and secure communication channels are established within the fed eration.</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 lowing procedure must be followed:</t> <t>To replace a certificate, whether due to expiration or other reasons, the fol lowing procedure must be followed:</t>
<ol> <ol>
<li>Publishing New Metadata: When a certificate needs to be changed, federation members publish new metadata containing the pin (SHA256 thumbprint) of the new p ublic key. This ensures that the new pin is available to all federation members. </li> <li>Publishing New Metadata: When a certificate needs to be changed, federation members publish new metadata containing the pin (SHA256 thumbprint) of the new p ublic key. This ensures that the new pin is available to all federation members. </li>
<li>Propagation Period: Allow time for the updated metadata to propagate through out the federation before switching to the new certificate. This overlap period ensures that all nodes recognize the new pin and avoid connection issues.</li> <li>Propagation Period: Allow time for the updated metadata to propagate through out the federation before switching to the new certificate. This overlap period ensures that all nodes recognize the new pin and avoid connection issues.</li>
<li>Switching to the New Certificate: After ensuring the new metadata has propag ated, members switch to the new certificate in their TLS stack.</li> <li>Switching to the New Certificate: After ensuring the new metadata has propag ated, members switch to the new certificate in their TLS stack.</li>
<li>Removing Old Pin: After successfully switching to the new certificate, membe rs must publish updated metadata that excludes the old pin. This final step ensu res that only the current public keys are trusted.</li> <li>Removing Old Pin: After successfully switching to the new certificate, membe rs must publish updated metadata that excludes the old pin. This final step ensu res that only the current public keys are trusted.</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 or by deferring validation to the application.</t> <t>Public key validation <bcp14>MUST</bcp14> always be enforced, either through direct pinning or by deferring validation to the application.</t>
<t>For clients, public key validation typically occurs within the application ha ndling the TLS session, either by enforcing direct pinning or by extracting and validating the public key against the published pins.</t> <t>For clients, public key validation typically occurs within the application ha ndling the TLS session, either by enforcing direct pinning or by extracting and validating the public key against the published pins.</t>
<t>For servers, validation depends on deployment. If the application terminates the TLS session, it performs direct pinning or extracts and validates the public key. If a reverse proxy terminates the TLS session, it can enforce direct pinni ng or forward the certificate to the application (e.g., via an HTTP header) for validation.</t> <t>For servers, validation depends on deployment. If the application terminates the TLS session, it performs direct pinning or extracts and validates the public key. If a reverse proxy terminates the TLS session, it can enforce direct pinni ng or forward the certificate to the application (e.g., via an HTTP header) for validation.</t>
<t>Implementations SHOULD, when possible, rely on libraries with native support <t>Implementations <bcp14>SHOULD</bcp14>, when possible, rely on libraries with
for pinning. Libcurl, for example, supports pinning via the PINNEDPUBLICKEY opti native support for pinning. Libcurl, for example, supports pinning via the PINNE
on. In Python, the cryptography library can extract public keys, while the reque DPUBLICKEY option. In Python, the cryptography library can extract public keys,
sts package together with urllib3 can intercept certificates. Go provides crypto while the requests package together with urllib3 can intercept certificates. Go
/tls and crypto/x509 for certificate inspection and public key extraction. In Ja provides crypto/tls and crypto/x509 for certificate inspection and public key ex
va, java.security.cert.X509Certificate enables public key extraction, while java traction. In Java, java.security.cert.X509Certificate enables public key extract
.net.http.HttpClient allows pinning enforcement using a custom SSLContext and Tr ion, while java.net.http.HttpClient allows pinning enforcement using a custom SS
ustManager. The choice of library is left to the discretion of each implementati LContext and TrustManager. The choice of library is left to the discretion of ea
on.</t> ch implementation.</t>
<t>If bypassing standard CA validation is possible, it SHOULD be done. If not, t <t>If bypassing standard CA validation is possible, it <bcp14>SHOULD</bcp14> be
he issuers listed in the federation metadata MUST be used as the trust store to done. If not, the issuers listed in the federation metadata <bcp14>MUST</bcp14>
validate certificate issuers while still enforcing key pinning. Without issuer v be used as the trust store to validate certificate issuers while still enforcing
alidation against issuers in metadata, self-signed certificates would not be acc key pinning. Without issuer validation against issuers in metadata, self-signed
epted. These mechanisms ensure compatibility with existing TLS infrastructure wh certificates would not be accepted. These mechanisms ensure compatibility with
ile maintaining strict security guarantees.</t> existing TLS infrastructure while maintaining strict security guarantees.</t>
</section> </section>
</section> </section>
<!-- [rfced] Should "federation members entities" be updated as follows (to
indicate that multiple federation members possess multiple entities)?
Original:
The payload contains statements about federation members entities.
Perhaps:
The payload contains statements about entities of federation members.
-->
<!-- [rfced] For clarity, may we update this sentence as follows?
Original:
The client then uses the selected server claims base_uri, pins and if
needed issuers to establish a connection.
Perhaps:
To establish a connection, the client then uses the base_uri, pins, and, if
needed, issuers of the selected server claims.
-->
<!-- [rfced] Sections 6.1 and 6.1.1: We note mixed use of quotation marks and/or
<tt> tags around the "Example" list items in these sections. Should any of thes
e items be updated for consistency?
-->
<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 payload contains statements <t>Federation metadata is published as a JWS <xref target="RFC7515"/>. The paylo ad contains statements
about federation members entities.</t> about federation members entities.</t>
<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 s the selected server claims base_uri, pins and if needed issuers to establish a connection.</t> <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 s the selected server claims base_uri, pins and if needed issuers to establish a connection.</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> <t>Upon receiving a connection, a server validates the received client certifica te using the client's published pins. A server <bcp14>MAY</bcp14> also check oth er claims such as organization and tags to determine if the connection is accept ed 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: 1755514949</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 exp 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: 1756119888</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 iss claim enables recipients to determine the
the identified federation.</t> 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: URI as defined in <xref target="RFC7519" sectionFormat="comma" sec
> tion="4.1.1"/>.</li>
<li>Example: <tt>&quot;https://federation.example.org&quot;</tt></li> <li>Example: "https://federation.example.org"</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: Must adhere to Semantic Versioning (see <eref target="https://semver
">https://semver.org</eref>).</li> .org" brackets="angle"/>).</li>
<li>Example: <tt>&quot;1.0.0&quot;</tt></li> <li>Example: "1.0.0"</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>Specifies the duration in seconds for caching downloaded federation metadata,
allowing for independent caching outside of specific HTTP configurations, parti allowing for independent caching outside of specific HTTP configurations; this
cularly useful when the communication mechanism isn't HTTP-based. In the event o is particularly useful when the communication mechanism isn't HTTP based. In the
f a metadata publication outage, members can rely on cached metadata until it ex event of a metadata publication outage, members can rely on cached metadata unt
pires, as indicated by the exp claim in the JWS payload, defined in <xref target il it expires, as indicated by the exp claim in the JWS payload, defined in <xre
="metadata-signing"></xref>. Once expired, metadata MUST no longer be trusted. I f target="metadata-signing"/>. Once expired, metadata <bcp14>MUST</bcp14> no lon
f omitted, a mechanism to refresh metadata MUST still exist to ensure the metada ger be trusted. If omitted, a mechanism to refresh metadata <bcp14>MUST</bcp14>
ta remains valid.</t> 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 entity_id within the federation or within any other
t the entity interacts with.</t> federation that the entity interacts with.</t>
<ul> <ul>
<li>Data Type: URI</li> <li>Data Type: URI</li>
<li>Syntax: A valid URI.</li> <li>Syntax: A valid URI.</li>
<li>Example: <tt>&quot;https://example.com&quot;</tt></li> <li>Example: <tt>&quot;https://example.com&quot;</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 a mechanism is in place to veri
anization claim corresponds to the rightful owner of the information exchanged b fy that the organization claim corresponds to the rightful owner of the informat
etween nodes. This is crucial for the trust model, ensuring certainty about the ion exchanged between nodes. This is crucial for the trust model, ensuring certa
identities of the involved parties. The federation operator SHOULD choose an app inty about the identities of the involved parties. The federation operator <bcp1
roach that best suits the specific needs and trust model of the federation.</t> 4>SHOULD</bcp14> choose an approach that best suits the specific needs and trust
model of the federation.</t>
<!-- [rfced] How may we update "PEM-encoded" in the two instances below for clar
ity?
In addition, note that we have expanded "PEM"; please review and let us know if
any corrections are needed.
Original:
For each issuer, the issuer's root CA certificate MUST be included in the
x509certificate property, PEM- encoded.
- Syntax: Each object contains a issuer certificate, PEM-encoded.
Perhaps:
For each issuer, the issuer's root CA certificate MUST be included in the
x509certificate property and be encoded by Privacy-Enhanced Mail (PEM).
- Syntax: Each object contains a PEM-encoded issuer certificate.
-->
<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>&quot;Example Org&quot;</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 x509certificate property, PEM-encoded. Certificate verificat
ublic key pinning, with the list of allowed issuers used only when a certificate ion relies on public key pinning, with the list of allowed issuers used only whe
chain validation mechanism is unavoidable. For self-signed certificates, the ce n a certificate chain validation mechanism is unavoidable. For self-signed certi
rtificate itself acts as its own issuer and MUST be listed as such in the metada ficates, the certificate itself acts as its own issuer and <bcp14>MUST</bcp14> b
ta.</t> e listed as such in the metadata.</t>
<ul> <ul>
<li>Data Type: List of Objects</li> <li>Data Type: List of Objects</li>
<li>Syntax: Each object contains a issuer certificate, PEM-encoded.</li> <li>Syntax: Each object contains an issuer certificate, PEM-encoded.</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>&quot;SCIM Server 1&quot;</tt></li>
</ul></li> </ul></li>
<li><t>base_uri (OPTIONAL)</t> <li><t>base_uri (<bcp14>OPTIONAL</bcp14>)</t>
<t>The base URL of the server, which is required for endpoints that describe ser <t>The base URL of the server, which is required for endpoints that describe ser
ver.</t> vers.</t>
<ul> <ul>
<li>Data Type: URI</li> <li>Data Type: URI</li>
<li>Syntax: A valid URL.</li> <li>Syntax: A valid URL.</li>
<li>Example: <tt>&quot;https://scim.example.com/&quot;</tt></li> <li>Example: <tt>&quot;https://scim.example.com/&quot;</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>&quot;sha256&quot;</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 Ke
y Information (SPKI) fingerprint, as specified in Section 2.4 of <xref target="R y Information (SPKI) fingerprint, as specified in <xref target="RFC7469" section
FC7469"></xref>. For clients, the digest MUST be globally unique for unambiguous ="2.4"/>. For clients, the digest <bcp14>MUST</bcp14> be globally unique for una
identification. However, within the same entity_id object, the same digest MAY mbiguous identification. However, within the same entity_id object, the same dig
be assigned to multiple clients.</t> est <bcp14>MAY</bcp14> 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>&quot;+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=&quot;</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>[&quot;scim&quot;, &quot;xyzzy&quot;]</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 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> </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 <t>Note: The schema in <xref target="json-schema-for-matf-metadata"/> is folded
ecified in <xref target="RFC8792"></xref>.</t> due to line length limitations as specified in <xref target="RFC8792"/>.</t>
</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 within the issuers' claim is for readability only.</t>
<sourcecode type="json">{ <sourcecode type="json"><![CDATA[
&quot;exp&quot;: 1755514949, {
&quot;iat&quot;: 1756119888, "exp": 1755514949,
&quot;iss&quot;: &quot;https://federation.example.org&quot;, "iat": 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 <em>ECDSA using P-256 and SHA-256</em> (&quot;
t;) as defined in <xref target="RFC7518"></xref>. However, to accommodate evolvi ES256&quot;) as defined in <xref target="RFC7518"/>. However, to accommodate evo
ng cryptographic standards, alternative algorithms MAY be used, provided they me lving cryptographic standards, alternative algorithms <bcp14>MAY</bcp14> be used
et the security requirements of the federation.</t> , provided they meet the security requirements of the federation.</t>
<t>The following protected JWS header parameters are REQUIRED:</t> <t>The following protected JWS 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 signing key in the key set used to sign the JWS <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.</t>
<t>The following example describes a scenario within the federation &quot;Skolfe deration&quot; where MATF is already established. Both clients and servers are r egistered members of the federation. In this scenario, clients aim to manage cro ss-domain user accounts within the service. The standard used for account manage ment is SS 12000:2018 (i.e., a SCIM extension).</t> <t>The following example describes a scenario within the federation &quot;Skolfe deration&quot; where MATF is already established. Both clients and servers are r egistered members of the federation. In this scenario, clients aim to manage cro ss-domain user accounts within the service. The standard used for account manage ment is SS 12000:2018 (i.e., a System for Cross-domain Identity Management (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 | | Client | | Reverse| | App |
| +--(D)-->+ Proxy +--(E)--&gt;+ | | +--(D)-->+ Proxy +--(E)--&gt;+ |
| | | | | | | | | | | |
| | | | | | | | | | | |
+--------+ +--------+ +--------+ +--------+ +--------+ +--------+]]></artwork>
</sourcecode>
--------+ +--------+ <span class="insert">+--------+]]&gt;&lt;/art work&gt;</span>
<ol type="A"> <ol type="A">
<li>Entities collect member metadata from the federation metadata.</li> <li>Entities collect member metadata from the federation metadata.</li>
<li>The client pins the server's public key pins.</li> <li>The client pins the server's public key pins.</li>
<li>The reverse proxy trust anchor is setup with the clients' certificate issuer s.</li> <li>The reverse proxy trust anchor is setup with the clients' certificate issuer s.</li>
<li>The client establishes a connection with the server using the base_uri from the federation metadata.</li> <li>The client establishes a connection with the server using the base_uri from the federation metadata.</li>
<li>The reverse proxy forwards the client certificate to the application.</li> <li>The reverse proxy forwards the client certificate to the application.</li>
<li>The application converts the certificate to a public key pin and checks the federation metadata for a matching pin. The entity's entity_id should be used as an identifier.</li> <li>The application converts the certificate to a public key pin and checks the federation metadata for a matching pin. The entity's entity_id should be used as an identifier.</li>
</ol> </ol>
<section anchor="client"><name>Client</name> <section anchor="client"><name>Client</name>
<t>A certificate is issued for the client and the issuer is published in the fed eration metadata together with the client's certificate public key pins</t> <t>A certificate is issued for the client and the issuer is published in the fed eration metadata together with the client's certificate public key pins.</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> <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> <ol>
<li>Find possible server candidates by filtering the remote entity's list of ser vers based on tags.</li> <li>Find possible server candidates by filtering the remote entity's list of ser vers based on tags.</li>
<li>Connect to the server URI. Include the entity's list of certificate issuers in the TLS clients list of trusted CAs, or trust the listed pins explicitly.</li > <li>Connect to the server URI. Include the entity's list of certificate issuers in the TLS clients list of trusted CAs, or trust the listed pins explicitly.</li >
<li>If pinning is not used during the TLS handshake, the client MUST perform a p ost-connection validation against the entity's published pins.</li> <li>If pinning is not used during the TLS handshake, the client <bcp14>MUST</bcp 14> perform a post-connection validation against the entity's published pins.</l i>
<li>Commence transactions.</li> <li>Commence transactions.</li>
</ol> </ol>
</section> </section>
<section anchor="server"><name>Server</name> <section anchor="server"><name>Server</name>
<t>A certificate is issued for the server and the issuer is published in the fed eration metadata together with the server's name and certificate public key pin. </t> <t>A certificate is issued for the server and the issuer is published in the fed eration metadata together with the server's name and certificate public key pin. </t>
<t>When the server receives a connection from a remote client, the following ste ps need to be taken:</t> <t>When the server receives a connection from a remote client, the following ste ps need to be taken:</t>
<ol> <ol>
<li>Populate list of trusted CAs using all known entities' published issuers and required TLS client certificate authentication, or configure optional untrusted TLS client certificate authentication (e.g., optional_no_ca).</li> <li>Populate list of trusted CAs using all known entities' published issuers and required TLS client certificate authentication, or configure optional untrusted TLS client certificate authentication (e.g., optional_no_ca).</li>
<li>Once a connection has been accepted, validate the received client certificat e using the client's published pins.</li> <li>Once a connection has been accepted, validate the received client certificat e using the client's published pins.</li>
<li>Commence transactions.</li> <li>Commence transactions.</li>
</ol> </ol>
</section> </section>
<!-- [rfced] FYI - We have adjusted the items below to make them complete
sentences. Please review.
Original:
7.3. SPKI Generation
Example of how to use OpenSSL to generate a SPKI fingerprint from a
PEM-encoded certificate.
7.4. Curl and Public Key Pinning
Example of public key pinning with curl. Line breaks are for
readability only.
Current:
7.3. SPKI Generation
The following is an example of how to use OpenSSL to generate a SPKI
fingerprint from a PEM-encoded certificate.
7.4. Curl and Public Key Pinning
The following is an example of public key pinning with curl. Line
breaks are for readability only.
-->
<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. Line breaks are for readability only.</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 --pinnedpubkey 'sha256//0Ok
2aNfcrCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' https://host.example.com 2aNfcrCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' https://host.example.com]]></source
</sourcecode> code>
</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 cure communication between digital educational resources and schools. MATF is de veloped to meet Moa's needs and enables secure data exchange for schools, munici palities, educational platforms, and services across Sweden.</t> <t>Skolfederation Moa <xref target="Moa"/> is a federation designed to secure co mmunication between digital educational resources and schools. MATF is developed to meet Moa's needs and enables secure data exchange for schools, municipalitie s, educational platforms, and services across Sweden.</t>
<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 eir needs. Moa's success highlights the importance of collaboration, with member s and the FO working together to maintain trust, security, and interoperability in the education sector.</t> <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 eir needs. Moa's success highlights the importance of collaboration, with member s and the FO working together to maintain trust, 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 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>
</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 dividual federation. Both the federation operator and federation members share t he responsibility of maintaining trust and security within the federation. Prope r handling and management of metadata, as well as thorough vetting of federation members, are crucial to sustaining this trust and security. Each federation ope rates within a trust framework, which includes its own security policies and pro cedures to ensure the integrity and reliability of the federation.</t> <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 he responsibility of maintaining trust and security within the federation. Prope r handling and management of metadata, as well as thorough vetting of federation members, are crucial to sustaining this trust and security. Each federation ope rates within a trust framework, which includes its own security policies and pro cedures to ensure the integrity and reliability of the federation.</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 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"/>, which describes security considerations related to algorithm 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.8174.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.7469.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.7515.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.7517.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.7518.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.7519.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.7638.xml"
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>
<!-- [rfced] References:
a) FYI - We updated the date for the [Moa] reference from "2022" to "6 October 2
025"
to match the most recent date provided at the URL.
Please let us know if you would like to point to a version from 2022. The page
history for this page is available here:
https://wiki.federationer.internetstiftelsen.se/pages/viewpreviousversions.actio
n?pageId=20545581
Original:
[Moa] The Swedish Internet Foundation, "Machine and Organization
Authentication", 2022,
<https://wiki.federationer.internetstiftelsen.se/x/
LYA5AQ>.
Current:
[Moa] Internetstiftelsens Federationer [The Swedish Internet
Foundation], "Machine and Organization Authentication", 6
October 2025,
<https://wiki.federationer.internetstiftelsen.se/x/
LYA5AQ>.
b) FYI - We updated the date for the [SkolverketMATF] reference from "2023" to
"4 September 2025" to match the most recent commit made to this README
file. We have also added the commit hash to this reference.
Please let us know if you would prefer to point to a commit from
2023. A list of commits for this README is available here:
https://github.com/skolverket/dnp-usermanagement/commits/main/authentication-api
/README.md
Original:
[SkolverketMATF]
Swedish National Agency for Education, "Authentication API
for User Management", 2023,
<https://github.com/skolverket/dnp-
usermanagement/blob/main/authentication-api/README.md>.
Current:
[SkolverketMATF]
Skolverket [Swedish National Agency for Education], "API
för autentisering" [Authentication API for User
Management], commit f8c2e93, 4 September 2023,
<https://github.com/skolverket/dnp-
usermanagement/blob/main/authentication-api/README.md>.
-->
<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="2023"></date>
</front> </front>
<refcontent>commit f8c2e93</refcontent>
</reference> </reference>
<reference anchor="eIDAS" target="https://eidas.ec.europa.eu/"> <reference anchor="eIDAS" target="https://eidas.ec.europa.eu/">
<front> <front>
<title>eIDAS: electronic Identification, Authentication and trust Services</ title> <title>eIDAS: electronic Identification, Authentication and trust Services</ title>
<author> <author>
<organization>European Commission</organization> <organization>European Commission</organization>
</author> </author>
<date year="2014"></date>
</front> </front>
</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 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> </section>
</back> </back>
<!-- [rfced] Please review whether any of the notes in this document
should be in the <aside> element. It is defined as "a container for
content that is semantically less important or tangential to the
content that surrounds it" (https://authors.ietf.org/en/rfcxml-vocabulary#aside)
.
-->
<!-- [rfced] Abbreviations and Terminology:
a) For brevity and for a closer 1:1 relationship between abbreviation and
expansion, may we adjust the expansion of MATF throughout this document as
follows?
Original:
Mutually Authenticating TLS in the context of Federations (MATF)
Perhaps:
Mutually Authenticating TLS in Federations (MATF)
b) Per Section 3.6 of RFC 7322 ("RFC Style Guide"), abbreviations should be
expanded upon first use. FO appears twice in the paragraph below, and is not us
ed elsewhere. Perhaps this should be replaced with "federation operator"? Othe
rwise, please let us know how may we expand "FO".
The community plays a crucial role in this type of federation.
Members are active participants, and the FO ensures the federation
runs smoothly and serves their needs. Moa's success highlights the
importance of collaboration, with members and the FO working together
to maintain trust, security, and interoperability in the education
sector.
c) To define "RESTful", may we adjust the text below as follows?
Original:
MATF is designed specifically for secure authentication in machine-
to-machine contexts, such as RESTful APIs and service-to-service
interactions, and is not intended for browser-based authentication.
Perhaps:
MATF is designed specifically for secure authentication in machine-
to-machine contexts, such as RESTful APIs (where "RESTful" refers to the
Representational State Transfer (REST) architecture) and service-to-service
interactions, and is not intended for browser-based authentication.
d) FYI - We have updated the following abbreviation to the form on the right to
match its usage in RFC 7517.
JSON Web Key Set (JWKS) -> JSON Web Key (JWK) Set
JWKS -> JWK Set
e) FYI - We have added expansions for abbreviations upon first
use per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each
expansion in the document carefully to ensure correctness.
Security Assertion Markup Language (SAML)
JSON Web Signature (JWS)
Certificate Authorities (CAs)
System for Cross-domain Identity Management (SCIM)
-->
<!-- [rfced] Please review the "Inclusive Language" portion of the online
Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
and let us know if any changes are needed. Updates of this nature typically
result in more precise language, which is helpful for readers.
For example, please consider whether the following terms should be updated in
the instances below:
a) "man-in-the-middle (perhaps "on-path attacks"):
* Public key pinning [RFC7469] and preloading to thwart man-in-the-
middle attacks by ensuring validated certificates.
b) "native" (perhaps "built in")
Implementations SHOULD, when possible, rely on libraries with native
support for pinning.
c) In addition, please consider whether "tradition" should be updated for clarit
y. While the NIST website
<https://web.archive.org/web/20250214092458/https://www.nist.gov/nist-research-l
ibrary/nist-technical-series-publications-author-instructions#table1>
indicates that this term is potentially biased, it is also ambiguous.
"Tradition" is a subjective term, as it is not the same for everyone.
This approach eliminates reliance on traditional certificate revocation
mechanisms and shifts the trust relationship to the specific, updated public
key identified by its pin.
-->
</rfc> </rfc>
 End of changes. 145 change blocks. 
556 lines changed or deleted 806 lines changed or added

This html diff was produced by rfcdiff 1.48.