Network Working Group J. Schlyter Internet-Draft Kirei AB Intended status: Informational S. Halen Expires: 24 July 2023 The Swedish Internet Foundation 20 January 2023 Federated TLS Authentication draft-halen-fed-tls-auth-05 Abstract This document describes how to establish a secure end-to-end channel between two parties within a federation, where both client and server are mutually authenticated. The trust relationship is based upon a trust anchor held and published by the federation. A federation is a trusted third party that inter-connect different trust domains with a common set of policies and standards. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 24 July 2023. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Schlyter & Halen Expires 24 July 2023 [Page 1] Internet-Draft Federated TLS AuthN January 2023 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Reserved Words . . . . . . . . . . . . . . . . . . . . . 3 2. Federation Chain of Trust . . . . . . . . . . . . . . . . . . 3 3. Authentication . . . . . . . . . . . . . . . . . . . . . . . 3 4. Federation Metadata . . . . . . . . . . . . . . . . . . . . . 4 4.1. Federation Metadata claims . . . . . . . . . . . . . . . 4 4.1.1. Entities . . . . . . . . . . . . . . . . . . . . . . 5 4.2. Metadata Schema . . . . . . . . . . . . . . . . . . . . . 6 4.3. Metadata Signing . . . . . . . . . . . . . . . . . . . . 7 4.4. Metadata Example . . . . . . . . . . . . . . . . . . . . 7 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 9 5.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.3. SPKI Generation . . . . . . . . . . . . . . . . . . . . . 10 5.4. Curl and Public Key Pinning . . . . . . . . . . . . . . . 11 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6.1. TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6.2. Federation Metadata Updates . . . . . . . . . . . . . . . 11 6.3. Federation Metadata Signing Key . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 9. Normative References . . . . . . . . . . . . . . . . . . . . 12 10. Informative References . . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction This document describes how to establish a secure end-to-end channel between two parties within a federation, where both client and server are mutually authenticated (TLS [RFC8446]). The trust relationship is based upon a trust anchor held and published by the federation. A federation is a trusted third party that inter-connect different trust domains with a common set of policies and standards. The federation aggregates and publishes information (“federation metadata”) about all the federated entities including certificate issuers and public key information. When the term “federation metadata” is used in this document, it always refer to the aggregated information published by a federation in the sense of this document. The federation provides a common framework for providing endpoint information. When two parties establish a connection, the information of the other endpoint is retrieved from the metadata. The parties leverage this every time they commence a transaction with a new entity in the federation. Schlyter & Halen Expires 24 July 2023 [Page 2] Internet-Draft Federated TLS AuthN January 2023 Mutual TLS authentication involves provisioning of key material. This key exchange is performed through the publication of the federation metadata by the federation and the use of that federation metadata by its members. Without a federation, the server side is often required to create a public key infrastructure (PKI) in order to distribute client certificates.The Swedish education sector uses federated TLS authentication to secure endpoints used for user lifecycle management . That Federation is a collaboration between school authorities and service providers. If the certificate distribution would be handled without a federated framework, it would mean a higher administrative burden and a higher risk of compromised security. 1.1. Reserved Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Federation Chain of Trust The members of a federation submit their issuer certificates and other requested data (in this document called “member metadata”) to the federation. Both the authenticity of the submitted member metadata and the submitting member MUST be assured by the federation. How this is achieved is out of scope for this document. The federation operator aggregates, signs and publishes the federation metadata, i.e., an aggregation of all members’ member metadata and some additional information added by the federation. By trusting the federation and its certificate, federation members trust the federation metadata content. The root of the chain of trust is the federation metadata signature and the trust anchor is the federation's signing certificate. That certificate needs to be securely distributed, there MUST be an out- of-band function to verify the certificate. The distribution and verification of the federation's certificate is out-of-scope of this document. 3. Authentication All TLS sessions between clients and servers are authenticated via mutual TLS authentication. Trust is limited to the set of public key pins published for each endpoint in the federation metadata. Public key pinning associates a public key with an endpoint to reduce the risk of attacks with rogue certificates. Public key pinning is defined in [RFC7469]. Pins are collected from federation metadata. It is up to the federation to establish a discovery process for Schlyter & Halen Expires 24 July 2023 [Page 3] Internet-Draft Federated TLS AuthN January 2023 finding relevant pins. There are metadata claims to aid the discovery process (e.g., organization, tags, description). Clients and servers preload the selected pins as defined in [RFC7469], section 2.7, before establishing a connection. Upon connection, the endpoints (client and server) MUST either use pinning or validate the received certificate using the entity's published pins. Issuers in metadata MAY be used to verify certificate issuers. It is up to each implementation to decide if these are needed. If a TLS session is terminated separately from the application (e.g., when using a reverse proxy). The termination point can either use optional untrusted TLS client certificate authentication or validate the certificate issuer. Pin validation MAY then be deferred to the application, given that the peer certificate is transferred to the application (e.g., via an HTTP header). Failure to validate a received certificate triggers termination of the connection. 4. Federation Metadata Federation metadata is published as an JWS [RFC7519]. The payload contains statements about federation members entities. Metadata is used for authentication and service discovery. A client select a server based on metadata claims (e.g., organization, tags). The client then use the selected server claims base_uri, pins and if needed issuers to establish a connection. Upon receiving a connection, a server validates the received client certificate using the client's published pins. Server MAY also check other claims such as organization and tags to determine if the connections is accepted or terminated. 4.1. Federation Metadata claims This section defines the set of claims that can be included in metadata. * version (REQUIRED) Schema version follows semantic versioning (https://semver.org (https://semver.org)) * cache_ttl (OPTIONAL) Schlyter & Halen Expires 24 July 2023 [Page 4] Internet-Draft Federated TLS AuthN January 2023 How long (in seconds) to cache metadata. Effective maximum TTL is the minimum of HTTP Expire and TTL * Entities (REQUIRED) List of entities (see Section 4.1.1) 4.1.1. Entities Metadata contains a list of entities that may be used for communication within the federation. Each entity describes one or more endpoints owned by a member. An entity has the following properties: * entity_id (REQUIRED) URI that identifies the entity. It MUST be globally unique. Example: "https://example.com" (https://example.com") * organization (OPTIONAL) A name identifying the organization that the entity's metadata represents. Example: “Example Org”. * issuers (REQUIRED) A list of certificate issuers that are allowed to issue certificates for the entity's endpoints. For each issuer, the issuer's root CA certificate is included in the x509certificate property (PEM-encoded). * servers (OPTIONAL) List of the entity's servers (see Section 4.1.1.1). * clients (OPTIONAL) List of the entity's clients (see Section 4.1.1.1). 4.1.1.1. Servers / Clients A list of the entity's servers and clients. * description (OPTIONAL) Schlyter & Halen Expires 24 July 2023 [Page 5] Internet-Draft Federated TLS AuthN January 2023 A human readable text describing the server. Example: "SCIM Server 1" * base_uri (OPTIONAL) The base URL of the server (hence required for endpoints describing servers). Example: "https://scim.example.com/" (https://scim.example.com/") * pins (REQUIRED) A list of Public Key Pins [RFC7469]. Each pin has the following properties: - alg (REQUIRED) The name of the cryptographic hash algorithm. The only allowed value is "sha256". Example: "sha256" - digest (REQUIRED) End-entity certificate base64 encoded Subject Public Key Information (SPKI) fingerprint [RFC7469], for client the digest MUST be globally unique. MAY, locally in the same entity_id object, be assigned to multiple clients. Example: "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" * tags (OPTIONAL) A list of strings that describe the endpoint's capabilities. Pattern: ^[a-z0-9]{1,64}$ Example: ["scim", "xyzzy"] 4.2. Metadata Schema The federation metadata JSON schema (in YAML format) can be found at https://github.com/dotse/tls-fed-auth (https://github.com/dotse/tls- fed-auth/blob/master/tls-fed-metadata.yaml). Schlyter & Halen Expires 24 July 2023 [Page 6] Internet-Draft Federated TLS AuthN January 2023 4.3. Metadata Signing The federation metadata is signed with JWS and published using JWS JSON Serialization. It is RECOMMENDED that federation metadata signatures are created with algorithm _ECDSA using P-256 and SHA-256_ ("ES256") as defined in [RFC7518]. The following federation metadata signature protected headers are REQUIRED: * alg (Algorithm) Identifies the algorithm used to generate the JWS signature [RFC7515], section 4.1.1. * iat (Issued At) Identifies the time on which the signature was issued. Its value MUST be a number containing a NumericDate value. * exp (Expiration Time) Identifies the expiration time on and after which the signature and federation metadata are no longer valid. The expiration time of the federation metadata MUST be set to the value of exp. Its value MUST be a number containing a NumericDate value. * iss (Issuer) URI that identifies the publisher of federation metadata. The issuer claim MUST be used to prevent conflicts of entities of the same name from different federations. * kid (Key Identifier) The key ID is used to identify the signing key in the key set used to sign the JWS. 4.4. Metadata Example The following is a non-normative example of a federation metadata statement. Line breaks within the issuers' claim is for readability only. Schlyter & Halen Expires 24 July 2023 [Page 7] Internet-Draft Federated TLS AuthN January 2023 { "version": "1.0.0", "cache_ttl": 3600, "entities": [{ "entity_id": "https://example.com", "organization": "Example Org", "issuers": [{ "x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDDCCAf SgAwIBAgIJAIOsfJBStJQhMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAM MEHNjaW0uZXhhbXBsZS5jb20wHhcNMTcwNDA2MDc1MzE3WhcNMTcwNTA2MD c1\nMzE3WjAbMRkwFwYDVQQDDBBzY2ltLmV4YW1wbGUuY29tMIIBIjANBgk qhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAyr+3dXTC8YXoi0LDJTH0lTfv 8omQivWFOr3+/PBE\n6hmpLSNXK/EZJBD6ZT4Q+tY8dPhyhzT5RFZCVlrDs e/kY00F4yoflKiqx9WSuCrq\nZFr1AUtIfGR/LvRUvDFtuHo1MzFttiK8Wr wskMYZrw1zLHTIVwBkfMw1qr2XzxFK\njt0CcDmFxNdY5Q8kuBojH9+xt5s ZbrJ9AVH/OI8JamSqDjk9ODyGg+GrEZFClP/B\nxa4Fsl04En/9GfaJnCU1 NpU0cqvWbVUlLOy8DaQMN14HIdkTdmegEsg2LR/XrJkt\nho16diAXrgS25 3xbkdD3T5d6lHiZCL6UxkBh4ZHRcoftSwIDAQABo1MwUTAdBgNV\nHQ4EFg QUs1dXuhGhGc2UNb7ikn3t6cBuU34wHwYDVR0jBBgwFoAUs1dXuhGhGc2U\ nNb7ikn3t6cBuU34wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAA OCAQEA\nrR9wxPhUa2XfQ0agAC0oC8TFf8wbTYb0ElP5Ej834xMMW/wWTSA N8/3WqOWNQJ23\nf0vEeYQwfvbD2fjLvYTyM2tSPOWrtQpKuvulIrxV7Zz8 A61NIjblE3rfea1eC8my\nTkDOlMKV+wlXXgUxirride+6ubOWRGf92fgze DGJWkmm/a9tj0L/3e0xIXeujxC7\nMIt3p99teHjvnZQ7FiIBlvGc1o8FD1 FKmFYd74s7RxrAusBEAAmBo3xyB89cFU0d\nKB2fkH2lkqiqkyOtjrlHPoy 6ws6g1S6U/Jx9n0NEeEqCfzXnh9jEpxisSO+fBZER\npCwj2LMNPQxZBqBF oxbFPw==\n-----END CERTIFICATE-----" }], "servers": [{ "description": "SCIM Server 1", "base_uri": "https://scim.example.com/", "pins": [{ "alg": "sha256", "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" }], "tags": [ "scim" ] }], "clients": [{ "description": "SCIM Client 1", "pins": [{ "alg": "sha256", "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" }] }] }] } Schlyter & Halen Expires 24 July 2023 [Page 8] Internet-Draft Federated TLS AuthN January 2023 5. Usage Examples The examples in this section are non-normative. The example below is from the federation called "Skolfederation" where federated TLS authentication is already in use. Clients and servers are registered in the federation. The clients intend to manage cross-domain user accounts within the service. The standard used for account management is SS 12000:2018 (i.e., a SCIM extension). +---------------------------------------------+ | | | Federation Metadata | | | +---+--------------------------+--------------+ | | (A) (A) | | v v +---+----+ +------------+--------------+ |Local MD| | Local MD | +---+----+ +----+------------- ---+----+ | | | (B) (C) (F) | | | v v v +---+----+ +----+---+ +----+---+ | | | | | | | Client | | Reverse| | App | | +--(D)-->+ Proxy +--(E)-->+ | | | | | | | | | | | | | +--------+ +--------+ +--------+ A. Entities collect member metadata from the federation metadata. B. The client pins the server's public key pins. C. The reverse proxy trust anchor is setup with the clients' certificate issuers. D. The client establishes a connection with the server using the base_uri from the federation metadata. E. The reverse proxy forwards the client certificate to the application. Schlyter & Halen Expires 24 July 2023 [Page 9] Internet-Draft Federated TLS AuthN January 2023 F. 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. 5.1. Client A certificate is issued for the client and the issuer is published in the federation metadata together with the client's certificate public key pins When the client wants to connect to a remote server (identified by an entity identifier) the following steps need to be taken: 1. Find possible server candidates by filtering the remote entity's list of servers based on tags. 2. 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. 3. If pinning was not used, validate the received server certificate using the entity's published pins. 4. Commence transactions 5.2. Server A certificate is issued for the server and the issuer is published in the federation metadata together with the server's name and certificate public key pin. When the server receives a connection from a remote client, the following steps need to be taken: 1. 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). 2. Once a connection has been accepted, validate the received client certificate using the client's published pins. 3. Commence transactions. 5.3. SPKI Generation Example of how to use OpenSSL to generate a SPKI fingerprint from a PEM-encoded certificate. Schlyter & Halen Expires 24 July 2023 [Page 10] Internet-Draft Federated TLS AuthN January 2023 openssl x509 -in -pubkey -noout | \ openssl pkey -pubin -outform der | \ openssl dgst -sha256 -binary | \ openssl enc -base64 5.4. Curl and Public Key Pinning Example of public key pinning with curl. Line breaks are for readability only. curl --cert client.pem --client.key --pinnedpubkey 'sha256//0Ok2aNf crCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' https://host.example.com 6. Security Considerations 6.1. TLS Security considerations for TLS 1.3 [RFC8446] are described in Section 10 and Appendices C, D and E of RFC 8446. 6.2. Federation Metadata Updates Frequent check of the federation metadata aggregate to use the most recent version is required. It is required to check the federation metadata periodically to find out if entities, pins and issuers are still active. 6.3. Federation Metadata Signing Key To ensure the validity of the federation metadata the refresh process must verify the signature on each and every federation metadata fetch. The federation's public key authenticity must be assured and verified in a secure way. 7. IANA Considerations This document has no IANA actions. 8. Acknowledgements This project was funded through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission’s Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310. The authors would like to thank the following people for the detailed review and suggestions: Schlyter & Halen Expires 24 July 2023 [Page 11] Internet-Draft Federated TLS AuthN January 2023 * Rasmus Larsson * Mats Dufberg * Joe Siltberg * Stefan Norberg * Petter Blomberg The authors would also like to thank participants in the EGIL working group for their comments on this specification. 9. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 2015, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . 10. Informative References [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, . Authors' Addresses Jakob Schlyter Kirei AB Email: jakob@kirei.se Schlyter & Halen Expires 24 July 2023 [Page 12] Internet-Draft Federated TLS AuthN January 2023 Stefan Halen The Swedish Internet Foundation Email: stefan.halen@internetstiftelsen.se Schlyter & Halen Expires 24 July 2023 [Page 13]