idnits 2.17.1 draft-halen-fed-tls-auth-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (12 October 2021) is 898 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schlyter 3 Internet-Draft Kirei AB 4 Intended status: Informational S. Halen 5 Expires: 15 April 2022 The Swedish Internet Foundation 6 12 October 2021 8 Federated TLS Authentication 9 draft-halen-fed-tls-auth-02 11 Abstract 13 This document describes how to establish a secure end-to-end channel 14 between two parties within a federation, where both client and server 15 are mutually authenticated. The trust relationship is based upon a 16 trust anchor held and published by the federation. A federation is a 17 trusted third party that inter-connect different trust domains with a 18 common set of policies and standards. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 15 April 2022. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Reserved Words . . . . . . . . . . . . . . . . . . . . . 3 52 2. Federation Chain of Trust . . . . . . . . . . . . . . . . . . 3 53 3. Authentication . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Federation Metadata . . . . . . . . . . . . . . . . . . . . . 4 55 4.1. Federation Metadata claims . . . . . . . . . . . . . . . 4 56 4.1.1. Entities . . . . . . . . . . . . . . . . . . . . . . 5 57 4.2. Metadata Schema . . . . . . . . . . . . . . . . . . . . . 6 58 4.3. Metadata Signing . . . . . . . . . . . . . . . . . . . . 6 59 4.4. Metadata Example . . . . . . . . . . . . . . . . . . . . 7 60 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 8 61 5.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 5.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 5.3. SPKI Generation . . . . . . . . . . . . . . . . . . . . . 10 64 5.4. Curl and Public Key Pinning . . . . . . . . . . . . . . . 10 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 6.1. TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 6.2. Federation Metadata Updates . . . . . . . . . . . . . . . 11 68 6.3. Federation Metadata Signing Key . . . . . . . . . . . . . 11 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 70 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 71 9. Normative References . . . . . . . . . . . . . . . . . . . . 12 72 10. Informative References . . . . . . . . . . . . . . . . . . . 12 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 75 1. Introduction 77 This document describes how to establish a secure end-to-end channel 78 between two parties within a federation, where both client and server 79 are mutually authenticated (TLS [RFC8446]). The trust relationship 80 is based upon a trust anchor held and published by the federation. A 81 federation is a trusted third party that inter-connect different 82 trust domains with a common set of policies and standards. The 83 federation aggregates and publishes information ("federation 84 metadata") about all the federated entities including certificate 85 issuers and public key information. When the term "federation 86 metadata" is used in this document, it always refer to the aggregated 87 information published by a federation in the sense of this document. 89 The federation provides a common framework for providing endpoint 90 information. When two parties establish a connection, the 91 information of the other endpoint is retrieved from the metadata. 92 The parties leverage this every time they commence a transaction with 93 a new entity in the federation. 95 Mutual TLS authentication involves provisioning of key material. 96 This key exchange is performed through the publication of the 97 federation metadata by the federation and the use of that federation 98 metadata by its members. Without a federation, the server side is 99 often required to create a public key infrastructure (PKI) in order 100 to distribute client certificates.The Swedish education sector uses 101 federated TLS authentication to secure endpoints used for user 102 lifecycle management. That Federation is a collaboration between 103 school authorities and service providers. If the certificate 104 distribution would be handled without a federated framework, it would 105 mean a higher administrative burden and a higher risk of compromised 106 security. 108 1.1. Reserved Words 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 112 document are to be interpreted as described in [RFC2119]. 114 2. Federation Chain of Trust 116 The members of a federation submit their issuer certificates and 117 other requested data (in this document called "member metadata") to 118 the federation. Both the authenticity of the submitted member 119 metadata and the submitting member MUST be assured by the federation. 120 How this is achieved is out of scope for this document. The 121 federation operator aggregates, signs and publishes the federation 122 metadata, i.e., an aggregation of all members' member metadata and 123 some additional information added by the federation. By trusting the 124 federation and its certificate, federation members trust the 125 federation metadata content. 127 The root of the chain of trust is the federation metadata signature 128 and the trust anchor is the federation's signing certificate. That 129 certificate needs to be securely distributed, there MUST be an out- 130 of-band function to verify the certificate. The distribution of the 131 federation's certificate is out-of-scope of this document. 133 3. Authentication 135 All TLS sessions between clients and servers are authenticated via 136 mutual TLS authentication. Trust is limited to the set of public key 137 pins published for each endpoint in the federation metadata. Public 138 key pinning associates a public key with an endpoint to reduce the 139 risk of attacks with rogue certificates. 141 Upon connection, the endpoints (client and server) MUST validate the 142 other endpoint's certificate against the published matching public 143 key pin. Issuers in metadata are only used to help validate the 144 server and client certificate. It is up to each implementation to 145 decide if these are needed. Failure to validate triggers termination 146 of the connection. 148 If a TLS session is terminated separately from the application (e.g., 149 when using a reverse proxy), the TLS session termination point can 150 validate the certificate issuer and defer public key pin matching to 151 the application given that the peer certificate is transferred to the 152 application (e.g., via a HTTP header). 154 4. Federation Metadata 156 Federation metadata is published as an JWS [RFC7515]. Entities have 157 an organization claim that is used for identification. Server 158 endpoints include a base URI to connect to the endpoint. Servers and 159 clients also have a list of public key pins used to limit valid 160 endpoint certificates. 162 Public key pinning is defined in [RFC7469]. Clients and servers 163 preloads pins as defined in [RFC7469], section 2.7 165 4.1. Federation Metadata claims 167 This section defines the set of claims that can be included in 168 metadata. 170 * version (REQUIRED) 172 Schema version follows semantic versioning (https://semver.org 173 (https://semver.org)) 175 * cache_ttl (OPTIONAL) 177 How long (in seconds) to cache metadata. Effective maximum TTL is 178 the minimum of HTTP Expire and TTL 180 * Entities (REQUIRED) 182 List of entities (see Section 4.1.1) 184 4.1.1. Entities 186 Metadata contains a list of entities that may be used for 187 communication within the federation. Each entity describes one or 188 more endpoints owned by a member. An entity has the following 189 properties: 191 * entity_id (REQUIRED) 193 URI that identifies the entity. It MUST be globally unique. 195 Example: "https://example.com" (https://example.com") 197 * organization (OPTIONAL) 199 A name identifying the organization that the entity's metadata 200 represents. 202 Example: "Example Org". 204 * issuers (REQUIRED) 206 A list of certificate issuers that are allowed to issue 207 certificates for the entity's endpoints. For each issuer, the 208 issuer's root CA certificate is included in the x509certificate 209 property (PEM-encoded). 211 * servers (OPTIONAL) 213 List of the entity's servers (see Section 4.1.1.1). 215 * clients (OPTIONAL) 217 List of the entity's clients (see Section 4.1.1.1). 219 4.1.1.1. Servers / Clients 221 A list of the entity's servers and clients. 223 * description (OPTIONAL) 225 A human readable text describing the server. 227 Example: "SCIM Server 1" 229 * base_uri (OPTIONAL) 230 The base URL of the server (hence required for endpoints 231 describing servers). 233 Example: "https://scim.example.com/" (https://scim.example.com/") 235 * pins (REQUIRED) 237 A list of Public Key Pins [RFC7469]. Each pin has the following 238 properties: 240 - alg (REQUIRED) 242 The name of the cryptographic hash algorithm. The only allowed 243 value is "sha256". 245 Example: "sha256" 247 - digest (REQUIRED) 249 End-entity certificate base64 encoded Subject Public Key 250 Information (SPKI) fingerprint [RFC7469], for client the digest 251 MUST be globally unique. MAY, locally in the same entity_id 252 object, be assigned to multiple clients. 254 Example: "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" 256 * tags (OPTIONAL) 258 A list of strings that describe the endpoint's capabilities. 260 Pattern: ^[a-z0-9]{1,64}$ 262 Example: ["scim", "xyzzy"] 264 4.2. Metadata Schema 266 The federation metadata JSON schema (in YAML format) can be found at 267 https://github.com/dotse/tls-fed-auth (https://github.com/dotse/tls- 268 fed-auth/blob/master/tls-fed-metadata.yaml). 270 4.3. Metadata Signing 272 The federation metadata is signed with JWS and published using JWS 273 JSON Serialization. It is RECOMMENDED that federation metadata 274 signatures are created with algorithm _ECDSA using P-256 and SHA-256_ 275 ("ES256") as defined in [RFC7518]. 277 The following federation metadata signature protected headers are 278 REQUIRED: 280 * alg (Algorithm) 282 Identifies the algorithm used to generate the JWS signature 283 [RFC7515], section 4.1.1. 285 * iat (Issued At) 287 Identifies the time on which the signature was issued. Its value 288 MUST be a number containing a NumericDate value. 290 * exp (Expiration Time) 292 Identifies the expiration time on and after which the signature 293 and federation metadata are no longer valid. The expiration time 294 of the federation metadata MUST be set to the value of exp. Its 295 value MUST be a number containing a NumericDate value. 297 * iss (Issuer) 299 URI that identifies the publisher of federation metadata. The 300 issuer claim MUST be used to prevent conflicts of entities of the 301 same name from different federations. 303 * kid (Key Identifier) 305 The key ID is used to identify the signing key in the key set used 306 to sign the JWS. 308 4.4. Metadata Example 310 The following is a non-normative example of a federation metadata 311 statement. Line breaks within the issuers' claim is for readability 312 only. 314 { 315 "version": "1.0.0", 316 "cache_ttl": 3600, 317 "entities": [{ 318 "entity_id": "https://example.com", 319 "organization": "Example Org", 320 "issuers": [{ 321 "x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDDCCAf 322 SgAwIBAgIJAIOsfJBStJQhMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAM 323 MEHNjaW0uZXhhbXBsZS5jb20wHhcNMTcwNDA2MDc1MzE3WhcNMTcwNTA2MD 324 c1\nMzE3WjAbMRkwFwYDVQQDDBBzY2ltLmV4YW1wbGUuY29tMIIBIjANBgk 325 qhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAyr+3dXTC8YXoi0LDJTH0lTfv 326 8omQivWFOr3+/PBE\n6hmpLSNXK/EZJBD6ZT4Q+tY8dPhyhzT5RFZCVlrDs 327 e/kY00F4yoflKiqx9WSuCrq\nZFr1AUtIfGR/LvRUvDFtuHo1MzFttiK8Wr 328 wskMYZrw1zLHTIVwBkfMw1qr2XzxFK\njt0CcDmFxNdY5Q8kuBojH9+xt5s 329 ZbrJ9AVH/OI8JamSqDjk9ODyGg+GrEZFClP/B\nxa4Fsl04En/9GfaJnCU1 330 NpU0cqvWbVUlLOy8DaQMN14HIdkTdmegEsg2LR/XrJkt\nho16diAXrgS25 331 3xbkdD3T5d6lHiZCL6UxkBh4ZHRcoftSwIDAQABo1MwUTAdBgNV\nHQ4EFg 332 QUs1dXuhGhGc2UNb7ikn3t6cBuU34wHwYDVR0jBBgwFoAUs1dXuhGhGc2U\ 333 nNb7ikn3t6cBuU34wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAA 334 OCAQEA\nrR9wxPhUa2XfQ0agAC0oC8TFf8wbTYb0ElP5Ej834xMMW/wWTSA 335 N8/3WqOWNQJ23\nf0vEeYQwfvbD2fjLvYTyM2tSPOWrtQpKuvulIrxV7Zz8 336 A61NIjblE3rfea1eC8my\nTkDOlMKV+wlXXgUxirride+6ubOWRGf92fgze 337 DGJWkmm/a9tj0L/3e0xIXeujxC7\nMIt3p99teHjvnZQ7FiIBlvGc1o8FD1 338 FKmFYd74s7RxrAusBEAAmBo3xyB89cFU0d\nKB2fkH2lkqiqkyOtjrlHPoy 339 6ws6g1S6U/Jx9n0NEeEqCfzXnh9jEpxisSO+fBZER\npCwj2LMNPQxZBqBF 340 oxbFPw==\n-----END CERTIFICATE-----" 341 }], 342 "servers": [{ 343 "description": "SCIM Server 1", 344 "base_uri": "https://scim.example.com/", 345 "pins": [{ 346 "alg": "sha256", 347 "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" 348 }], 349 "tags": [ 350 "scim" 351 ] 352 }], 353 "clients": [{ 354 "description": "SCIM Client 1", 355 "pins": [{ 356 "alg": "sha256", 357 "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ=" 358 }] 359 }] 360 }] 361 } 363 5. Usage Examples 365 The examples in this section are non-normative. 367 The example below is from the federation called "Skolfederation" 368 where federated TLS authentication is already in use. Clients and 369 servers are registered in the federation. The clients intend to 370 manage cross-domain user accounts within the service. The standard 371 used for account management is SS 12000:2018 (i.e., a SCIM 372 extension). 374 +---------------------------------------------+ 375 | | 376 | Federation Metadata | 377 | | 378 +---+--------------------------+--------------+ 379 | | 380 (A) (A) 381 | | 382 v v 383 +---+----+ +------------+--------------+ 384 |Local MD| | Local MD | 385 +---+----+ +----+------------- ---+----+ 386 | | | 387 (B) (C) (F) 388 | | | 389 v v v 390 +---+----+ +----+---+ +----+---+ 391 | | | | | | 392 | Client | | Reverse| | App | 393 | +--(D)-->+ Proxy +--(E)-->+ | 394 | | | | | | 395 | | | | | | 396 +--------+ +--------+ +--------+ 398 A. Entities collect member metadata from the federation metadata. 400 B. The client pins the server's public key pins. 402 C. The reverse proxy trust anchor is setup with the clients' 403 certificate issuers. 405 D. The client establishes a connection with the server using the 406 base_uri from the federation metadata. 408 E. The reverse proxy forwards the client certificate to the 409 application. 411 F. The application converts the certificate to a public key pin and 412 checks the federation metadata for a matching pin. The entity's 413 entity_id should be used as an identifier. 415 5.1. Client 417 A certificate is issued for the client and the issuer is published in 418 the federation metadata together with the client's certificate public 419 key pins 420 When the client wants to connect to a remote server (identified by an 421 entity identifier) the following steps need to be taken: 423 1. Find possible server candidates by filtering the remote entity's 424 list of servers based on tags. 426 2. Connect to the server URI. Include the entity's list of 427 certificate issuers in the TLS clients list of trusted CAs, or 428 trust the listed pins explicitly. 430 3. If pinning was not used, validate the received server certificate 431 using the entity's published pins. 433 4. Commence transactions 435 5.2. Server 437 A certificate is issued for the server and the issuer is published in 438 the federation metadata together with the server's name and 439 certificate public key pin. 441 When the server receives a connection from a remote client, the 442 following steps need to be taken: 444 1. Populate list of trusted CAs using all known entities' published 445 issuers and required TLS client certificate authentication, or 446 configure optional untrusted TLS client certificate 447 authentication (e.g., optional_no_ca). 449 2. Once a connection has been accepted, validate the received client 450 certificate using the client's published pins. 452 3. Commence transactions. 454 5.3. SPKI Generation 456 Example of how to use OpenSSL to generate a SPKI fingerprint from a 457 PEM-encoded certificate. 459 openssl x509 -in -pubkey -noout | \ 460 openssl pkey -pubin -outform der | \ 461 openssl dgst -sha256 -binary | \ 462 openssl enc -base64 464 5.4. Curl and Public Key Pinning 466 Example of public key pinning with curl. Line breaks are for 467 readability only. 469 curl --cert client.pem --client.key --pinnedpubkey 'sha256//0Ok2aNf 470 crCNDMhC2uXIdxBFOvMfEVtzlNVUT5pur0Dk=' https://host.example.com 472 6. Security Considerations 474 6.1. TLS 476 Security considerations for TLS 1.3 [RFC8446] are described in 477 Section 10 and Appendices C, D and E of RFC 8446. 479 6.2. Federation Metadata Updates 481 Frequent check of the federation metadata aggregate to use the most 482 recent version is required. It is required to check the federation 483 metadata periodically to find out if entities, pins and issuers are 484 still active. 486 6.3. Federation Metadata Signing Key 488 To ensure the validity of the federation metadata the refresh process 489 must verify the signature on each and every federation metadata 490 fetch. The federation's public key authenticity must be assured and 491 verified in a secure way. 493 7. IANA Considerations 495 This document has no IANA actions. 497 8. Acknowledgements 499 This project was funded through the NGI0 PET Fund, a fund established 500 by NLnet with financial support from the European Commission's Next 501 Generation Internet programme, under the aegis of DG Communications 502 Networks, Content and Technology under grant agreement No 825310. 504 The authors would like to thank the following people for the detailed 505 review and suggestions: 507 * Rasmus Larsson 509 * Mats Dufberg 511 * Joe Siltberg 513 * Stefan Norberg 515 * Petter Blomberg 516 The authors would also like to thank participants in the EGIL working 517 group for their comments on this specification. 519 9. Normative References 521 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 522 Requirement Levels", BCP 14, RFC 2119, 523 DOI 10.17487/RFC2119, March 1997, 524 . 526 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 527 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 528 2015, . 530 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 531 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 532 2015, . 534 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 535 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 536 . 538 10. Informative References 540 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 541 DOI 10.17487/RFC7518, May 2015, 542 . 544 Authors' Addresses 546 Jakob Schlyter 547 Kirei AB 549 Email: jakob@kirei.se 551 Stefan Halen 552 The Swedish Internet Foundation 554 Email: stefan.halen@internetstiftelsen.se