# drafts

name: draft-steckbeck-ua-conn-sec
rev: 00
title: User Agent Connection Security
time: 2025-08-17T09:07:18Z
group_uri: /api/v1/group/group/1027/
expires: 2023-09-13T21:29:23Z
states: ["/api/v1/doc/state/2/", "/api/v1/doc/state/150/", "/api/v1/doc/state/75/"]
categories: ["Policy/governance", "Other AI/agent"]
tags: []
fetched_at: 2026-02-27T22:56:05.127580+00:00
abstract:
The user agent to server transaction has many attack surfaces which
   have been defended by various recommendations such as Content
   Security Policy. An attack vector that is currently exploited is the
   open connection policy to first, second- and third-party resources.
   A breach of the origin website or other connected resource could
   require the client to load resources from a malicious network. This
   document provides a framework which allows authors to publish
   authorized connectable second- and third-party resources that a user
   agent should or must follow depending on configuration of that user
   agent.

full_text:
﻿

Network Working Group                                       D. Steckbeck
Internet-Draft                                                      
Intended Status: Standards Track
Category: Experimental                                        March 2023



                    User Agent Connection Security
                  draft-steckbeck-ua-conn-sec-00.txt

Abstract

   The user agent to server transaction has many attack surfaces which
   have been defended by various recommendations such as Content 
   Security Policy. An attack vector that is currently exploited is the 
   open connection policy to first, second- and third-party resources.
   A breach of the origin website or other connected resource could 
   require the client to load resources from a malicious network. This 
   document provides a framework which allows authors to publish 
   authorized connectable second- and third-party resources that a user 
   agent should or must follow depending on configuration of that user 
   agent.

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), its areas, and its working groups.  Note that 
   other groups may also distribute working documents as 
   Internet-Drafts.

   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."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html

   This Internet-Draft will expire on September 13 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction
      1.1  Terminology
      1.2  Applicability
   2  Conventions used in this document
      2.1  DNS Entries published
         2.1.1  Single site and domain example
         2.1.2  Multiple sites and domain example
         2.1.3  Wildcards
   3  Security Considerations
   4  IANA Considerations
   5  References
      5.1  Normative References
   6  Acknowledgments


1  Introduction

   The traditional website model for distributing information has been 
   one of open resource connections. Website authors are in control as
   to how the published resource connections draw upon other resources.

   This model leaves end-users and administrators who require higher
   connection security to either trust the site author implicitly or 
   profile a website and provide connection security through other 
   means.

   Establishing a trust model where all connections are approved by both
   parties, is an additional step in providing a model where users and
   administrators can be assured the website they are using is making
   author-verified connections to second- and third-parties.

   This document covers an implementation for website authors to
   indicate a validation method of second- and third-party resources 
   and a strict or compatible model for browser owners to enforce 
   depending on their security requirements.

1.1 Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The term "researcher" corresponds to the terms "finder" and
   "reporter" in [ISO.29147.2018] and [CERT.CVD].  The term
   "organization" corresponds to the term "vendor" in [ISO.29147.2018]
   and [CERT.CVD].

1.2 Applicability

   This document covers a method of actions user-agents and website
   authors should implement to enhance security. 

2  Conventions used in this document

   First-party connections are those created to the same host listed
   in the URL.

   Second-party connections are those created to other hosts using the
   same top level domain.

   Third-party connections are those to a host with a different host
   listed in the URL.

2.1 DNS Entries published

   The DNS entry is a TXT record which was proposed in [RFC1464]. The
   format of the record begins with uacs=1; and an optional host= 
   identifier, if the domain serves multiple hostnames which require
   user-agent connection security. 

   Every semi-colon separated entry after it must be a [RFC1123]
   and [RFC4343] formatted host identifier.

   Length

2.1.1 Single site and domain example

   An example record for a single website hosted from a domain:

   uacs=1;host.example1.com;*.example2.com;zzz.example-cloud-network.net

2.1.2 Multiple sites and domain example

   If a domain serves multiple websites requiring user-agent connection
   security, these records MUST be broken up into separate TXT records
   with an identifying host tag:

   uacs=1;host=website1.example.com;host.example1.com;*.example2.com
   uacs=1;host=website2.example.com;host.example1.com;*.example2.com

   Hostname entries are separated by semicolons and no spaces. Where
   characters have case representations, all characters should be in
   lower case versions.

2.1.3 Wildcards

   Wildcards are allowed to reduce record sizes and client processing
   time, for example a website hosted at example1.com can include
   resources from *.example2.com in order to accommodate changes
   example2.com may publish to their service.

   The wildcard MUST be interpreted as meaning 0 or more characters. 

   Caution should be used when using wildcards with services that
   publish random hostnames for customers since site authors may not
   intend for data from other customers to be referenced. For example,
   a content distribution network may create content access URIs such
   as 123456.example.net for every customer. A wildcard against this
   network would grant resource load opportunities for any non-related
   customers of that service.

   Only one uacs= and one host= are allowed per TXT record.

2.2 User-Agent Requests

   User-Agents SHOULD include the TXT record request at the time of the
   DNS request to resolve the host name, should subsequently send the
   request to retrieve the uacs= TXT record prior to processing any
   further connection requests other than the initial resource request.

2.3 Caching

   User-Agents SHOULD follow their normal caching rules for the TXT
   records request.

2.4 User-Agent Enforcement Modes

   Compatible, Compliant, Strict

2.4.1 Compatible mode

   Compatible mode is included as a transition option. This mode
   indicates the user-agent SHOULD NOT enforce any uacs entries.

2.4.2 Compliant mode

   Compliant mode indicates the user-agent MUST process and follow the
   rules identified by a website author.

2.4.3 Strict mode

   Strict mode indicates the user-agent should not connect to any
   resources beyond the domain.

2.5 Record Size

   Published records SHOULD be limited to fit within the 512 octet
   limit. If not, it could exceed the DNS protocol limit. For further
   details on the technical details, please see [RFC7208] section 3.4
   entitled Record Size and [RFC2181] section 11 entitled Name Syntax.
   It is RECOMMENDED to follow these directions.

3  Security Considerations

3.1 Sensible initial defaults

   The initial compatible user agent mode was chosen as a lead in order
   to provide a path for adoption due to this RFC requiring changes
   from both website operators and developers of user-agents.

3.2 DNS TXT versus a text file

   The DNS TXT entry was chosen after working through a model with a
   plain text file, similar to security.txt or a robots.txt file. After
   consideration, one of the defensive tactics for UACS is to protect a
   client against a server compromise attack in which a text file could
   be replaced by an attacker. Having the approved connections list
   separate provides an additional layer of defense.

3.3 Misconfigurations

   It is possible to configure the connection host entries too
   inclusively thereby allowing connections to unintended hosts and
   degrading the security posture this RFC is proposing.

3.4 Profiling

   A profile-building model of security is prone to functional deferred
   deprecation upon website updates. For organizations managing security
   profiles, not every security administrator is willing to trust every
   website vendor implicitly, and not every website vendor openly 
   discloses every third-party resource connection. 

   Attacks that leverage injectionable payloads from second- and
   third-party connections require an open connection to an
   attacker-controlled resource. Limiting attacks with connection
   restrictions such as this RFC reduces the available options an
   attacker may use and improves the security posture of the user agent.

4  IANA Considerations

   This draft does not require any IANA action.

5  References

5.1  Normative References

   [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 
             and Support",  RFC 1123, October 1989

   [RFC1464] Rosenbaum, R., "Using the Domain Name System To Store
             Arbitrary String Attributes", RFC 1464,
             DOI 10.17487/RFC1464, May 1993,
             <https://www.rfc-editor.org/rfc/rfc1464>.

   [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
             Requirement Levels", BCP 14, RFC 2119,
             DOI 10.17487/RFC2119, March 1997,
             <https://www.rfc-editor.org/info/rfc2119>.

   [RFC2181] Elz, R., "Clarifications to the DNS Specification",  
             RFC 2181, July 1997

   [RFC4343] Eastlake 3rd, D., "Domain Name System (DNS) Case
             Insensitivity Clarification",  RFC 4343, January 2006

   [RFC7208]  Kitterman, S., "Sender Policy Framework (SPF) for
              Authorizing Use of Domains in Email, Version 1", RFC 7208,
              DOI 10.17487/RFC7208, April 2014,
              <https://www.rfc-editor.org/info/rfc7208>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

6  Acknowledgments

   The author would like to thank Steven Hart, Michael J. Cataletto,
   Yulia Slesavara and the many other team members who contributed
   suggestions and edits to help complete this document.
 
   This document was prepared using 2-Word-v2.0.template.dot.

Authors' Addresses

   David Steckbeck
   Email: dsteckbeck@gatech.edu


name: draft-ietf-lamps-e2e-mail-guidance
rev: 17
title: Guidance on End-to-End E-mail Security
time: 2025-08-23T03:12:49Z
group_uri: /api/v1/group/group/2164/
expires: 2025-07-12T19:18:18Z
ad: /api/v1/person/person/105815/
shepherd: /api/v1/person/email/housley@vigilsec.com/
categories: ["Data formats/interop", "Policy/governance"]
tags: []
fetched_at: 2026-02-27T22:56:05.127593+00:00
abstract:
End-to-end cryptographic protections for e-mail messages can provide
   useful security.  However, the standards for providing cryptographic
   protection are extremely flexible.  That flexibility can trap users
   and cause surprising failures.  This document offers guidance for
   mail user agent implementers to help mitigate those risks, and to
   make end-to-end e-mail simple and secure for the end user.  It
   provides a useful set of vocabulary as well as recommendations to
   avoid common failures.  It also identifies a number of currently
   unsolved usability and interoperability problems.

states:
["/api/v1/doc/state/3/", "/api/v1/doc/state/110/", "/api/v1/doc/state/115/", "/api/v1/doc/state/7/", "/api/v1/doc/state/44/"]

full_text:
lamps                                                 D. K. Gillmor, Ed.
Internet-Draft                                                      ACLU
Intended status: Informational                         B. Hoeneisen, Ed.
Expires: 12 July 2025                                        pEp Project
                                                        A. Melnikov, Ed.
                                                               Isode Ltd
                                                          8 January 2025


                 Guidance on End-to-End E-mail Security
                 draft-ietf-lamps-e2e-mail-guidance-17

Abstract

   End-to-end cryptographic protections for e-mail messages can provide
   useful security.  However, the standards for providing cryptographic
   protection are extremely flexible.  That flexibility can trap users
   and cause surprising failures.  This document offers guidance for
   mail user agent implementers to help mitigate those risks, and to
   make end-to-end e-mail simple and secure for the end user.  It
   provides a useful set of vocabulary as well as recommendations to
   avoid common failures.  It also identifies a number of currently
   unsolved usability and interoperability problems.

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://dkg.gitlab.io/e2e-mail-guidance/.  Status information for
   this document may be found at https://datatracker.ietf.org/doc/draft-
   ietf-lamps-e2e-mail-guidance/.

   Discussion of this document takes place on the LAMPS Working Group
   mailing list (mailto:spasm@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/spasm/.  Subscribe at
   https://www.ietf.org/mailman/listinfo/spasm/.

   Source for this draft and an issue tracker can be found at
   https://gitlab.com/dkg/e2e-mail-guidance.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.






Gillmor, et al.           Expires 12 July 2025                  [Page 1]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   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 12 July 2025.

Copyright Notice

   Copyright (c) 2025 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   6
       1.1.1.  Structural Header Fields  . . . . . . . . . . . . . .   7
       1.1.2.  User-Facing Header Fields . . . . . . . . . . . . . .   8
   2.  Usability . . . . . . . . . . . . . . . . . . . . . . . . . .   9
     2.1.  Simplicity  . . . . . . . . . . . . . . . . . . . . . . .   9
     2.2.  E-mail Users Want a Familiar Experience . . . . . . . . .  10
     2.3.  Warning About Failure vs. Announcing Success  . . . . . .  11
   3.  Types of Protection . . . . . . . . . . . . . . . . . . . . .  11
     3.1.  Simplified Mental Model . . . . . . . . . . . . . . . . .  12
     3.2.  One Cryptographic Status Per Message  . . . . . . . . . .  13
   4.  Cryptographic MIME Message Structure  . . . . . . . . . . . .  14
     4.1.  Cryptographic Layers  . . . . . . . . . . . . . . . . . .  14
       4.1.1.  S/MIME Cryptographic Layers . . . . . . . . . . . . .  14
       4.1.2.  PGP/MIME Cryptographic Layers . . . . . . . . . . . .  15
     4.2.  Cryptographic Envelope  . . . . . . . . . . . . . . . . .  16
     4.3.  Cryptographic Payload . . . . . . . . . . . . . . . . . .  17
     4.4.  Types of Cryptographic Envelope . . . . . . . . . . . . .  17
       4.4.1.  Simple Cryptographic Envelopes  . . . . . . . . . . .  17
       4.4.2.  Multilayer Cryptographic Envelopes  . . . . . . . . .  17



Gillmor, et al.           Expires 12 July 2025                  [Page 2]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


     4.5.  Errant Cryptographic Layers . . . . . . . . . . . . . . .  17
       4.5.1.  Mailing List Wrapping . . . . . . . . . . . . . . . .  18
       4.5.2.  A Baroque Example . . . . . . . . . . . . . . . . . .  18
     4.6.  Cryptographic Summary . . . . . . . . . . . . . . . . . .  19
   5.  Message Composition . . . . . . . . . . . . . . . . . . . . .  19
     5.1.  Message Composition Algorithm . . . . . . . . . . . . . .  19
     5.2.  Encryption Outside, Signature Inside  . . . . . . . . . .  20
     5.3.  Avoid Offering Encrypted-only Messages  . . . . . . . . .  21
     5.4.  Composing a Reply Message . . . . . . . . . . . . . . . .  22
   6.  Message Interpretation  . . . . . . . . . . . . . . . . . . .  23
     6.1.  Rendering Well-formed Messages  . . . . . . . . . . . . .  23
     6.2.  Errant Cryptographic Layers . . . . . . . . . . . . . . .  23
       6.2.1.  Errant Signing Layer  . . . . . . . . . . . . . . . .  23
       6.2.2.  Errant Encryption Layer . . . . . . . . . . . . . . .  25
       6.2.3.  Avoiding Non-MIME Cryptographic Mechanisms  . . . . .  26
     6.3.  Forwarded Messages with Cryptographic Protection  . . . .  27
     6.4.  Signature failures  . . . . . . . . . . . . . . . . . . .  27
     6.5.  Weak Encryption . . . . . . . . . . . . . . . . . . . . .  29
   7.  Reasoning about Message Parts . . . . . . . . . . . . . . . .  30
     7.1.  Main Body Part  . . . . . . . . . . . . . . . . . . . . .  30
     7.2.  Attachments . . . . . . . . . . . . . . . . . . . . . . .  31
     7.3.  MIME Part Examples  . . . . . . . . . . . . . . . . . . .  32
   8.  Certificate Management  . . . . . . . . . . . . . . . . . . .  33
     8.1.  Peer Certificates . . . . . . . . . . . . . . . . . . . .  33
       8.1.1.  Peer Certificate Selection  . . . . . . . . . . . . .  33
     8.2.  Local Certificates  . . . . . . . . . . . . . . . . . . .  34
       8.2.1.  Getting Certificates for the User . . . . . . . . . .  34
       8.2.2.  Local Certificate Maintenance . . . . . . . . . . . .  36
       8.2.3.  Shipping Certificates in Outbound Messages  . . . . .  37
   9.  Common Pitfalls and Guidelines  . . . . . . . . . . . . . . .  38
     9.1.  Reading Sent Messages . . . . . . . . . . . . . . . . . .  39
     9.2.  Reading Encrypted Messages after Certificate
           Expiration  . . . . . . . . . . . . . . . . . . . . . . .  40
     9.3.  Unprotected Message Header Fields . . . . . . . . . . . .  40
     9.4.  Composing an Encrypted Message with Bcc . . . . . . . . .  41
       9.4.1.  Simple Encryption with Bcc  . . . . . . . . . . . . .  41
     9.5.  Draft Messages  . . . . . . . . . . . . . . . . . . . . .  42
     9.6.  Composing a Message to Heterogeneous Recipients . . . . .  43
     9.7.  Message Transport Protocol Proxy: A Dangerous
           Implementation Choice . . . . . . . . . . . . . . . . . .  45
       9.7.1.  Dangers of a Submission Proxy for Message
               Composition . . . . . . . . . . . . . . . . . . . . .  45
       9.7.2.  Dangers of an IMAP Proxy for Message Rendering  . . .  47
       9.7.3.  Who Controls the Proxy? . . . . . . . . . . . . . . .  48
     9.8.  Intervening MUAs Do Not Handle End-to-End Cryptographic
           Protections . . . . . . . . . . . . . . . . . . . . . . .  48
     9.9.  External Subresources in MIME Parts Break Cryptographic
           Protections . . . . . . . . . . . . . . . . . . . . . . .  49



Gillmor, et al.           Expires 12 July 2025                  [Page 3]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  51
   11. Security Considerations . . . . . . . . . . . . . . . . . . .  51
   12. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  51
   13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  51
     13.1.  Normative References . . . . . . . . . . . . . . . . . .  51
     13.2.  Informative References . . . . . . . . . . . . . . . . .  52
   Appendix A.  Future Work  . . . . . . . . . . . . . . . . . . . .  56
     A.1.  Webmail Threat Model  . . . . . . . . . . . . . . . . . .  56
     A.2.  Test Vectors  . . . . . . . . . . . . . . . . . . . . . .  56
     A.3.  Further Guidance on Peer Certificates . . . . . . . . . .  57
       A.3.1.  Certificate Discovery from Incoming Messages  . . . .  57
       A.3.2.  Certificate Directories . . . . . . . . . . . . . . .  57
       A.3.3.  Checking for Certificate Revocation . . . . . . . . .  57
       A.3.4.  Further Peer Certificate Selection  . . . . . . . . .  57
       A.3.5.  Human-readable Names in Peer Certificates, Header
               Fields, and Addressbooks  . . . . . . . . . . . . . .  58
     A.4.  Further Guidance on Local Certificates and Secret Keys  .  58
       A.4.1.  Cross-MUA sharing of Local Certificates and Secret
               Keys  . . . . . . . . . . . . . . . . . . . . . . . .  59
       A.4.2.  Use of Smartcards or Other Portable Secret Key
               Mechanisms  . . . . . . . . . . . . . . . . . . . . .  59
       A.4.3.  Active Local Certificate Maintenance  . . . . . . . .  59
     A.5.  Certification Authorities . . . . . . . . . . . . . . . .  59
     A.6.  Indexing and Search of Encrypted Messages . . . . . . . .  60
     A.7.  Cached Signature Validation . . . . . . . . . . . . . . .  60
     A.8.  Aggregate Cryptographic Status  . . . . . . . . . . . . .  60
     A.9.  Expectations of Cryptographic Protection  . . . . . . . .  61
     A.10. Secure Deletion . . . . . . . . . . . . . . . . . . . . .  61
     A.11. Interaction with Opportunistic Encryption . . . . . . . .  62
     A.12. Split Attachments . . . . . . . . . . . . . . . . . . . .  62
     A.13. Proxy Extensions  . . . . . . . . . . . . . . . . . . . .  62
     A.14. Mailing Lists . . . . . . . . . . . . . . . . . . . . . .  63
   Appendix B.  Document History . . . . . . . . . . . . . . . . . .  64
     B.1.  Substantive changes from draft-ietf-...-16 to
            draft-ietf-...-17  . . . . . . . . . . . . . . . . . . .  64
     B.2.  Substantive changes from draft-ietf-...-15 to
            draft-ietf-...-16  . . . . . . . . . . . . . . . . . . .  64
     B.3.  Substantive changes from draft-ietf-...-14 to
            draft-ietf-...-15  . . . . . . . . . . . . . . . . . . .  64
     B.4.  Substantive changes from draft-ietf-...-13 to
            draft-ietf-...-14  . . . . . . . . . . . . . . . . . . .  64
     B.5.  Substantive changes from draft-ietf-...-12 to
            draft-ietf-...-13  . . . . . . . . . . . . . . . . . . .  65
     B.6.  Substantive changes from draft-ietf-...-11 to
            draft-ietf-...-12  . . . . . . . . . . . . . . . . . . .  65
     B.7.  Substantive changes from draft-ietf-...-10 to
            draft-ietf-...-11  . . . . . . . . . . . . . . . . . . .  65




Gillmor, et al.           Expires 12 July 2025                  [Page 4]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


     B.8.  Substantive changes from draft-ietf-...-09 to
            draft-ietf-...-10  . . . . . . . . . . . . . . . . . . .  65
     B.9.  Substantive changes from draft-ietf-...-08 to
            draft-ietf-...-09  . . . . . . . . . . . . . . . . . . .  65
     B.10. Substantive changes from draft-ietf-...-07 to
            draft-ietf-...-08  . . . . . . . . . . . . . . . . . . .  65
     B.11. Substantive changes from draft-ietf-...-06 to
            draft-ietf-...-07  . . . . . . . . . . . . . . . . . . .  66
     B.12. Substantive changes from draft-ietf-...-05 to
            draft-ietf-...-06  . . . . . . . . . . . . . . . . . . .  66
     B.13. Substantive changes from draft-ietf-...-04 to
            draft-ietf-...-05  . . . . . . . . . . . . . . . . . . .  66
     B.14. Substantive changes from draft-ietf-...-03 to
            draft-ietf-...-04  . . . . . . . . . . . . . . . . . . .  66
     B.15. Substantive changes from draft-ietf-...-02 to
            draft-ietf-...-03  . . . . . . . . . . . . . . . . . . .  67
     B.16. Substantive changes from draft-ietf-...-01 to
            draft-ietf-...-02  . . . . . . . . . . . . . . . . . . .  67
     B.17. Substantive changes from draft-ietf-...-00 to
            draft-ietf-...-01  . . . . . . . . . . . . . . . . . . .  67
     B.18. Substantive changes from draft-dkg-...-01 to
            draft-ietf-...-00  . . . . . . . . . . . . . . . . . . .  67
     B.19. Substantive changes from draft-dkg-...-00 to
            draft-dkg-...-01 . . . . . . . . . . . . . . . . . . . .  67
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  67

1.  Introduction

   E-mail end-to-end security using S/MIME ([RFC8551]) and PGP/MIME
   ([RFC3156]) cryptographic standards can provide integrity,
   authentication and confidentiality to MIME ([RFC4289]) e-mail
   messages.

   However, there are many ways that a receiving mail user agent can
   misinterpret or accidentally break these security guarantees.  For
   example, [EFAIL]'s "Direct Exfiltration" attack leaks cleartext due
   to an attack that splices existing ciphertext into a new message,
   which is then handled optimistically (and wrongly) by many mail user
   agents.

   A mail user agent that interprets a message with end-to-end
   cryptographic protections needs to do so defensively, staying alert
   to different ways that these protections can be bypassed by mangling
   (either malicious or accidental) or a failed user experience.







Gillmor, et al.           Expires 12 July 2025                  [Page 5]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A mail user agent that generates a message with end-to-end
   cryptographic protections should be aware of these defensive
   interpretation strategies, and should compose any new outbound
   message conservatively if they want the protections to remain intact.

   This document offers guidance to the implementer of a mail user agent
   that provides these cryptographic protections, whether for sending or
   receiving mail.  An implementation that follows this guidance will
   provide its users with stronger and easier-to-understand security
   properties, and will also offer more reliable interoperability for
   messages exchanged with other implementations.

   In Appendix A, this document also identifies a number of
   interoperability and usability concerns for end-to-end cryptographic
   e-mail which have no current broadly accepted technical standard for
   resolution.  One major area not covered in this document is the
   acquisition and long-term maintenance of cryptographic identity
   information and metadata across multiple mail user agents controlled
   by the same user.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

1.1.  Terminology

   For the purposes of this document, we define the following concepts:

   *  _MUA_ is short for Mail User Agent; an e-mail client.

   *  _Protection_ of message data refers to cryptographic encryption
      and/or signatures, providing confidentiality, authenticity, and/or
      integrity.

   *  _Cryptographic Layer_, _Cryptographic Envelope_, _Cryptographic
      Payload_, _Cryptographic Summary_, and _Errant Cryptographic
      Layer_ are defined in Section 4

   *  A _well-formed_ e-mail message with cryptographic protection has
      both a _Cryptographic Envelope_ and a _Cryptographic Payload_.

   *  _Structural Header Fields_ are documented in Section 1.1.1.

   *  _User-Facing Header Fields_ are documented in Section 1.1.2.





Gillmor, et al.           Expires 12 July 2025                  [Page 6]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  _Main Body Part_ is the part (or parts) that are typically
      rendered to the user as the message itself (not "as an
      attachment").  See Section 7.1.

   This document contains extensive discussion about end-to-end
   cryptographic protections in e-mail, while acknowledging that many
   MUAs have no capabilities for end-to-end cryptographic protections at
   all.  We divide MUAs into three distinct profiles:

   *  A _Non-cryptographic_ MUA has no capabilities for end-to-end
      cryptographic protections.

   *  A _Conformant_ MUA follows the guidance in this document when
      dealing with end-to-end cryptographic protections.

   *  A _Legacy_ MUA has capabilities for end-to-end cryptographic
      protections, but does not adhere to the the guidance in this
      document.

   At the time of the writing of this document, most MUAs with
   cryptographic protections are legacy MUAs.

1.1.1.  Structural Header Fields

   A message header field named MIME-Version, or whose name begins with
   Content- is referred to in this document as a "structural" header
   field.  This is a less-ambiguous name for what [RFC2045] calls "MIME
   Header Fields".

   These header fields indicate something about the specific MIME part
   they are attached to, and cannot be transferred or copied to other
   parts without endangering the readability of the message.

   This includes:

   *  MIME-Version

   *  Content-Type

   *  Content-Transfer-Encoding

   *  Content-Disposition









Gillmor, et al.           Expires 12 July 2025                  [Page 7]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


1.1.2.  User-Facing Header Fields

   Of all the header fields that an e-mail message may contain, only a
   handful are typically presented directly to the user.  This document
   refers to them as "user-facing" header fields.  Typically, user-
   facing header fields are:

   *  Subject

   *  From

   *  To

   *  Cc

   *  Date

   *  Reply-To

   *  Followup-To

   *  Sender

   *  Resent-From

   *  Resent-To

   *  Resent-Cc

   *  Resent-Date

   *  Resent-Sender

   The above list are the header fields most often presented directly to
   the user who views a message, though an MUA may also decide to treat
   any other header field as "user-facing".  Of course, many of these
   header fields are entirely absent from any given message, and an
   absent header field is not presented to the user at all.

   Note that the resending header fields (those beginning with Resent-)
   are typically only added by an intervening MUA (see Section 3.6.6 of
   [RFC5322] and Section 9.8 of this document).  As such, though they
   may in some cases be presented to the user, they will typically not
   bear any end-to-end cryptographic protection (even if the original
   header fields of a message are protected, see Section 9.3), because
   they are unknown to the original sender.





Gillmor, et al.           Expires 12 July 2025                  [Page 8]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Other header fields may affect the visible rendering of the message
   (e.g., References and In-Reply-To may affect the placement of a
   message in a threaded discussion; or the List-* and Archived-At
   header fields added by mailing lists may cause additional buttons to
   be displayed during rendering), but they are not directly displayed
   to the user and so are not considered "user-facing".

2.  Usability

   Any MUA that enables its user to transition from unprotected messages
   to messages with end-to-end cryptographic protection needs to
   consider how the user understands this transition.  That said, the
   primary goal of the user of an MUA is communication -- so interface
   elements that interfere with communication should be avoided where
   possible.

   Furthermore, it is a near certainty that the user will continue to
   encounter unprotected messages, and may need to send unprotected
   messages (for example, if a given recipient cannot handle
   cryptographic protections).  This means that the MUA needs to provide
   the user with some guidance, so that they understand what protections
   any given message or conversation has.  But the user should not be
   overwhelmed with choices or presented with unactionable information.

2.1.  Simplicity

   The end user (the operator of the MUA) is unlikely to understand
   complex end-to-end cryptographic protections on any e-mail message,
   so keep it simple.

   For clarity to the user, any cryptographic protections should apply
   to the message as a whole, not just to some subparts.

   This is true for message composition: the standard message
   composition user interface of an MUA should offer minimal controls
   which indicate which types of protection to apply to the new message
   as a whole.

   This is also true for message interpretation: the standard message
   rendering user interface of an MUA should offer a minimal, clear
   indicator about the end-to-end cryptographic status of the message as
   a whole.

   See Section 3 for more detail about mental models and cryptographic
   status.






Gillmor, et al.           Expires 12 July 2025                  [Page 9]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   (It is of course possible that a message forwarded as a MIME
   attachment could have its own cryptographic status while still being
   a message subpart; but that status should be distinct from the status
   of the enclosing message.)

2.2.  E-mail Users Want a Familiar Experience

   A person communicating over the Internet today often has many options
   for reaching their desired correspondent, including web-based
   bulletin boards, contact forms, and instant messaging services.

   E-mail offers a few distinctions from these other systems, most
   notably features like:

   *  Ubiquity: Most correspondents will have an e-mail address, while
      not everyone is present on the various non-e-mail messaging
      services, particularly those that have reliable end-to-end
      cryptographic protections,

   *  Federation: interaction between users on distinct domains who have
      not agreed on a common communications provider is still possible,
      and

   *  User Control: the user can interact with the e-mail system using
      an MUA of their choosing, including automation and other control
      over their preferred and/or customized workflow.

   Other systems (like some popular instant messaging applications, such
   as WhatsApp and Signal Private Messenger) offer built-in end-to-end
   cryptographic protections by default, which are simpler for the user
   to understand.  ("All the messages I see on Signal are confidential
   and integrity-protected" is a clean user story)

   A user of e-mail is likely using e-mail instead of other systems
   because of the distinctions outlined above.  When adding end-to-end
   cryptographic protection to an e-mail endpoint, care should be taken
   not to negate any of the distinct features of e-mail as a whole.  If
   these features are violated to provide end-to-end crypto, the user
   may just as well choose one of the other systems that don't have the
   drawbacks that e-mail has.  Implementers should try to provide end-
   to-end protections that retain the familiar experience of e-mail
   itself.









Gillmor, et al.           Expires 12 July 2025                 [Page 10]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Furthermore, an e-mail user is likely to regularly interact with
   other e-mail correspondents who _cannot_ handle or produce end-to-end
   cryptographic protections.  Care should be taken that enabling
   cryptography in an MUA does not inadvertently limit the ability of
   the user to interact with correspondents who use legacy or non-
   cryptographic MUAs.

2.3.  Warning About Failure vs. Announcing Success

   Moving the web from http to https offers useful historical
   similarities to adding end-to-end encryption to e-mail.

   In particular, the indicators of what is "secure" vs. "insecure" for
   web browsers have changed over time.  For example, years ago the
   default experience was http, and https sites were flagged with
   "secure" indicators like a lock icon.  Starting in 2018, some
   browsers reversed that process by downplaying https, and instead
   visibly marking http as "not secure" (see [chrome-indicators]).

   By analogy, when the user of an MUA first enables end-to-end
   cryptographic protection, it's likely that they will want to see
   which messages _have_ protection (that is, the security indicators
   amenable to a conformant MUA as of 2024 are most likely to be
   comparable to those of a pre-2018 web browser).  But a user whose
   private e-mail communications with a given correspondent, or within a
   given domain are known to be entirely end-to-end protected might
   instead want to know which messages do _not_ have the expected
   protections.

   Note also that some messages may be expected to be confidential, but
   other messages are expected to be public -- the types of protection
   (see Section 3) that apply to each particular message will be
   different.  And the types of protection that are _expected_ to be
   present in any context might differ (for example, by sender, by
   thread, or by date).

   It is out of scope for this document to define expectations about
   protections for any given message, but an implementer who cares about
   usable experience should be deliberate and judicious about the
   expectations their interface assumes that the user has in a given
   context.  See also Appendix A.9 for future work.

3.  Types of Protection

   A given message might be:

   *  signed,




Gillmor, et al.           Expires 12 July 2025                 [Page 11]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  encrypted,

   *  both signed and encrypted, or

   *  none of the above.

   Given that many e-mail messages offer no cryptographic protections,
   the user needs to be able to detect which protections are present for
   any given message.

3.1.  Simplified Mental Model

   To the extent that an e-mail message actually does have end-to-end
   cryptographic protections, those protections need to be visible and
   comprehensible to the end users: both the sending user and the
   receiving user.  If either user is unaware of the protections, then
   they do not effectively extend all the way to the "end".

   However, most users do not have (or want to have) a sophisticated
   mental model of what kinds of protections can be associated with a
   given message.  Even the four states above approach the limits of
   complexity for an interface for normal users.

   While Section 5.3 recommends avoiding deliberate creation of
   encrypted-only messages, some messages may end up in the encrypted-
   only state due to signature failure or certificate revocation.

   A simple model for the receiving user could be that a message is in
   one of three normal states, which align with the only reasonable
   choices for message composition:

   *  Unprotected

   *  Verified (has a valid signature from the apparent sender of the
      message)

   *  Confidential (meaning, encrypted, with a valid signature from the
      apparent sender of the message)

   However, one error state exists for received mail that does not
   correspond to a reasonable choice for message composition:

   *  Encrypted But Unverified (meaning, encrypted without a valid
      signature from the apparent sender of the message)

   Note that this last state is not "Confidential" (a secret shared
   exclusively between the participants in the communication) because
   the recipient does not know for sure who sent it.



Gillmor, et al.           Expires 12 July 2025                 [Page 12]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   In an ecosystem where encrypted-only messages are never deliberately
   sent (see Section 5.3), representing an Encrypted But Unverified
   message as a type of user-visible error is not unreasonable.
   However, this is not the state of the global e-mail ecosystem when
   this document was written, since some legacy MUAs permit sending
   encrypted-but-unsigned mail (see Appendix A.9 for possible future
   guidance).

   Alternately, an MUA may prefer to represent the state of a Encrypted
   but Unverified message to the user as though it was Unprotected,
   since no verification is possible.  However the MUA represents the
   message to the user, though, it MUST NOT leak cleartext of an
   encrypted message (even an Encrypted but Unverified message) in
   subsequent replies (see Section 5.4) or similar replications of the
   message.

   Note that a cleartext message with an invalid signature SHOULD NOT be
   represented to the user as anything other than Unprotected (see
   Section 6.4), unless the MUA is providing the user with debugging
   information.

   At the time this document was written, the global e-mail ecosystem
   contains a heterogeneous mix of legacy and non-cryptographic MUAs.
   In such an ecosystem, a conformant MUA may prefer instead to
   represent "Verified" and "Encrypted" as orthogonal states of any
   given received message.  While this model does not precisely match
   the choice a user makes when composing a message, it may align more
   with the reality of the range of messages they receive.

3.2.  One Cryptographic Status Per Message

   Some MUAs may attempt to generate multiple copies of a given e-mail
   message, with different copies offering different types of protection
   (for example, opportunistically encrypting on a per-recipient basis).
   A message resulting from this approach will have a cryptographic
   state that few users will understand.  Even if the sender understands
   the different statuses of the different copies, the recipients of the
   messages may not understand (each recipient might not even know about
   the other copies).  See for example the discussion in Section 9.6 for
   how this can go wrong.

   For comprehensibility, a conformant MUA SHOULD NOT create multiple
   copies of a given message that differ in the types of end-to-end
   cryptographic protections afforded.

   For opportunistic cryptographic protections that are not surfaced to
   the user (that is, that are not end-to-end), other mechanisms like
   transport encryption ([RFC3207]) or domain-based signing ([RFC6376])



Gillmor, et al.           Expires 12 July 2025                 [Page 13]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   may be preferable due to ease of implementation and deployment.
   These opportunistic transport protections are orthogonal to the end-
   to-end protections described in this document.

   To the extent that opportunistic message protections are made visible
   to the user for a given copy of a message, a conformant MUA will
   distinguish that status from the message's end-to-end cryptographic
   status.  But the potential confusion caused by rendering this
   complex, hybrid state may not be worth the value of additional
   knowledge gained by the user.  The benefits of opportunistic
   protections accrue (or don't) even without visibility to the user
   (see [RFC7435]).

   The user needs a single clear, simple, and correct indication about
   the end-to-end cryptographic status of any given message.  See
   Section 4.6 for more details.

4.  Cryptographic MIME Message Structure

   Implementations use the structure of an e-mail message to establish
   (when sending) and understand (when receiving) the cryptographic
   status of the message.  This section establishes some conventions
   about how to think about message structure.

4.1.  Cryptographic Layers

   "Cryptographic Layer" refers to a MIME substructure that supplies
   some cryptographic protections to an internal MIME subtree.  The
   internal subtree is known as the "protected part" though of course it
   may itself be a multipart object.

   In the diagrams below, "↧" (DOWNWARDS ARROW FROM BAR, U+21A7)
   indicates "decrypts to", and "⇩" (DOWNWARDS WHITE ARROW, U+21E9)
   indicates "unwraps to".

4.1.1.  S/MIME Cryptographic Layers

   For S/MIME [RFC8551], there are four forms of Cryptographic Layers:
   multipart/signed, PKCS #7 signed-data, PKCS #7 enveloped-data, PKCS
   #7 authEnveloped-data.

4.1.1.1.  S/MIME Multipart Signed Cryptographic Layer

   └┬╴multipart/signed; protocol="application/pkcs7-signature"
    ├─╴[protected part]
    └─╴application/pkcs7-signature

   This MIME layer offers authentication and integrity.



Gillmor, et al.           Expires 12 July 2025                 [Page 14]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


4.1.1.2.  S/MIME PKCS #7 signed-data Cryptographic Layer

   └─╴application/pkcs7-mime; smime-type="signed-data"
    ⇩ (unwraps to)
    └─╴[protected part]

   This MIME layer offers authentication and integrity.

4.1.1.3.  S/MIME PKCS #7 enveloped-data Cryptographic Layer

   └─╴application/pkcs7-mime; smime-type="enveloped-data"
    ↧ (decrypts to)
    └─╴[protected part]

   This MIME layer offers confidentiality.

4.1.1.4.  S/MIME PKCS #7 authEnveloped-data Cryptographic Layer

   └─╴application/pkcs7-mime; smime-type="authEnveloped-data"
    ↧ (decrypts to)
    └─╴[protected part]

   This MIME layer offers confidentiality and integrity.

   Note that enveloped-data (Section 4.1.1.3) and authEnveloped-data
   (Section 4.1.1.4) have identical message structure and very similar
   confidentiality semantics.  The only difference between the two is
   ciphertext malleability.

   The examples in this document only include enveloped-data, but the
   implications for that layer apply to authEnveloped-data as well.

4.1.1.5.  PKCS #7 Compression is NOT a Cryptographic Layer

   The Cryptographic Message Syntax (CMS) provides a MIME compression
   layer (smime-type="compressed-data"), as defined in [RFC3274].  While
   the compression layer is technically a part of CMS, it is not
   considered a Cryptographic Layer for the purposes of this document.

4.1.2.  PGP/MIME Cryptographic Layers

   For PGP/MIME [RFC3156] there are two forms of Cryptographic Layers,
   signing and encryption.

4.1.2.1.  PGP/MIME Signing Cryptographic Layer (multipart/signed)






Gillmor, et al.           Expires 12 July 2025                 [Page 15]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   └┬╴multipart/signed; protocol="application/pgp-signature"
    ├─╴[protected part]
    └─╴application/pgp-signature

   This MIME layer offers authenticity and integrity.

4.1.2.2.  PGP/MIME Encryption Cryptographic Layer (multipart/encrypted)

   └┬╴multipart/encrypted
    ├─╴application/pgp-encrypted
    └─╴application/octet-stream
     ↧ (decrypts to)
     └─╴[protected part]

   This MIME layer can offer any of:

   *  confidentiality (via a Symmetrically Encrypted Data Packet, see
      Section 5.7 of [RFC9580]; an MUA MUST NOT generate this form due
      to ciphertext malleability)

   *  confidentiality and integrity (via a Symmetrically Encrypted
      Integrity Protected Data Packet (SEIPD), see Section 5.13 of
      [RFC9580]), or

   *  confidentiality, integrity, and authenticity all together (by
      including an OpenPGP Signature Packet within the SEIPD).

4.2.  Cryptographic Envelope

   The Cryptographic Envelope is the largest contiguous set of
   Cryptographic Layers of an e-mail message starting with the outermost
   MIME type (that is, with the Content-Type of the message itself).

   If the Content-Type of the message itself is not a Cryptographic
   Layer, then the message has no cryptographic envelope.

   "Contiguous" in the definition above indicates that if a
   Cryptographic Layer is the protected part of another Cryptographic
   Layer, the layers together comprise a single Cryptographic Envelope.

   Note that if a non-Cryptographic Layer intervenes, all Cryptographic
   Layers within the non-Cryptographic Layer _are not_ part of the
   Cryptographic Envelope.  They are Errant Cryptographic Layers (see
   Section 4.5).

   Note also that the ordering of the Cryptographic Layers implies
   different cryptographic properties.  A signed-then-encrypted message
   is different than an encrypted-then-signed message.  See Section 5.2.



Gillmor, et al.           Expires 12 July 2025                 [Page 16]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


4.3.  Cryptographic Payload

   The Cryptographic Payload of a message is the first non-Cryptographic
   Layer -- the "protected part" -- within the Cryptographic Envelope.

4.4.  Types of Cryptographic Envelope

4.4.1.  Simple Cryptographic Envelopes

   As described above, if the "protected part" identified in the section
   above is not itself a Cryptographic Layer, that part _is_ the
   Cryptographic Payload.

   If the application wants to generate a message that is both encrypted
   and signed, it MAY use the simple MIME structure from Section 4.1.2.2
   by ensuring that the [RFC9580] Encrypted Message within the
   application/octet-stream part contains an [RFC9580] Signed Message
   (the final option described in Section 4.1.2.2).

4.4.2.  Multilayer Cryptographic Envelopes

   It is possible to construct a Cryptographic Envelope consisting of
   multiple layers with either S/MIME or PGP/MIME , for example using
   the following structure:

   A └─╴application/pkcs7-mime; smime-type="enveloped-data"
   B  ↧ (decrypts to)
   C  └─╴application/pkcs7-mime; smime-type="signed-data"
   D   ⇩ (unwraps to)
   E   └─╴[protected part]

   When handling such a message, the properties of the Cryptographic
   Envelope are derived from the series A, C.

   As noted in Section 4.4.1, PGP/MIME applications also have a simpler
   MIME construction available with the same cryptographic properties.

4.5.  Errant Cryptographic Layers

   Due to confusion, malice, or well-intentioned tampering, a message
   may contain a Cryptographic Layer that is not part of the
   Cryptographic Envelope.  Such a layer is an Errant Cryptographic
   Layer.

   An Errant Cryptographic Layer MUST NOT contribute to the message's
   overall cryptographic state.





Gillmor, et al.           Expires 12 July 2025                 [Page 17]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Guidance for dealing with Errant Cryptographic Layers can be found in
   Section 6.2.

4.5.1.  Mailing List Wrapping

   Some mailing list software will re-wrap a well-formed signed message
   before re-sending to add a footer, resulting in the following
   structure seen by recipients of the e-mail:

   H └┬╴multipart/mixed
   I  ├┬╴multipart/signed
   J  │├─╴text/plain
   K  │└─╴application/pgp-signature
   L  └─╴text/plain

   In this message, L is the footer added by the mailing list.  I is now
   an Errant Cryptographic Layer.

   Note that this message has no Cryptographic Envelope at all.

   It is NOT RECOMMENDED to produce e-mail messages with this structure,
   because a legacy MUA may present the data in part L as though it were
   part of J, though they have different cryptographic properties.  In
   particular, if the user believes that the entire message is signed,
   but cannot distinguish L from J then the author of L can effectively
   tamper with content of the signed message, breaking the user's
   expectation of integrity and authenticity.

4.5.2.  A Baroque Example

   Consider a message with the following overcomplicated structure:

   M └┬╴multipart/encrypted
   N  ├─╴application/pgp-encrypted
   O  └─╴application/octet-stream
   P   ↧ (decrypts to)
   Q   └┬╴multipart/signed
   R    ├┬╴multipart/mixed
   S    │├┬╴multipart/signed
   T    ││├─╴text/plain
   U    ││└─╴application/pgp-signature
   V    │└─╴text/plain
   W    └─╴application/pgp-signature








Gillmor, et al.           Expires 12 July 2025                 [Page 18]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   The 3 Cryptographic Layers in such a message are rooted in parts M,
   Q, and S.  But the Cryptographic Envelope of the message consists
   only of the properties derived from the series M, Q.  The
   Cryptographic Payload of the message is part R.  Part S is an Errant
   Cryptographic Layer.

   Note that this message has both a Cryptographic Envelope _and_ an
   Errant Cryptographic Layer.

   It is NOT RECOMMENDED to generate messages with such complicated
   structures.  Even if a receiving MUA can parse this structure
   properly, it is nearly impossible to render in a way that the user
   can reason about the cryptographic properties of part T compared to
   part V.

4.6.  Cryptographic Summary

   The cryptographic status of an e-mail message with end-to-end
   cryptographic protections is known as the Cryptographic Summary.  A
   reasonable, simple Cryptographic Summary is derived from the
   aggregate properties of the layers in the Cryptographic Envelope.
   This is a conceptual tool and a feature that an MUA can use to guide
   behavior and user experience, but it is not necessarily always
   directly exposed in any given user interface.  See Section 6.1 for
   guidance and considerations about rendering the Cryptographic Summary
   to the user.

5.  Message Composition

   This section describes the ideal composition of an e-mail message
   with end-to-end cryptographic protection.  A message composed with
   this form is most likely to achieve its end-to-end security goals.

5.1.  Message Composition Algorithm

   This section describes the steps that an MUA should use to compose a
   cryptographically-protected message, such that it has a proper
   Cryptographic Envelope and Payload.

   The message composition algorithm takes three parameters:

   *  origbody: the traditional unprotected message body as a well-
      formed MIME tree (possibly just a single MIME leaf part).  As a
      well-formed MIME tree, origbody already has structural header
      fields present (see Section 1.1.1).






Gillmor, et al.           Expires 12 July 2025                 [Page 19]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  origheaders: the intended non-structural header fields for the
      message, represented here as a list of (h,v) pairs, where h is a
      header field name and v is the associated value.

   *  crypto: The series of cryptographic protections to apply (for
      example, "sign with the secret key corresponding to X.509
      certificate X, then encrypt to X.509 certificates X and Y").  This
      is a routine that accepts a MIME tree as input (the Cryptographic
      Payload), wraps the input in the appropriate Cryptographic
      Envelope, and returns the resultant MIME tree as output.

   The algorithm returns a MIME object that is ready to be injected into
   the mail system:

   1.  Apply crypto to origbody, yielding MIME tree output

   2.  For each header name and value (h,v) in origheaders:

       a.  Add header h to output with value v

   3.  Return output

   This is the traditional algorithm.  It only protects the structural
   Header Fields of the message body, and leaves non-structural
   (including user-facing) Header Fields unprotected.

   Therefore, a conformant MUA MUST implement Header Protection as
   described in [I-D.ietf-lamps-header-protection] (see Section 9.3).

5.2.  Encryption Outside, Signature Inside

   An e-mail message that is both signed and encrypted is signed
   _inside_ the encryption, and not the other way around.  For example,
   when crafting an encrypted and signed message using a simple
   Cryptographic Envelope of a single layer (Section 4.4.1) with PGP/
   MIME, the OpenPGP Encrypted Message object should contain an OpenPGP
   Signed Message.  Likewise, when using a multilayer Cryptographic
   Envelope (Section 4.4.2), the outer layer should be an encryption
   layer and the inner layer should be a signing layer.

   Putting the signature inside the encryption has two advantages:

   *  The details of the signature remain confidential, visible only to
      the parties capable of decryption.

   *  Any mail transport agent that modifies the message is unlikely to
      be able to accidentally break the signature.




Gillmor, et al.           Expires 12 July 2025                 [Page 20]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A conformant MUA MUST NOT generate an encrypted and signed message
   where the only signature is outside the encryption.

5.3.  Avoid Offering Encrypted-only Messages

   When generating an e-mail, there are four options for applying end-
   to-end cryptographic protections:

   *  Unprotected: In some cases, offering any end-to-end cryptographic
      protection is harmful: it may confuse the recipient and offer no
      benefit.

   *  Signed-only: In other cases, signing a message is useful
      (authenticity and integrity are desirable) but encryption is
      either impossible (for example, if the sender does not know how to
      encrypt to all recipients) or meaningless (for example, an e-mail
      message to a mailing list that is intended to be published to a
      public archive).

   *  Signed-and-Encryped: In other cases, full end-to-end
      confidentiality, authenticity, and integrity are desirable.

   *  Encrypted-only: There is no common use case for generating an
      e-mail message with end-to-end confidentiality but without
      authenticity or integrity.

      -  Additionally, some encryption schemes are malleable.  This
         allows an attacker to tamper with the plaintext by modifying
         the ciphertext (i.e., without decrypting it).  One way to
         prevent this is to authenticate the ciphertext, e.g., using
         signatures, MACs, or AEAD schemes.  See the CBC/CFB gadget
         attack in [EFAIL].

   A conformant MUA should keep its message composition interface
   simple.  When presenting the user with a choice of cryptographic
   protection, it MUST offer no more than three choices:

   *  No end-to-end cryptographic protection

   *  Verified (signed only)

   *  Confidential (signed and encrypted)

   Note that these choices correspond to the simplified mental model in
   Section 3.1.






Gillmor, et al.           Expires 12 July 2025                 [Page 21]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A common anti-pattern among legacy MUAs is offering two boolean
   choices: one to toggle signing, another to toggle encryption.  This
   creates usability hurdles:

   *  A user who wants to send a signed and encrypted message will have
      to click two buttons instead of one.

   *  A user who clicks "Encrypt" but neglects to click "Signed" may not
      understand that they are creating a message which cannot be
      authenticated by the receiver.

5.4.  Composing a Reply Message

   When replying to a message, most MUAs compose an initial draft of the
   reply that contains quoted text from the original message.  A
   responsible MUA will take precautions to avoid leaking the cleartext
   of an encrypted message in such a reply.

   If the original message was end-to-end encrypted, the replying MUA
   MUST either:

   *  compose the reply with end-to-end encryption, or

   *  avoid including quoted text from the original message.

   In general, MUAs SHOULD prefer the first option: to compose an
   encrypted reply.  This is what users expect.

   However, in some circumstances, the replying MUA cannot compose an
   encrypted reply.  For example, the MUA might not have a valid,
   unexpired, encryption-capable certificate for all recipients.  This
   can also happen during composition when a user adds a new recipient
   into the reply, or manually toggles the cryptographic protections to
   remove encryption.

   In this circumstance, the composing MUA SHOULD strip the quoted text
   from the original message, unless the user indicates that they are
   deliberately including previously confidential content in a non-
   confidential message.

   Note additional nuance about replies to malformed messages that
   contain encryption in Section 6.2.2.1.









Gillmor, et al.           Expires 12 July 2025                 [Page 22]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


6.  Message Interpretation

   Despite the best efforts of well-intentioned senders to create e-mail
   messages with well-formed end-to-end cryptographic protection,
   receiving MUAs will inevitably encounter some messages with malformed
   end-to-end cryptographic protection.

   This section offers guidance on dealing with both well-formed and
   malformed messages containing Cryptographic Layers.

6.1.  Rendering Well-formed Messages

   A message is well-formed when it has a Cryptographic Envelope, a
   Cryptographic Payload, and no Errant Cryptographic Layers.  Rendering
   a well-formed message is straightforward.

   The receiving MUA evaluates and assembles the cryptographic
   properties of the Cryptographic Envelope into a Cryptographic Summary
   and displays that status to the user in a secure, strictly-controlled
   part of the UI.  In particular, the part of the UI used to render the
   Cryptographic Summary of the message MUST NOT be spoofable,
   modifiable, or otherwise controllable by the received message itself.
   By analogy, consider the "lock" icon in the address bar of the web
   browser: regardless of the content of the webpage, the lock icon will
   only be displayed when the transport to the web server is adequately
   secured.

   Aside from this Cryptographic Summary, the message itself MUST be
   rendered as though the Cryptographic Payload is the body of the
   message.  The Cryptographic Layers themselves SHOULD NOT be rendered
   as distinct objects unless the MUA is providing the user with
   debugging information.

6.2.  Errant Cryptographic Layers

   If an incoming message has any Errant Cryptographic Layers, a
   conformant interpreting MUA MUST ignore those layers when rendering
   the Cryptographic Summary of the message to the user.

6.2.1.  Errant Signing Layer

   When rendering a message with an Errant Cryptographic Layer that
   provides authenticity and integrity (via signatures), the message
   should be rendered by replacing the Cryptographic layer with the part
   it encloses.

   For example, a message with this structure:




Gillmor, et al.           Expires 12 July 2025                 [Page 23]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A └┬╴multipart/mixed
   B  ├╴text/plain
   C  ├┬╴multipart/signed
   D  │├─╴image/jpeg
   E  │└─╴application/pgp-signature
   F  └─╴text/plain

   Should be rendered identically to this:

   A └┬╴multipart/mixed
   B  ├─╴text/plain
   D  ├─╴image/jpeg
   F  └─╴text/plain

   In such a situation, a conformant MUA MUST NOT indicate in the
   Cryptographic Summary that the message is signed.  It MUST indicate
   that the message is Unprotected.

6.2.1.1.  Exception: Mailing List Footers

   The use case described in Section 4.5.1 is common enough in some
   contexts that a conformant MUA MAY decide to handle it as a special
   exception.

   If the MUA determines that the message comes from a mailing list (for
   example, it has a List-ID header), and it has a structure that
   appends a footer to a signing-only Cryptographic Layer with a valid
   signature, such as:

   H └┬╴multipart/mixed
   I  ├┬╴multipart/signed
   J  │├─╴[protected part, may be arbitrary MIME subtree]
   K  │└─╴application/{pgp,pkcs7}-signature
   L  └─╴[footer, typically text/plain]

   or:

   H └┬╴multipart/mixed
   I  ├─╴application/pkcs7-mime; smime-type="signed-data"
      │⇩ (unwraps to)
   J  │└─╴[protected part, may be an arbitrary MIME subtree]
   L  └─╴[footer, typically text/plain]

   Then, the MUA MAY indicate to the user that this is a Verified
   message that has been wrapped by the mailing list.






Gillmor, et al.           Expires 12 July 2025                 [Page 24]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   In this case, the MUA MUST distinguish the footer (part L) from the
   protected part (part J) when rendering any information about the
   signature.

   One way to do this is to offer the user two different views of the
   message: the "mailing list" view, which hides any positive
   Cryptographic Summary but shows the footer:

   Cryptographic Protections: Unprotected
   H └┬╴multipart/mixed
   J  ├─╴[protected part, may be arbitrary MIME subtree]
   L  └─╴[footer, typically text/plain]

   or the "sender's view", which shows the Cryptographic Summary as
   Verified, but hides the footer:

   Cryptographic Protections: Verified [details from part I]
   J └─╴[protected part, may be arbitrary MIME subtree]

6.2.2.  Errant Encryption Layer

   An MUA may encounter a message with an Errant Cryptographic Layer
   that offers confidentiality (encryption), and the MUA is capable of
   decrypting it.

   The user wants to be able to see the contents of any message that
   they receive, so a conformant MUA in this situation SHOULD decrypt
   the part.

   In this case, though, a conformant MUA MUST NOT indicate in the
   message's Cryptographic Summary that the message itself was
   encrypted.  Such an indication could be taken to mean that other
   (non-encrypted) parts of the message arrived with cryptographic
   confidentiality.

   Furthermore, when decrypting an Errant Cryptographic Layer, the MUA
   MUST treat the decrypted cleartext as a distinct MIME subtree, and
   not attempt to merge or splice it together with any other part of the
   message.  This offers protection against the direct exfiltration
   (also known as EFAIL-DE) attacks described in [EFAIL] and so-called
   multipart/oracle attacks described in [ORACLE].

6.2.2.1.  Replying to a Message with an Errant Encryption Layer

   Note that there is an asymmetry here between rendering and replying
   to a message with an Errant Encryption Layer.





Gillmor, et al.           Expires 12 July 2025                 [Page 25]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   When rendering, the MUA does not indicate that the message was
   encrypted, even if some subpart of it was decrypted for rendering.

   When composing a reply to a message that has any encryption layer,
   even an errant one, the reply message SHOULD be marked for
   encryption, unless quoted and attributed text is not included in the
   reply, as noted in Section 5.4.

   When composing a reply to a message with an errant cryptographic
   layer, a conformant MUA MUST NOT decrypt any errant cryptographic
   layers when generating quoted or attributed text.  This will
   typically mean either leaving the ciphertext itself in the generated
   reply message, or simply not generating any quoted or attributed text
   at all.  This offers protection against the reply-based attacks
   described in [REPLY].

   In all circumstances, if the reply message cannot be encrypted (or if
   the user elects to not encrypt the reply), the composed reply MUST
   NOT include any material from the decrypted subpart.

6.2.3.  Avoiding Non-MIME Cryptographic Mechanisms

   In some cases, there may be a cryptographic signature or encryption
   that does not coincide with a MIME boundary.  For example so-called
   "PGP Inline" messages typically contain base64-encoded ("ASCII-
   armored", see Section 6 of [RFC9580]) ciphertext, or within the
   content of a MIME part.

6.2.3.1.  Do Not Validate Non-MIME Signatures

   When encountering cryptographic signatures in these positions, a
   conformant MUA MUST NOT attempt to validate any signature.  It is
   challenging to communicate to the user exactly which part of such a
   message is covered by the signature, so it is better to leave the
   message marked as Unprotected.  See [SPOOFING] for examples of
   spoofed message signatures that rely on permissive legacy clients
   that are willing to validate signatures in poorly-structured
   messages.

6.2.3.2.  Skip or Isolate Non-MIME Decryption When Rendering

   When encountering what appears to be encrypted data not at a MIME
   boundary, a conformant MUA MAY decline to decrypt the data at all.

   During message rendering, if a conformant MUA attempts decryption of
   such a non-MIME encrypted section of an e-mail, it MUST synthesize a
   separate MIME part to contain only the decrypted data, and not
   attempt to merge or splice that part together with any other part of



Gillmor, et al.           Expires 12 July 2025                 [Page 26]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   the message.  Keeping such a section distinct and isolated from any
   other part of the message offers protection against the direct
   exfiltration attacks (also known as EFAIL-DE) described in [EFAIL].

6.2.3.3.  Do Not Decrypt Non-MIME Decryption when Replying

   When composing a reply to a message with such a non-MIME encrypted
   section, a conformant MUA MUST NOT decrypt any non-MIME encrypted
   section when generating quoted or attributed text, similar to the
   guidance in Section 6.2.2.1.

   This offers protection against the reply-based attacks described in
   [REPLY].

6.3.  Forwarded Messages with Cryptographic Protection

   An incoming e-mail message may include an attached forwarded message,
   typically as a MIME subpart with Content-Type: message/rfc822
   ([RFC5322]) or Content-Type: message/global ([RFC5355]).

   Regardless of the cryptographic protections and structure of the
   incoming message, the internal forwarded message may have its own
   Cryptographic Envelope.

   The Cryptographic Layers that are part of the Cryptographic Envelope
   of the forwarded message are not Errant Cryptographic Layers of the
   surrounding message -- they are simply layers that apply to the
   forwarded message itself.

   A conformant rendering MUA MUST NOT conflate the cryptographic
   protections of the forwarded message with the cryptographic
   protections of the incoming message.

   A conformant rendering MUA MAY render a Cryptographic Summary of the
   protections afforded to the forwarded message by its own
   Cryptographic Envelope, as long as that rendering is unambiguously
   tied to the forwarded message itself, and cannot be spoofed either by
   the enclosing message or by the forwarded message.

6.4.  Signature failures

   A cryptographic signature may fail in multiple ways.  A conformant
   receiving MUA that discovers a failed signature treats the message as
   though the signature did not exist.  This is similar to the standard
   guidance for about failed DKIM signatures (see Section 6.1 of
   [RFC6376]).





Gillmor, et al.           Expires 12 July 2025                 [Page 27]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A conformant MUA MUST NOT render a message with a failed signature as
   more dangerous or more dubious than a comparable message without any
   signature at all.  In both cases, the Cryptographic Summary should be
   Unprotected.

   A conformant MUA that encounters an encrypted-and-signed message
   where the signature is invalid SHOULD treat the message the same way
   that it would treat a message that is encryption-only, unless the MUA
   is providing the user with debugging information.

   Some different ways that a signature may be invalid on a given
   message:

   *  the signature is not cryptographically valid (the math fails).

   *  the signature relies on suspect cryptographic primitives (e.g.,
      over a deprecated digest algorithm, or was made by a weak key,
      e.g., 1024-bit RSA); note that this requires the rendering MUA to
      have an explicit policy about what cryptographic primitives are
      acceptable.

   *  the signature is made by a certificate which the receiving MUA
      does not have access to.

   *  the certificate used to verify the signature was revoked.

   *  the certificate used to verify the signature was expired at the
      time that the signature was made.

   *  the certificate used to verify the signature does not correspond
      to the author of the message. (for X.509, there is no
      subjectAltName of type rfc822Name whose value matches an e-mail
      address found in From: or Sender:)

   *  the certificate used to verify the signature was not issued by an
      authority that the MUA user is willing to rely on for certifying
      the sender's e-mail address, and the user has no other reasonable
      indication that the certificate belongs to the sender's e-mail
      address.

   *  the signature indicates that it was made at a time much before or
      much after from the date of the message itself.

   *  The signature covers a message that depends on an external
      subresource that might change (see Section 9.9).

   A valid signature must pass all these tests, but of course invalid
   signatures may be invalid in more than one of the ways listed above.



Gillmor, et al.           Expires 12 July 2025                 [Page 28]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


6.5.  Weak Encryption

   Sometimes, an MUA might encounter a message with a well-formed
   Cryptographic Envelope that uses a form of encryption with
   substantial known flaws.  For example, a PGP/MIME message might use a
   Symmetrically Encrypted Data packet, which is known to have malleable
   ciphertext (see Section 5.7 of [RFC9580]). ِAs another example, an S/
   MIME message may use an enveloped-data MIME part with a
   contentEncryptionAlgorithm of rc2-cbc with rc2ParameterVersion of
   160, meaning a 40-bit key (see Section 5.2 of [RFC3370]), which is
   widely considered breakable via brute force with moderate hardware
   investment in 2024.  As cryptanalysis and hardware capacities
   advance, an implementation may widen the scope of what encryption
   mechanisms are considered weak.

   A receiving MUA MUST warn the user that such a message has a known
   weakness.  The receiving MUA MAY decline to decrypt such a message at
   all.  If it decides to decrypt a message with a weak encryption
   layer, it MUST NOT indicate in the message's Cryptographic Summary
   that the message was encrypted, as the confidentiality of the message
   is suspect.  This is similar to the approach taken in Section 6.2.2
   for messages with an Errant Encryption Layer.

   Like the Errant Encryption Layer situation, there is an asymmetry
   between rendering and replying to a message with weak encryption.
   The guidance in Section 6.2.2.1 should be followed when replying to a
   message with weak encryption as well.

   A receiving MUA MAY also treat historically archived messages with
   weak encryption differently from modern messages.  For example, if an
   encryption algorithm was known to be weak in 2005, then a message
   that appears to have been encrypted with that algorithm in 1995 might
   decrypted with a warning, as an archival service.  But a message that
   appears to have been encrypted with that same weak algorithm in 2015
   might be quarantined as a likely attack.

   There are several possible ways to distinguish a historical message
   from a modern one, including:

   *  The message timestamp (e.g., the Date header field)

   *  The time the message was first observed on the network (e.g.,
      delivery of a new message via IMAP from a mailbox that had
      recently checked)

   *  The timestamp in any signature observed in the message





Gillmor, et al.           Expires 12 July 2025                 [Page 29]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  The message structure (a message composed using protocol elements
      that were invented after the encryption algorithm was known weak
      is likely to be an attack than a legitimate archival message)

7.  Reasoning about Message Parts

   When generating or rendering messages, it is useful to know what
   parts of the message are likely to be displayed, and how.  This
   section introduces some common terms that can be applied to parts
   within the Cryptographic Payload.

7.1.  Main Body Part

   When an e-mail message is composed or rendered to the user there is
   typically one main view that presents a (mostly textual) part of the
   message.

   While the message itself may be constructed of several distinct MIME
   parts in a tree, the part that is rendered to the user is the "Main
   Body Part".

   When rendering a message, one of the primary jobs of the receiving
   MUA is identifying which part (or parts) is the Main Body Part.
   Typically, this is found by traversing the MIME tree of the message
   looking for a leaf node that has a primary content type of text
   (e.g., text/plain or text/html) and is not Content-Disposition:
   attachment.

   MIME tree traversal follows the first child of every multipart node,
   with the exception of multipart/alternative.  When traversing a
   multipart/alternative node, all children should be scanned, with
   preference given to the last child node with a MIME type that the MUA
   is capable of rendering directly.

   An MUA MAY offer the user a mechanism to prefer a particular MIME
   type within multipart/alternative instead of the last renderable
   child.  For example, a user may explicitly prefer a text/plain
   alternative part over text/html.  Note that due to uncertainty about
   the capabilities and configuration of the receiving MUA, a conformant
   composing MUA should consider that multiple parts might be rendered
   as the Main Body Part when the message is ultimately viewed.  In
   particular, the composing MUA should ensure that any part likely to
   be viewed as the Main Body Part has the same semantic content as any
   other such part.

   When composing a message, an originating MUA operating on behalf of
   an active user can identify which part (or parts) are the "main"
   parts: these are the parts the MUA generates from the user's editor.



Gillmor, et al.           Expires 12 July 2025                 [Page 30]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Tooling that automatically generates e-mail messages should also have
   a reasonable estimate of which part (or parts) are the "main" parts,
   as they can be programmatically identified by the message author.

   For a filtering program that attempts to transform an outbound
   message without any special knowledge about which parts are Main Body
   Parts, it can identify the likely parts by following the same routine
   as a receiving MUA.

7.2.  Attachments

   A message may contain one or more separated MIME parts that are
   intended for download or extraction.  Such a part is commonly called
   an "attachment", and is commonly identified by having Content-
   Disposition: attachment.

   An MUA MAY identify a subpart as an attachment, or permit extraction
   of a subpart even when the subpart does not have Content-Disposition:
   attachment.

   When generating a message with end-to-end cryptographic protection,
   any attachment MUST be included within the Cryptographic Payload.  If
   an attachment is found outside the Cryptographic Payload, then the
   message is not well-formed (see Section 6.1), and will not be handled
   by other MUAs as intended.

   Some MUAs have tried to compose messages where each attachment is
   placed in its own cryptographic envelope.  Such a message is
   problematic for several reasons:

   *  The attachments can be stripped, replaced, or reordered without
      breaking any cryptographic integrity mechanism.

   *  The resulting message may have a mix of cryptographic statuses
      (e.g., if a signature on one part fails but another succeeds, or
      if one part is encrypted and another is not).  This mix of
      statuses is difficult to represent to the user in a comprehensible
      way.

   *  The divisions between the different attachments are visible to
      operators of any mail transport agent (MTA) that handles the
      message, potentially resulting in a metadata leak.  For example,
      the MTA operator may learn the number of attachments, and the size
      of each attachment.

   These messages are unlikely to be usefully interoperable without
   additional standardization work (see Appendix A.12).




Gillmor, et al.           Expires 12 July 2025                 [Page 31]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


7.3.  MIME Part Examples

   Consider a common message with the following MIME structure:

   M └─╴application/pkcs7-mime
      ↧ (decrypts to)
   N  └─╴application/pkcs7-mime
       ⇩ (unwraps to)
   O   └┬╴multipart/mixed
   P    ├┬╴multipart/alternative
   Q    │├─╴text/plain
   R    │└─╴text/html
   S    └─╴image/png

   Parts M and N comprise the Cryptographic Envelope.

   Parts Q and R are both Main Body Parts.

   If part S is Content-Disposition: attachment, then it is an
   attachment.  If part S has no Content-Disposition header, it is
   potentially ambiguous whether it is an attachment or not.  If the
   sender prefers a specific behavior, it should explicitly set the
   Content-Disposition header on part S to either inline or attachment
   as guidance to the receiving MUA.

   Consider also this alternate structure:

   M └─╴application/pkcs7-mime
      ↧ (decrypts to)
   N  └─╴application/pkcs7-mime
       ⇩ (unwraps to)
   O   └┬╴multipart/alternative
   P    ├─╴text/plain
   Q    └┬╴multipart/related
   R     ├─╴text/html
   S     └─╴image/png

   In this case, parts M and N still comprise the Cryptographic
   Envelope.

   Parts P and R (the first two leaf nodes within each subtree of part
   O) are the Main Body Parts.

   Part S is more likely not to be an attachment, as the subtree layout
   suggests that it is only relevant for the HTML version of the
   message.  For example, it might be rendered as an image within the
   HTML alternative.




Gillmor, et al.           Expires 12 July 2025                 [Page 32]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


8.  Certificate Management

   A cryptographically-capable MUA typically maintains knowledge about
   certificates for the user's own account(s), as well as certificates
   for the peers that it communicates with.

8.1.  Peer Certificates

   Most certificates that a cryptographically-capable MUA will use will
   be certificates belonging to the parties that the user communicates
   with through the MUA.  This section discusses how to manage the
   certificates that belong to such a peer.

   The MUA will need to be able to discover X.509 certificates for each
   peer, cache them, and select among them when composing an encrypted
   message.

   Detailed guidance about how to do this is beyond the scope of this
   document, but future revisions may bring it into scope (see
   Appendix A.3).

8.1.1.  Peer Certificate Selection

   When composing an encrypted message, the MUA needs to select an
   encryption-capable certificate for each recipient.

   To select such a certificate for a given destination e-mail address,
   the MUA should look through all of its known certificates and verify
   that _all_ of the conditions below are met:

   *  The certificate must be valid, not expired or revoked.

   *  It must have a subjectAltName of type rfc822Name whose contents
      match the destination e-mail address.  In particular, the local-
      part of the two addresses should be an exact bytewise match, and
      the domain parts of the two addresses should be matched by
      ensuring label equivalence across the full domain name, as
      described in Section 2.3.2.4 of [RFC5890].

   *  The algorithm OID in the certificate's SPKI is known to the MUA
      and capable of encryption.  Examples include:

      -  rsaEncryption (OID 1.2.840.113549.1.1.1), with keyUsage (OID
         2.5.29.15) extension present and the "key encipherment" bit
         (value 32) set.

      -  curveX25519 (OID 1.3.101.110) with keyUsage extension present
         and the "key agreement" bit (value 8) set.



Gillmor, et al.           Expires 12 July 2025                 [Page 33]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  If extendedKeyUsage (OID 2.5.29.37) is present, it contains at
      least one of the following OIDs: e-mail protection (OID
      1.3.6.1.5.5.7.3.4), anyExtendedKeyUsage (OID 2.5.29.37.0).

   A conformant MUA may include more considerations when selecting a
   peer certificate as well, see Appendix A.3.4 for examples.

8.2.  Local Certificates

   The MUA also needs to know about one or more certificates associated
   with the user's e-mail account.  It is typically expected to have
   access to the secret key material associated with the public keys in
   those certificates.

   While some basic guidance is offered here, it is beyond the scope of
   this document to describe all possible relevant guidance for local
   certificate and key material handling.  See Appendix A.4 for
   suggestions of guidance that a future version might bring into scope.

8.2.1.  Getting Certificates for the User

   If a conformant MUA does not have any certificate or secret key for
   the user, it should help the user to generate, acquire, or import
   them with a minimum of difficulty.

8.2.1.1.  User Certificates for S/MIME

   For S/MIME, the user SHOULD have both a signing-capable certificate
   and an encryption-capable certificate (and the corresponding secret
   keys).  Using the same cryptographic key material for multiple
   algorithms (i.e., for both encryption and signing) has been the
   source of vulnerabilities in other (non-e-mail) contexts (e.g.,
   [DROWN] and [IKE]).  The simplest way to avoid any comparable risk is
   to use distinct key material for each cryptographic algorithm.  A
   conformant MUA that generates S/MIME certificates for the user MUST
   generate distinct S/MIME certificates: one for encryption and another
   for signing, to avoid possible cross-protocol key misuse.

   The simplest option for an S/MIME-capable MUA is for the MUA to
   permit the user to import a PKCS #12 ([RFC7292]) object that is
   expected to contain secret key material, end entity certificates for
   the user, and intermediate certification authority certificates that
   permit chaining from the end entity certs to widely-accepted trust
   anchors.  A conformant MUA that imports such a PKCS #12 bundle SHOULD
   warn the user if the bundle contains an S/MIME certificate and
   corresponding secret key where the same secret key is used for both
   encryption and signing.




Gillmor, et al.           Expires 12 July 2025                 [Page 34]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   An S/MIME-capable MUA that has access to user certificates and their
   corresponding secret key material should also offer the ability to
   export those objects into a well-formed PKCS #12 object that could be
   imported into another MUA operated by the same user.

   Manual handling of PKCS #12 objects is challenging for most users.
   Producing the initial PKCS #12 object typically can only be done with
   the aid of a certification authority via non-standardized, labor-
   intensive, and error-prone procedures that most users do not
   understand.  Furthermore, manual export and import incurs ongoing
   labor (for example, before certificate expiration) by the user which
   most users are unprepared to do (see Section 8.2.2).

   A better approach is for the MUA to integrate some form of automated
   certificate issuance procedure, for example, by using the ACME
   protocol for end user S/MIME certificates ([RFC8823]).

   Another possible approach is integration with a cryptographic
   hardware token or smartcard that can provide certificates and permit
   the use of isolated secret key material, for example [PKCS11], though
   this approach delegates the complexity of acquiring and managing
   certificates to management of the hardware token itself (see
   Appendix A.4.2).

   See also [I-D.woodhouse-cert-best-practice] for more recommendations
   about managing user certificates.

8.2.1.2.  User Certificates for PGP/MIME

   As distinct from S/MIME, OpenPGP ([RFC9580]) has a different set of
   common practices.  For one thing, a single OpenPGP certificate can
   contain both a signing-capable key and a distinct encryption-capable
   key, so only one certificate is needed for an e-mail user of OpenPGP,
   as long as the certificate has distinct key material for the
   different purposes.

   Furthermore, a single OpenPGP certificate MAY be only self-signed, so
   the MUA can generate such a certificate entirely on its own.

   An OpenPGP-capable MUA should have the ability to import and export
   OpenPGP Tranferable Secret Keys (see Section 10.2 of [RFC9580]), to
   enable manual transfer of user certificates and secret key material
   between multiple MUAs controlled by the user.

   Since an OpenPGP certificate MAY be certified by third parties
   (whether formal certification authorities or merely other well-
   connected peers) the MUA SHOULD offer affordances to help the user
   acquire and merge third party certifications on their certificate.



Gillmor, et al.           Expires 12 July 2025                 [Page 35]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   When doing this, the MUA should prioritize third-party certifications
   from entities that the user's peers are likely to know about and be
   willing to rely on.

   Since an OpenPGP certificate can grow arbitrarily large with third-
   party certifications, the MUA should assist the user in pruning it to
   ensure that it remains a reasonable size when transmitting it to
   other parties.

8.2.1.3.  Generate Secret Key Material Locally

   Regardless of protocol used (S/MIME or PGP), when producing
   certificates for the end user, the MUA SHOULD ensure that it has
   generated secret key material locally, and MUST NOT accept secret key
   material from an untrusted external party as the basis for the user's
   certificate.  For example, a user who trusts their system
   administrator not to compromise their MUA may accept secret key
   material generated by the sysadmin, but probably should not accept
   secret key material generated by an unaffiliated online web service.

   An MUA that accepts secret key material from a third party cannot
   prevent that third party from retaining this material.  A third party
   with this level of access could decrypt messages intended to be
   confidential for the user, or could forge messages that would appear
   to come from the user.

8.2.2.  Local Certificate Maintenance

   In the context of a single e-mail account managed by an MUA, where
   that e-mail account is expected to be able to use end-to-end
   cryptographic protections, the MUA SHOULD warn the user (or
   proactively fix the problem) when/if:

   *  For S/MIME, the user's own certificate set for the account does
      not include a valid, unexpired encryption-capable X.509
      certificate, and a valid, unexpired signature-capable X.509
      certificate.

   *  For PGP/MIME, the user's own certificate does not include a valid,
      unexpired signing-capable key/subkey and a valid, unexpired
      encryption-capable key/subkey.

   *  Any of the user's own certificates for the account:

      -  is due to expire in the next month (or at some other reasonable
         cadence).





Gillmor, et al.           Expires 12 July 2025                 [Page 36]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


      -  not match the e-mail address associated with the account in
         question.

   *  Any of the user's own S/MIME certificates for the account:

      -  does not have a keyUsage extension.

      -  does not contain an extendedKeyUsage extension.

      -  would be considered invalid by the MUA for any other reason if
         it were a peer certificate.

   An MUA that takes active steps to fix any of these problems before
   they arise is even more usable than just warning, but guidance on how
   to do active certificate maintenance is beyond scope for this current
   document (see Appendix A.4.3).

   If the MUA does find any of these issues and chooses to warn the
   user, it should use one aggregate warning with simple language that
   the certificates might not be acceptable for other people, and
   recommend a course of action that the user can take to remedy the
   problem.

8.2.3.  Shipping Certificates in Outbound Messages

   When sending mail, a conformant MUA SHOULD include copies of the
   user's own certificates (and potentially other certificates) in each
   message to facilitate future communication, unless it has specific
   knowledge that the other parties involved already know the relevant
   keys (for example, if it is mail between members within a domain that
   has a synchronized and up-to-date certificate directory).

   The mechanism for including these certificates, and which
   certificates to include in the message, are protocol specific.

8.2.3.1.  Shipping Certificates in S/MIME Messages

   In any S/MIME SignedData object, certificates can be shipped in the
   "certificates" member.  In S/MIME EnvelopedData object, certificates
   can be shipped in the "originatorInfo.certs" member.

   When a single S/MIME-protected e-mail message is encrypted and
   signed, it is usually sufficient to ship all the relevant
   certificates in the inner SignedData object's "certificates" member.

   The S/MIME certificates shipped in such a message SHOULD include:





Gillmor, et al.           Expires 12 July 2025                 [Page 37]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  The user's own S/MIME signing certificate, so that signature on
      the current message can be validated.

   *  The user's own S/MIME encryption-capable certificate, so that the
      recipient can reply in encrypted form.

   *  On an encrypted message to multiple recipients, the encryption-
      capable peer certificates of the other recipients, so that any
      recipient can easily "reply all" without needing to search for
      certificates.

   *  Any intermediate CA certificates needed to chain all of the above
      to a widely-trusted set of root authorities.

8.2.3.2.  Shipping Certificates in PGP/MIME Messages

   PGP/MIME does not have a single specific standard location for
   shipping certificates.

   Some MUAs ship relevant OpenPGP certificates in a single MIME leaf of
   Content-Type "application/pgp-keys".  When such a message has
   cryptographic protections, to ensure that the message is well-formed,
   this kind of MIME part SHOULD be a leaf of the Cryptographic Payload,
   and not outside of it.  One problem with this approach is that it
   appears to recipients with non-cryptographic MUAs as an "attachment",
   which can lead to confusion if the user does not know how to use it.

   Other implementations ship relevant OpenPGP certificates in
   "Autocrypt" or "Autocrypt-Gossip" message header fields (see
   [AUTOCRYPT]).  To ensure that those header fields receive the same
   cryptographic authenticity as the rest of the message, these header
   fields SHOULD be protected as described in
   [I-D.ietf-lamps-header-protection].

   The OpenPGP certificates shipped in such a message SHOULD include:

   *  The user's own OpenPGP certificate, capable of both signing and
      encryption, so that the user can validate the message's signature
      and can encrypt future messages

   *  On an encrypted message to multiple recipients, the OpenPGP
      certificates of the other recipients, so that any recipient can
      easily "reply all" without needing to search for certificates.

9.  Common Pitfalls and Guidelines

   This section highlights a few "pitfalls" and guidelines based on
   these discussions and lessons learned.



Gillmor, et al.           Expires 12 July 2025                 [Page 38]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


9.1.  Reading Sent Messages

   When sending a message, a typical MUA will store a copy of the
   message sent in sender's Sent mail folder so that the sender can read
   it later.  If the message is an encrypted message, storing it
   encrypted requires some forethought to ensure that the sender can
   read it in the future.

   It is a common and simple practice to encrypt the message not only to
   the recipients of the message, but also to the sender.  One advantage
   of doing this is that the message that is sent on the wire can be
   identical to the message stored in the sender's Sent mail folder.
   This allows the sender to review and re-read the message even though
   it was encrypted.

   There are at least three other approaches that are possible to ensure
   future readability by the sender of the message, but with different
   tradeoffs:

   *  Encrypt two versions of the message: one to the recipients (this
      version is sent on the wire), and one to the sender only (this
      version is stored in the sender's Sent folder).  This approach
      means that the message stored in the Sent folder is not byte-for-
      byte identical to the message sent to the recipients.  In the
      event that message delivery has a transient failure, the MUA
      cannot simply re-submit the stored message into the SMTP system
      and expect it to be readable by the recipient.

   *  Store a cleartext version of the message in the Sent folder.  This
      presents a risk of information leakage: anyone with access to the
      Sent folder can read the contents of the message.  Furthermore,
      any attempt to re-send the message needs to also re-apply the
      cryptographic transformation before sending, or else the message
      contents will leak upon re-send.  A conformant MUA SHOULD NOT
      store a cleartext copy in the Sent folder unless it knows that the
      Sent folder cannot be read by an attacker.  For example, if end-
      to-end confidentiality is desired, then storing the cleartext in
      an IMAP folder where a potentially adversarial server can read it
      defeats the purpose.

   *  A final option is that the MUA can store a copy of the message's
      encryption session key.  Standard e-mail encryption mechanisms
      (e.g., S/MIME and PGP/MIME) are hybrid mechanisms: the asymmetric
      encryption steps simply encrypt a symmetric "session key", which
      is used to encrypt the message itself.  If the MUA stores the
      session key itself, it can use the session key to decrypt the Sent
      message without needing the Sent message to be decryptable by the
      user's own asymmetric key.  An MUA doing this must take care to



Gillmor, et al.           Expires 12 July 2025                 [Page 39]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


      store (and backup) its stash of session keys, because if it loses
      them it will not be able to read the sent messages; and if someone
      else gains access to them, they can decrypt the sent messages.
      This has the additional consequence that any other MUA accessing
      the same Sent folder cannot decrypt the message unless it also has
      access to the stashed session key.

9.2.  Reading Encrypted Messages after Certificate Expiration

   When encrypting a message, the sending MUA should decline to encrypt
   to an expired certificate (see Section 8.1.1).  But when decrypting a
   message, as long as the viewing MUA has access to the appropriate
   secret key material, it should permit decryption of the message, even
   if the associated certificate is expired.  That is, the viewing MUA
   should not prevent the user from reading a message that they have
   already received.

   The viewing MUA may warn the user when decrypting a message that
   appears to have been encrypted to an encryption-capable certificate
   that was expired at the time of encryption (e.g., based on the Date:
   header field of the message, or the timestamp in the cryptographic
   signature), but otherwise should not complain.

   The primary goal of certificate expiration is to facilitate rotation
   of secret key material, so that secret key material does not need to
   be retained indefinitely.  Certificate expiration permits the user to
   destroy an older secret key if access to the messages received under
   it is no longer necessary (see also Appendix A.10).

9.3.  Unprotected Message Header Fields

   Many legacy cryptographically-aware MUAs only apply cryptographic
   protections to the body of the message, but leave the header fields
   unprotected.  This gives rise to vulnerabilities like information
   leakage (e.g., the Subject line is visible to a passive intermediary)
   or message tampering (e.g., the Subject line is replaced, effectively
   changing the semantics of a signed message).  These are not only
   security vulnerabilities, but usability problems, because the
   distinction between what is a header and what is the body of a
   message is unclear to many end users, and requires a more complex
   mental model than is necessary.  Useful security comes from alignment
   between simple mental models and tooling.

   To avoid these concerns, a conformant MUA MUST implement header
   protection as described in [I-D.ietf-lamps-header-protection].






Gillmor, et al.           Expires 12 July 2025                 [Page 40]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Note that some message header fields, like List-*, Archived-At, and
   Resent-* are typically added by an intervening MUA (see Section 9.8),
   not by one of the traditional "ends" of an end-to-end e-mail
   exchange.  A receiving MUA may choose to consider the contents of
   these header fields on an end-to-end protected message as markers
   added during message transit, even if they are not covered by the
   end-to-end cryptographic protection.

9.4.  Composing an Encrypted Message with Bcc

   When composing an encrypted message containing at least one recipient
   address in the Bcc header field, there is a risk that the encrypted
   message itself could leak information about the actual recipients,
   even if the Bcc header field does not mention the recipient.  For
   example, if the message clearly indicates which certificates it is
   encrypted to, the set of certificates can identify the recipients
   even if they are not named in the message header fields.

   Because of these complexities, there are several interacting factors
   that need to be taken into account when composing an encrypted
   message with Bcc'ed recipients.

   *  Section 3.6.3 of [RFC5322] describes a set of choices about
      whether (and how) to populate the Bcc field explicitly on Bcc'ed
      copies of the message, and in the copy stored in the sender's Sent
      folder.

   *  When separate copies are made for Bcced recipients, should each
      separate copy _also_ be encrypted to the named recipients, or just
      to the designated Bcc recipient?

   *  When a copy is stored in the Sent folder, should that copy also be
      encrypted to Bcced recipients? (see also Section 9.1)

   *  When a message is encrypted, if there is a mechanism to include
      the certificates of the recipients, whose certificates should be
      included?

9.4.1.  Simple Encryption with Bcc

   Here is a simple approach that tries to minimize the total number of
   variants of the message created while leaving a coherent view of the
   message itself:

   *  No cryptographic payload contains any Bcc header field.






Gillmor, et al.           Expires 12 July 2025                 [Page 41]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  The main copy of the message is signed and encrypted to all named
      recipients and to the sender.  A copy of this message is also
      stored in the sender's Sent folder.

   *  Each Bcc recipient receives a distinct copy of the message, with
      an identical cryptographic payload, and the message is signed and
      encrypted to that specific recipient and all the named recipients.
      These copies are not stored in the sender's Sent folder.

   *  Any Bcc'ed recipient MUST NOT be taken into consideration when
      determining which certificates to include in the message.  In
      particular, certificates for Bcc'ed recipients MUST NOT included
      in any message.

9.4.1.1.  Rationale

   The approach described in Section 9.4.1 aligns the list of
   cryptographic recipients as closely as possible with the set of named
   recipients, while still allowing a Bcced recipient to read their own
   copy, and to "Reply All" should they want to.

   This should reduce user confusion on the receiving side: a recipient
   of such a message who naively looks at the user-facing header fields
   from their own mailbox will have a good sense of what cryptographic
   treatments have been applied to the message.  It also simplifies
   message composition and user experience: the message composer sees
   fields that match their expectations about what will happen to the
   message.  Additionally, it may preserve the ability for a Bcc'ed
   recipient to retain their anonymity, should they need to offer the
   signed cryptographic payload to an outside party as proof of the
   original sender's intent without revealing their own identity.

9.5.  Draft Messages

   When composing a message, most MUAs will save a copy of the as-yet-
   unsent message to a "Drafts" folder.  If that folder is itself stored
   somewhere not under the user's control (e.g., an IMAP mailbox), it
   would be a mistake to store the draft message in the clear, because
   its contents could leak.

   This is the case even if the message is ultimately sent deliberately
   in the clear.  During message composition, the MUA does not know
   whether the message is intended to be sent encrypted or not.  For
   example, just before sending, the sender could decide to encrypt the
   message, and the MUA would have had no way of knowing.






Gillmor, et al.           Expires 12 July 2025                 [Page 42]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   The MUA SHOULD encrypt all draft messages, unless it has explicit
   knowledge that the message will not be encrypted when sent, or that
   the Drafts folder cannot be read by an attacker.  For example, if
   end-to-end confidentiality is desired, then storing a cleartext draft
   in an IMAP folder where a potentially adversarial server can read it
   defeats the purpose.

   Furthermore, when encrypting a draft message, the message draft MUST
   only be encrypted to the user's own certificate, or to some
   equivalent secret key that only the user possesses.  A draft message
   encrypted in this way can be decrypted when the user wants to resume
   composing the message, but cannot be read by anyone else, including a
   potential intended recipient.  Note that a draft message encrypted in
   this way will only be resumable by another MUA attached to the same
   mailbox if that other MUA has access to the user's decryption-capable
   secret key.  This shared access to key material is also likely
   necessary for useful interoperability, but is beyond the scope of
   this document (see Appendix A.4.1).

   A conformant MUA MUST NOT sign a message draft with the user's normal
   signing key.  If draft signing is intended for cryptographic
   coordination between multiple MUAs of the same user, it should be
   negotiated with a different key (but see Appendix A.4.1).

   The message should only be encrypted to its recipients upon actually
   sending the message.  No reasonable user expects their message's
   intended recipients to be able to read a message that is not yet
   complete.

9.6.  Composing a Message to Heterogeneous Recipients

   When sending a message that the user intends to be encrypted, it's
   possible that some recipients will be unable to receive an encrypted
   copy.  For example, when Carol composes a message to Alice and Bob,
   Carol's MUA may be able to find a valid encryption-capable
   certificate for Alice, but none for Bob.

   In this situation, there are four possible strategies, each of which
   has a negative impact on the experience of using encrypted mail.
   Carol's MUA can:

   1.  send encrypted to Alice and Bob, knowing that Bob will be unable
       to read the message.

   2.  send encrypted to Alice only, dropping Bob from the message
       recipient list.

   3.  send the message in the clear to both Alice and Bob.



Gillmor, et al.           Expires 12 July 2025                 [Page 43]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   4.  send an encrypted copy of the message to Alice, and a cleartext
       copy to Bob.

   Each of these strategies has different drawbacks.

   The problem with approach 1 is that Bob will receive unreadable mail.

   The problem with approach 2 is that Carol's MUA will not send the
   message to Bob, despite Carol asking it to.

   The problem with approach 3 is that Carol's MUA will not encrypt the
   message, despite Carol asking it to.

   Approach 4 has two problems:

   *  Carol's MUA will release a cleartext copy of the message, despite
      Carol asking it to send the message encrypted.

   *  If Alice wants to "reply all" to the message, she may not be able
      to find an encryption-capable certificate for Bob either.  This
      puts Alice in an awkward and confusing position, one that users
      are unlikely to understand.  In particular, if Alice's MUA is
      following the guidance about replies to encrypted messages in
      Section 5.4, having received an encrypted copy will make Alice's
      Reply buffer behave in an unusual fashion.

   This is particularly problematic when the second recipient is not
   "Bob" but in fact a public mailing list or other visible archive,
   where messages are simply never encrypted.

   Carol is unlikely to understand the subtleties and negative
   downstream interactions involved with approaches 1 and 4, so
   presenting the user with those choices is not advised.

   The most understandable approach for an MUA with an active user is to
   ask the user (when they hit "send") to choose between approach 2 and
   approach 3.  If the user declines to choose between 2 and 3, the MUA
   can drop them back to their message composition window and let them
   make alternate adjustments.

   See also further discussion of these scenarios in
   [I-D.dkg-mail-cleartext-copy].









Gillmor, et al.           Expires 12 July 2025                 [Page 44]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


9.7.  Message Transport Protocol Proxy: A Dangerous Implementation
      Choice

   An implementer of end-to-end cryptographic protections may be tempted
   by a simple software design that piggybacks off of a mail protocol
   like SMTP Submission ([RFC6409]), IMAP ([RFC9051]), or JMAP
   ([RFC8621]) to handle message assembly and interpretation.  In such
   an architecture, a naive MUA speaks something like a "standard"
   protocol like SMTP, IMAP, or JMAP to a local proxy, and the proxy
   handles signing and encryption (outbound), and decryption and
   verification (inbound) internally on behalf of the user.  While such
   a "pluggable" architecture has the advantage that it is likely to be
   easy to apply to any mail user agent, it is problematic for the goals
   of end-to-end communication, especially in an existing cleartext
   ecosystem like e-mail, where any given message might be unsigned or
   signed, cleartext or encrypted.  In particular:

   *  the user cannot easily and safely identify what protections any
      particular message has (including messages currently being
      composed), and

   *  the proxy itself is unaware of subtle nuances about the message
      that the MUA actually knows.

   With a trustworthy and well-synchronized sidechannel or protocol
   extension between the MUA and the proxy, it is possible to deploy
   such an implementation safely, but the requirement for the
   sidechannel or extension eliminates the universal-deployability
   advantage of the scheme.

   Similar concerns apply to any implementation bound by an API which
   operates on message objects alone, without any additional contextual
   parameters.

   This section attempts to document some of the inherent risks involved
   with such an architecture.

9.7.1.  Dangers of a Submission Proxy for Message Composition

   When composing and sending a message, the act of applying
   cryptographic protections has subtleties that cannot be directly
   expressed in the SMTP protocol used by Submission [RFC6409], or in
   any other simple protocol that hands off a cleartext message for
   further processing.







Gillmor, et al.           Expires 12 July 2025                 [Page 45]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   For example, the sender cannot indicate via SMTP whether or not a
   given message _should_ be encrypted (some messages, like those sent
   to a publicly archived mailing list, are pointless to encrypt), or
   select among multiple certificates for a recipient, if they exist
   (see Section 8.1.1).

   Likewise, because such a proxy only interacts with the message when
   it is ready to be sent, it cannot indicate back to the user _during
   message composition_ whether or not the message is able to be
   encrypted (that is, whether a valid certificate is available for each
   intended recipient).  A message author may write an entirely
   different message if they know that it will be protected end-to-end;
   but without this knowledge, the author is obliged either to write
   text that they presume will be intercepted, or to risk revealing
   sensitive content.

   Even without encryption, deciding whether to sign or not (and which
   certificate to sign with, if more than one exists) is another choice
   that the proxy is ill-equipped to make.  The common message-signing
   techniques either render a message unreadable by any non-
   cryptographic MUA (i.e., PKCS7 signed-data), or appear as an
   attachment that can cause confusion to a naive recipient using a non-
   cryptographic MUA (i.e., multipart/signed).  If the sender knows that
   the recipient will not check signatures, they may prefer to leave a
   cleartext message without a cryptographic signature at all.

   Furthermore, handling encryption properly depends on the context of
   any given message, which cannot be expressed by the MUA to the
   Submission proxy.  For example, decisions about how to handle
   encryption and quoted or attributed text may depend on the
   cryptographic status of the message that is being replied to (see
   Section 5.4).

   Additionally, such a proxy would need to be capable of managing the
   user's own key and certificate (see Section 8.2).  How will the
   implementation indicate to the user when their own certificate is
   near expiry, for example?  How will any other error conditions be
   handled when communication with the user is needed?

   While an extension to SMTP might be able to express all the necessary
   semantics that would allow a generic MUA to compose messages with
   standard cryptographic protections via a proxy, such an extension is
   beyond the scope of this document.  See
   [I-D.ietf-jmap-smime-sender-extensions] for an example of how an MUA
   using a proxy protocol might indicate signing and encryption
   instructions to its proxy.





Gillmor, et al.           Expires 12 July 2025                 [Page 46]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


9.7.2.  Dangers of an IMAP Proxy for Message Rendering

   When receiving and rendering a message, the process of indicating to
   the user the cryptographic status of a message requires subtleties
   that are difficult to offer from a straightforwad IMAP (or POP
   [RFC1939], or JMAP) proxy.

   One approach such a proxy could take is to remove all the
   Cryptographic Layers from a well-formed message, and to package a
   description of those layers into a special header field that the MUA
   can read.  But this merely raises the question: what semantics need
   to be represented?  For example:

   *  Was the message signed?  If so, by whom?  When?

   *  Should the details of the cryptographic algorithms used in any
      signatures found be indicated as well?

   *  Was the message encrypted?  if so, to whom?  What key was used to
      decrypt it?

   *  If both signed and encrypted, was the signing outside the
      encryption or inside?

   *  How should errant Cryptographic Layers (see Section 4.5) be dealt
      with?

   *  What cryptographic protections do the header fields of the message
      have? (see [I-D.ietf-lamps-header-protection])

   *  How are any errors or surprises communicated to the user?

   If the proxy passes any of this cryptographic status to the client in
   an added header field, it must also ensure that no such header field
   is present on the messages it receives before processing it.  If it
   were to allow such a header field through unmodified to any client
   that is willing to trust its contents, an attacker could spoof the
   field to make the user believe lies about the cryptographic status of
   the message.  In order for an MUA to be confident in such a header
   field, then, it needs a guarantee from the proxy that any header it
   produces will be safe.  How does the MUA reliably negotiate this
   guarantee with the proxy?  If the proxy can no longer offer this
   guarantee, how will the MUA know that things have changed?

   If such an inbound proxy handles certificate discovery in inbound
   messages (see Appendix A.3.1), it will also need to communicate the
   results of that discovery process to its corresponding outbound proxy
   for message composition (see Section 9.7.1).



Gillmor, et al.           Expires 12 July 2025                 [Page 47]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   While an extension to IMAP (or POP, or JMAP) might be able to express
   all the necessary semantics that would allow a generic MUA to
   indicate standardized cryptographic message status, such an extension
   is beyond the scope of this document.  [RFC9219] describes S/MIME
   signature verification status over JMAP, which is a subset of the
   cryptographic status information described here.

9.7.3.  Who Controls the Proxy?

   Finally, consider that the naive proxy deployment approach is risky
   precisely because of its opacity to the end user.  Such a deployment
   could be placed anywhere in the stack, including on a machine that is
   not ultimately controlled by the end user, making it effectively a
   form of transport protection, rather than end-to-end protection.

   An MUA explicitly under the control of the end user with thoughtful
   integration can offer UI/UX and security guarantees that a simple
   proxy cannot provide.  See also Appendix A.13 for suggestions of
   future work that might augment a proxy to make it safer.

9.8.  Intervening MUAs Do Not Handle End-to-End Cryptographic
      Protections

   Some Mail User Agents (MUAs) will resend a message in identical form
   (or very similar form) to the way that they received it.  For
   example, consider the following use cases:

   *  A mail expander or mailing list that receives a message and re-
      sends it to all subscribers (see also Appendix A.14 for more
      discussion of mailing lists).

   *  An individual user who reintroduces a message they received into
      the mail transport system (see Section 3.6.6 of [RFC5322]).

   *  An automated e-mail intake system that forwards a report to the
      mailboxes of responsible staffers.

   These MUAs intervene in message transport by receiving and then re-
   injecting messages into the mail transport system.  In some cases,
   the original sender or final recipient of a message that has passed
   through such an MUA may be unaware of the intervention.  (Note that
   an MUA that forwards a received message as a attachment (MIME
   subpart) of type message/rfc822 or message/global or "inline" in the
   body of a message is _not_ acting as an intervening MUA in this
   sense, because the forwarded message is encapsulated within a visible
   outer message that is clearly from the MUA itself.)





Gillmor, et al.           Expires 12 July 2025                 [Page 48]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   An intervening MUA should be aware of end-to-end cryptographic
   protections that might already exist on messages that they re-send.
   In particular, it is unclear what the "end-to-end" properties are of
   a message that has been handled by an intervening MUA.  For signed-
   only messages, if the intervening MUA makes any substantive
   modifications to the message as it passes it along, it may break the
   signature from the original sender.  In many cases, breaking the
   original signature is the appropriate result, since the original
   message has been modified, and the original sender has no control
   over the modifications made by the intervening MUA.  For encrypted-
   and-signed messages, if the intervening MUA is capable of decrypting
   the message, it must be careful when re-transmitting the message.
   Will the new recipient be able to decrypt it?  If not, will the
   message be useful to the recipient?  If not, it may not make sense to
   re-send the message.

   Beyond the act of re-sending, an intervening MUA should not itself
   try to apply end-to-end cryptographic protections on a message that
   it is resending unless directed otherwise by some future
   specification.  Additional layers of cryptographic protection added
   in an ad-hoc way by an intervening MUA are more likely to confuse the
   recipient and will not be interpretable as end-to-end protections as
   they do not originate with the original sender of the message.

9.9.  External Subresources in MIME Parts Break Cryptographic
      Protections

   A MIME part with a content type that can refer to external resources
   (like text/html) may itself have some sort of end-to-end
   cryptographic protections.  However, retrieving or rendering these
   external resources may violate the properties that users expect from
   cryptographic protection.

   As a baseline, retrieving the external resource at the time a message
   is read can be used as a "web bug", leaking the activity and network
   location of the receiving user to the server hosting the external
   resource.  This privacy risk is present, of course, even for messages
   with no cryptographic protections, but may be even more surprising to
   users who are shown some level of security indicator about a given
   message.

   Other problems with external resources are more specifically bound to
   cryptographic protections.

   For example, an signed e-mail message with at text/html part that
   refers to an external image (i.e., via <img src="https://example.com/
   img.png">) may render differently if the hosting webserver decides to
   serve different content at the source URL for the image.  This



Gillmor, et al.           Expires 12 July 2025                 [Page 49]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   effectively breaks the goals of integrity and authenticity that the
   user should be able to rely on for signed messages, unless the
   external subresource has strict integrity guarantees (e.g., via
   [SRI]).

   Likewise, fetching an external subresource for an encrypted-and-
   signed message effectively breaks goals of privacy and
   confidentiality for the user.

   This is loosely analogous to security indicator problems that arose
   for web browsers as described in [mixed-content].  However, while
   fetching the external subresource over https is sufficient to avoid a
   "mixed content" warning from most browsers, it is insufficicent for
   an MUA that wants to offer its users true end-to-end guarantees for
   e-mail messages.

   A conformant sending MUA that applies signing-only cryptographic
   protection to a new e-mail message with an external subresource
   should take one of the following options:

   *  pre-fetch the external subresource and include it in the message
      itself,

   *  use a strong integrity mechanism like Subresource Integrity
      ([SRI]) to guarantee the content of the subresource (though this
      does not fix the "web bug" privacy risk described above), or

   *  prompt the composing user to remove the subresource from the
      message.

   A conformant sending MUA that applies encryption to a new e-mail
   message with an external resource cannot depend on subresource
   integrity to protect the privacy and confidentiality of the message,
   so it should either pre-fetch the external resource to include it in
   the message, or prompt the composing user to remove it before
   sending.

   A conformant receiving MUA that encounters a message with end-to-end
   cryptographic protections that contain a subresource MUST either
   refuse to retrieve and render the external subresource, or it should
   decline to treat the message as having cryptographic protections.
   For example, it could indicate in the Cryptographic Summary that the
   message is Unprotected.

   Note that when composing a message reply with quoted text from the
   original message, if the original message did contain an external
   resource, the composing MUA SHOULD NOT fetch the external resource
   solely to include it in the reply message, as doing so would trigger



Gillmor, et al.           Expires 12 July 2025                 [Page 50]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   the "web bug" at reply composition time.  Instead, the safest way to
   deal with quoted text that contains an external resource in an end-
   to-end encrypted reply is to strip any reference to the external
   resource during initial composition of the reply.

10.  IANA Considerations

   This document does not require anything from IANA.

11.  Security Considerations

   This entire document addresses security considerations about end-to-
   end cryptographic protections for e-mail messages.

12.  Acknowledgements

   The set of constructs and recommendations in this document are
   derived from discussions with many different implementers, including
   Bjarni Rúnar Einarsson, Daniel Huigens, David Bremner, Deb Cooley,
   Eliot Lear, Fabian Ising, Heiko Schaefer, Holger Krekel, Jameson
   Rollins, John Levine, Jonathan Hammell, juga, Patrick Brunschwig,
   Paul Kyzivat, Pete Resnick, Roman Danyliw, Santosh Chokhani, Stephen
   Farrell, Thore Göbel, and Vincent Breitmoser.

13.  References

13.1.  Normative References

   [I-D.ietf-lamps-header-protection]
              Gillmor, D. K., Hoeneisen, B., and A. Melnikov, "Header
              Protection for Cryptographically Protected E-mail", Work
              in Progress, Internet-Draft, draft-ietf-lamps-header-
              protection-25, 6 January 2025,
              <https://datatracker.ietf.org/doc/html/draft-ietf-lamps-
              header-protection-25>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC3156]  Elkins, M., Del Torto, D., Levien, R., and T. Roessler,
              "MIME Security with OpenPGP", RFC 3156,
              DOI 10.17487/RFC3156, August 2001,
              <https://www.rfc-editor.org/rfc/rfc3156>.






Gillmor, et al.           Expires 12 July 2025                 [Page 51]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   [RFC4289]  Freed, N. and J. Klensin, "Multipurpose Internet Mail
              Extensions (MIME) Part Four: Registration Procedures",
              BCP 13, RFC 4289, DOI 10.17487/RFC4289, December 2005,
              <https://www.rfc-editor.org/rfc/rfc4289>.

   [RFC5890]  Klensin, J., "Internationalized Domain Names for
              Applications (IDNA): Definitions and Document Framework",
              RFC 5890, DOI 10.17487/RFC5890, August 2010,
              <https://www.rfc-editor.org/rfc/rfc5890>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC8551]  Schaad, J., Ramsdell, B., and S. Turner, "Secure/
              Multipurpose Internet Mail Extensions (S/MIME) Version 4.0
              Message Specification", RFC 8551, DOI 10.17487/RFC8551,
              April 2019, <https://www.rfc-editor.org/rfc/rfc8551>.

13.2.  Informative References

   [AUTOCRYPT]
              Breitmoser, V., Krekel, H., and D. K. Gillmor, "Autocrypt
              - Convenient End-to-End Encryption for E-Mail", July 2018,
              <https://autocrypt.org/>.

   [chrome-indicators]
              Schechter, E., "Evolving Chrome's security indicators",
              May 2018, <https://blog.chromium.org/2018/05/evolving-
              chromes-security-indicators.html>.

   [DROWN]    Aviram, N., Schinzel, S., Somorovsky, J., Heninger, N.,
              Dankel, M., Steube, J., Valenta, L., Adrian, D.,
              Halderman, J. A., Dukhovni, V., Käsper, E., Cohney, S.,
              Engels, S., Paar, C., and Y. Shavitt, "DROWN: Breaking TLS
              using SSLv2", March 2016, <https://drownattack.com/>.

   [EFAIL]    Poddebniak, D., Dresen, C., Müller, J., Ising, F.,
              Schinzel, S., Friedberger, S., Somorovsky, J., and J.
              Schwenk, "Efail: breaking S/MIME and OpenPGP email
              encryption using exfiltration channels", August 2018,
              <https://efail.de>.









Gillmor, et al.           Expires 12 July 2025                 [Page 52]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   [I-D.dkg-mail-cleartext-copy]
              Gillmor, D. K., "Encrypted E-mail with Cleartext Copies",
              Work in Progress, Internet-Draft, draft-dkg-mail-
              cleartext-copy-01, 21 February 2023,
              <https://datatracker.ietf.org/doc/html/draft-dkg-mail-
              cleartext-copy-01>.

   [I-D.ietf-jmap-smime-sender-extensions]
              Melnikov, A., "JMAP extension for S/MIME signing and
              encryption", Work in Progress, Internet-Draft, draft-ietf-
              jmap-smime-sender-extensions-04, 3 August 2023,
              <https://datatracker.ietf.org/doc/html/draft-ietf-jmap-
              smime-sender-extensions-04>.

   [I-D.koch-openpgp-webkey-service]
              Koch, W., "OpenPGP Web Key Directory", Work in Progress,
              Internet-Draft, draft-koch-openpgp-webkey-service-19, 5
              December 2024, <https://datatracker.ietf.org/doc/html/
              draft-koch-openpgp-webkey-service-19>.

   [I-D.woodhouse-cert-best-practice]
              Woodhouse, D. and N. Mavrogiannopoulos, "Recommendations
              for applications using X.509 client certificates", Work in
              Progress, Internet-Draft, draft-woodhouse-cert-best-
              practice-01, 25 July 2023,
              <https://datatracker.ietf.org/doc/html/draft-woodhouse-
              cert-best-practice-01>.

   [I-D.wussler-openpgp-forwarding]
              Wussler, A., "Automatic Forwarding for ECDH Curve25519
              OpenPGP messages", Work in Progress, Internet-Draft,
              draft-wussler-openpgp-forwarding-00, 10 July 2023,
              <https://datatracker.ietf.org/doc/html/draft-wussler-
              openpgp-forwarding-00>.

   [IKE]      Felsch, D., Grothe, M., Schwenk, J., Czubak, A., and M.
              Szymane, "The Dangers of Key Reuse: Practical Attacks on
              IPsec IKE", August 2018,
              <https://www.usenix.org/system/files/conference/
              usenixsecurity18/sec18-felsch.pdf>.

   [mixed-content]
              "Mixed Content", February 2023,
              <https://www.w3.org/TR/mixed-content/>.

   [ORACLE]   Ising, F., Poddebniak, D., Kappert, T., Saatjohann, C.,
              and S. Schinzel, "Content-Type: multipart/oracle Tapping
              into Format Oracles in Email End-to-End Encryption",



Gillmor, et al.           Expires 12 July 2025                 [Page 53]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


              August 2023,
              <https://www.usenix.org/conference/usenixsecurity23/
              presentation/ising>.

   [PKCS11]   Bong, D. and T. Cox, "PKCS", 23 July 2023,
              <https://docs.oasis-open.org/pkcs11/pkcs11-spec/v3.1/os/
              pkcs11-spec-v3.1-os.html>.

   [REPLY]    Müller, J., Brinkmann, M., Poddebniak, D., Schinzel, S.,
              and J. Schwenk, "Re: What’s Up Johnny?: Covert Content
              Attacks on Email End-to-End Encryption", Springer
              International Publishing, Lecture Notes in Computer
              Science pp. 24-42, DOI 10.1007/978-3-030-21568-2_2,
              ISBN ["9783030215675", "9783030215682"], 2019,
              <https://doi.org/10.1007/978-3-030-21568-2_2>.

   [RFC1939]  Myers, J. and M. Rose, "Post Office Protocol - Version 3",
              STD 53, RFC 1939, DOI 10.17487/RFC1939, May 1996,
              <https://www.rfc-editor.org/rfc/rfc1939>.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
              <https://www.rfc-editor.org/rfc/rfc2045>.

   [RFC3207]  Hoffman, P., "SMTP Service Extension for Secure SMTP over
              Transport Layer Security", RFC 3207, DOI 10.17487/RFC3207,
              February 2002, <https://www.rfc-editor.org/rfc/rfc3207>.

   [RFC3274]  Gutmann, P., "Compressed Data Content Type for
              Cryptographic Message Syntax (CMS)", RFC 3274,
              DOI 10.17487/RFC3274, June 2002,
              <https://www.rfc-editor.org/rfc/rfc3274>.

   [RFC3370]  Housley, R., "Cryptographic Message Syntax (CMS)
              Algorithms", RFC 3370, DOI 10.17487/RFC3370, August 2002,
              <https://www.rfc-editor.org/rfc/rfc3370>.

   [RFC4511]  Sermersheim, J., Ed., "Lightweight Directory Access
              Protocol (LDAP): The Protocol", RFC 4511,
              DOI 10.17487/RFC4511, June 2006,
              <https://www.rfc-editor.org/rfc/rfc4511>.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              DOI 10.17487/RFC5322, October 2008,
              <https://www.rfc-editor.org/rfc/rfc5322>.





Gillmor, et al.           Expires 12 July 2025                 [Page 54]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   [RFC5355]  Stillman, M., Ed., Gopal, R., Guttman, E., Sengodan, S.,
              and M. Holdrege, "Threats Introduced by Reliable Server
              Pooling (RSerPool) and Requirements for Security in
              Response to Threats", RFC 5355, DOI 10.17487/RFC5355,
              September 2008, <https://www.rfc-editor.org/rfc/rfc5355>.

   [RFC6376]  Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,
              "DomainKeys Identified Mail (DKIM) Signatures", STD 76,
              RFC 6376, DOI 10.17487/RFC6376, September 2011,
              <https://www.rfc-editor.org/rfc/rfc6376>.

   [RFC6409]  Gellens, R. and J. Klensin, "Message Submission for Mail",
              STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011,
              <https://www.rfc-editor.org/rfc/rfc6409>.

   [RFC7292]  Moriarty, K., Ed., Nystrom, M., Parkinson, S., Rusch, A.,
              and M. Scott, "PKCS #12: Personal Information Exchange
              Syntax v1.1", RFC 7292, DOI 10.17487/RFC7292, July 2014,
              <https://www.rfc-editor.org/rfc/rfc7292>.

   [RFC7435]  Dukhovni, V., "Opportunistic Security: Some Protection
              Most of the Time", RFC 7435, DOI 10.17487/RFC7435,
              December 2014, <https://www.rfc-editor.org/rfc/rfc7435>.

   [RFC7929]  Wouters, P., "DNS-Based Authentication of Named Entities
              (DANE) Bindings for OpenPGP", RFC 7929,
              DOI 10.17487/RFC7929, August 2016,
              <https://www.rfc-editor.org/rfc/rfc7929>.

   [RFC8162]  Hoffman, P. and J. Schlyter, "Using Secure DNS to
              Associate Certificates with Domain Names for S/MIME",
              RFC 8162, DOI 10.17487/RFC8162, May 2017,
              <https://www.rfc-editor.org/rfc/rfc8162>.

   [RFC8621]  Jenkins, N. and C. Newman, "The JSON Meta Application
              Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,
              August 2019, <https://www.rfc-editor.org/rfc/rfc8621>.

   [RFC8823]  Melnikov, A., "Extensions to Automatic Certificate
              Management Environment for End-User S/MIME Certificates",
              RFC 8823, DOI 10.17487/RFC8823, April 2021,
              <https://www.rfc-editor.org/rfc/rfc8823>.

   [RFC9051]  Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
              Access Protocol (IMAP) - Version 4rev2", RFC 9051,
              DOI 10.17487/RFC9051, August 2021,
              <https://www.rfc-editor.org/rfc/rfc9051>.




Gillmor, et al.           Expires 12 July 2025                 [Page 55]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   [RFC9216]  Gillmor, D. K., Ed., "S/MIME Example Keys and
              Certificates", RFC 9216, DOI 10.17487/RFC9216, April 2022,
              <https://www.rfc-editor.org/rfc/rfc9216>.

   [RFC9219]  Melnikov, A., "S/MIME Signature Verification Extension to
              the JSON Meta Application Protocol (JMAP)", RFC 9219,
              DOI 10.17487/RFC9219, April 2022,
              <https://www.rfc-editor.org/rfc/rfc9219>.

   [RFC9580]  Wouters, P., Ed., Huigens, D., Winter, J., and Y. Niibe,
              "OpenPGP", RFC 9580, DOI 10.17487/RFC9580, July 2024,
              <https://www.rfc-editor.org/rfc/rfc9580>.

   [SPOOFING] Müller, J., Brinkmann, M., Poddebniak, D., Böck, H.,
              Schinzel, S., Somorovsky, J., and J. Schwenk, "“Johnny,
              you are fired!” – Spoofing OpenPGP and S/MIME Signatures
              in Emails", August 2019,
              <https://www.usenix.org/system/files/sec19-muller.pdf>.

   [SRI]      "Subresource Integrity", June 2016,
              <https://www.w3.org/TR/SRI/>.

Appendix A.  Future Work

   This document contains useful guidance for MUA implementers, but it
   cannot contain all possible guidance.  Future revisions to this
   document may want to further explore the following topics, which are
   out of scope for this version.

A.1.  Webmail Threat Model

   The webmail threat model for end-to-end cryptographic protections is
   significantly more complex than the traditional MUA model.  For
   example, the web server hosting the webmail interface could be a
   potential adversary.  If the user treats the web server as a trusted
   party, but the web server violates that trust, the end-to-end
   cryptographic protections do not hold.

   A future version of this document could include more detailed
   discussion of an adversarial threat model for end-to-end
   cryptographic protections in a webmail context.

A.2.  Test Vectors

   A future version of this document (or a companion document) could
   contain examples of well-formed and malformed messages using
   cryptographic key material and certificates from [RFC9580] and
   [RFC9216].



Gillmor, et al.           Expires 12 July 2025                 [Page 56]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   It may also include example renderings of these messages.

A.3.  Further Guidance on Peer Certificates

A.3.1.  Certificate Discovery from Incoming Messages

   As described in Section 8.2.3, an incoming e-mail message may have
   one or more certificates embedded in it.  This document currently
   acknowledges that receiving MUA should assemble a cache of
   certificates for future use, but providing more detailed guidance for
   how to assemble and manage that cache is currently out of scope.

   Existing recommendations like [AUTOCRYPT] provide some guidance for
   handling incoming certificates about peers, but only in certain
   contexts.  A future version of this document may describe in more
   detail how these incoming certs should be handled.

A.3.2.  Certificate Directories

   Some MUAs may have the capability to look up peer certificates in a
   directory, for example via LDAP [RFC4511], WKD
   [I-D.koch-openpgp-webkey-service], or the DNS (e.g., SMIMEA [RFC8162]
   or OPENPGPKEY [RFC7929] resource records).

   A future version of this document may describe in more detail what
   sources an MUA should consider when searching for a peer's
   certificates, and what to do with the certificates found by various
   methods.

A.3.3.  Checking for Certificate Revocation

   A future version of this document could discuss how/when to check for
   revocation of peer certificates, or of the user's own certificate.

   Such discussion should address privacy concerns: what information
   leaks to whom when checking peer cert revocations?

A.3.4.  Further Peer Certificate Selection

   A future version of this document may describe more prescriptions for
   deciding whether a peer certificate is acceptable for encrypting a
   message.  For example, if the SPKI is an EC Public Key and the
   keyUsage extension is absent, what should the encrypting MUA do?








Gillmor, et al.           Expires 12 July 2025                 [Page 57]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   A future version of this document might also provide guidance on what
   to do if multiple certificates are all acceptable for encrypting to a
   given recipient.  For example, the sender could select among them in
   some deterministic way; it could encrypt to all of them; or it could
   present them to the user to let the user select any or all of them.

A.3.5.  Human-readable Names in Peer Certificates, Header Fields, and
        Addressbooks

   In header fields like From: that may contain a display-name as
   described in Section 3.4 of [RFC5322], a malicious sender (or
   interfering adversary) may populate the display-name part with a
   human-readable name that does not at all match the actual name of the
   participant.  Section 8.1.1 describes some matching rules relating
   peer certificates to e-mail addresses (the addr-spec part of these
   e-mail header fields), but does not contemplate matching display-
   names or other or similar user-visible data elements.  Section 6.4
   describes how signature validation should confirm a binding between
   the addr-spec and the certificate itself, but also does not
   contemplate matching display-names or other similar user-visible data
   elements.  Depending on how the receiving MUA renders the display-
   name in a message's header field, that unvalidated field may present
   a risk of user confusion which could break the intended end-to-end
   assurances.  Yet both X.509 and OpenPGP certificate formats offer
   ways to provide cryptographically certified (though possibly not
   unique) comparable human-readable names.  Additionally, many MUAs
   also include an addressbook or comparable feature which can make
   substantive connections between user-relevant identity labels and
   e-mail addresses.

   A human-readable name like a display-name does not have the property
   of global uniqueness that an addr-spec does, so reasoning about
   human-readable names and rendering them to the user as an element in
   a system providing end-to-end cryptographic assurance requires
   additional deliberate analysis.

   A future version of this document might offer strategies for
   associating human-readable names from certificates (and features like
   addressbooks) to the rendering of header fields that include display-
   name.  Such guidance should be paired with an analysis of specific
   usability and security risks associated with these human-readable
   fields, as well as a description of how the recommended guidance
   mitigates those risks.

A.4.  Further Guidance on Local Certificates and Secret Keys






Gillmor, et al.           Expires 12 July 2025                 [Page 58]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


A.4.1.  Cross-MUA sharing of Local Certificates and Secret Keys

   Many users today use more than one MUA to access the same mailbox
   (for example, one MUA on a mobile device, and another MUA on a
   desktop computer).

   A future version of this document might offer guidance on how
   multiple MUAs attached to the same mailbox can efficiently and
   securely share the user's own secret key material and certificates
   between each other.  This guidance should include suggestions on how
   to maintain the user's keys (e.g., avoiding certificate expiration)
   and safe secret key transmission.

A.4.2.  Use of Smartcards or Other Portable Secret Key Mechanisms

   Rather than having to transfer secret key material between clients,
   some users may prefer to rely on portable hardware-backed secret keys
   in the form of smartcards, USB tokens or other comparable form
   factors.  These secret keys sometimes require direct user interaction
   for each use, which can complicate the usability of any MUA that uses
   them to decrypt a large number of messages.

   Guidance on the use of this kind of secret key management are beyond
   the scope of this document, but future revisions may bring them into
   scope.

A.4.3.  Active Local Certificate Maintenance

   Section 8.2.2 describes conditions where the MUA SHOULD warn the user
   that something is going wrong with their certificate.

   A future version of this document might outline how an MUA could
   actively avoid these warning situations, for example, by
   automatically updating the certificate or prompting the user to take
   specific action.

A.5.  Certification Authorities

   A future document could offer guidance on how an MUA should select
   and manage root certification authorities (CAs).

   For example:

   *  Should the MUA cache intermediate CAs?

   *  Should the MUA share such a cache with other PKI clients (e.g.,
      web browsers)?




Gillmor, et al.           Expires 12 July 2025                 [Page 59]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  What distinctions are there between a CA for S/MIME and a CA for
      the web?

A.6.  Indexing and Search of Encrypted Messages

   A common use case for MUAs is search of existing messages by keyword
   or topic.  This is done most efficiently for large mailboxes by
   assembling an index of message content, rather than by a linear scan
   of all message content.

   When message contents and header fields are encrypted, search by
   index is complicated.  If the cleartext is not indexed, then messages
   cannot be found by search.  On the other hand, if the cleartext is
   indexed, then the index effectively contains the sensitive contents
   of the message, and needs to be protected.

   Detailed guidance on the tradeoff here, including choices about
   remote search vs local search, are beyond the scope of this document,
   but a future version of the document may bring them into scope.

A.7.  Cached Signature Validation

   Asymmetric signature validation can be computationally expensive, and
   the results can also potentially vary over time (e.g., if a signing
   certificate is discovered to be revoked).  In some cases, the user
   may care about the signature validation that they saw when they first
   read or received the message, not only about the status of the
   signature verification at the current time.

   So, for both performance reasons and historical perspective, it may
   be useful for an MUA to cache signature validation results in a way
   that they can be easily retrieved and compared.  Documenting how and
   when to cache signature validation, as well as how to indicate it to
   the user, is beyond the scope of this document, but a future version
   of the document may bring these topics into scope.

A.8.  Aggregate Cryptographic Status

   This document limits itself to consideration of the cryptographic
   status of single messages as a baseline concept that can be clearly
   and simply communicated to the user.  However, some users and some
   MUAs may find it useful to contemplate even higher-level views of
   cryptographic status which are not considered directly here.








Gillmor, et al.           Expires 12 July 2025                 [Page 60]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   For example, a future version of the document may also consider how
   to indicate a simple cryptographic status of message threads (groups
   of explicitly related messages), conversations (groups of messages
   with shared sets of participants), peers, or other perspectives that
   an MUA can provide.

A.9.  Expectations of Cryptographic Protection

   As mentioned in Section 2.3, the types of security indicators
   displayed to the user may well vary based on the expectations of the
   user for a given communication.  At present, there is no widely
   shared method for the MUA to establish and maintain reasonable
   expectations about whether a specific received message should have
   cryptographic protections.

   If such a standard is developed, a future version of this document
   should reference it and encourage the deployment of clearer and
   simpler security indicators.

A.10.  Secure Deletion

   One feature many users desire from a secure communications medium is
   the ability to reliably destroy a message such that it cannot be
   recovered even by a determined adversary.  In other contexts, a
   similar desired property is called "forward secrecy".  Doing this
   with standard e-mail mechanisms like S/MIME and PGP/MIME is
   challenging because of two interrelated factors:

   *  A copy of of an e-mail message may be retained by any of the mail
      transport agents that handle it during delivery, and

   *  The secret key used to decrypt an encrypted e-mail message is
      typically retained indefinitely.

   This means that an adversary aiming to recover the cleartext contents
   of a deleted message can do so by getting access to a copy of the
   encrypted message and the long-term secret key material.

   Some mitigation measures may be available to make it possible to
   delete some encrypted messages securely, but this document considers
   this use case out of scope.  A future version of the document may
   elaborate on secure message deleton in more detail.









Gillmor, et al.           Expires 12 July 2025                 [Page 61]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


A.11.  Interaction with Opportunistic Encryption

   This document focuses on guidance for strong, user-comprehensible
   end-to-end cryptographic protections for e-mail.  Other approaches
   are possible, including various forms of opportunistic and transport
   encryption, which are out of scope for this document.

   A future version of this document could describe the interaction
   between this guidance and more opportunistic forms of encryption, for
   example some of the scenarios contemplated in
   [I-D.dkg-mail-cleartext-copy].

A.12.  Split Attachments

   As noted in Section 7.2, the standard form for encrypted e-mail
   messages is a single cryptographic envelope.  In a scenario where
   multiple user agents are drafting a single encrypted message over
   low-bandwidth links, this can create a poor user experience, as each
   MUA has to retrieve the full message, including attachments, to
   modify the draft.  Similarly, when retrieving a message with a large
   attachment, the receiving MUA might want to only render the main body
   part, and will have a significant delay in doing so if required to
   process the full message before handling.

   Future work might include an attempt to standardize a mechanism that
   eases this use case, potentially at the risk of additional metadata
   leakage about the message (e.g., the size and number of message
   parts).  Any such work should explicitly try to minimize the risks
   and concerns described in Section 7.2.

A.13.  Proxy Extensions

   As noted in Section 9.7, a proxy-based implementation can be a
   tempting approach.  But its naive form is likely to be insufficient
   to provide safe end-to-end encrypted e-mail.

   A future version of this document, or a separate but related
   document, could try to outline the specific additional information,
   state, and network API surface that would be needed to allow an MUA
   to be safely integrated with an encryption provider.  Any such work
   should try to address the potential problems described in
   Section 9.7.









Gillmor, et al.           Expires 12 July 2025                 [Page 62]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


A.14.  Mailing Lists

   Mailing lists offer challenging complications to any notion of end-
   to-end cryptographic protections.  By default, there is some sort of
   intervening MUA (see Section 9.8), but more than that, user
   expectations about cryptographic protections might differ from normal
   messages, at least insofar as they understand they are writing to a
   mailing list.  A particular challenge to the notion of end-to-end
   cryptographic security with mailing lists is that a subscriber to a
   mailing list often does not know who else is subscribed to the
   mailing list.  Another challenge is that for some mailing lists, some
   subscribers might not have a valid, non-expired certificate.

   Encryption can interact with mailing lists in different ways,
   depending on the use case of the list.  It's not clear that there are
   any useful motivations for sending encrypted mail to a publicly
   archived mailing list.  But an unarchived mailing list might want to
   provide confidentiality between all recipients, even if the
   recipients don't know for certain who all the other participants are.
   Or, a mailing list with private archives might well decide that two
   "hops" of encryption (between the sender and the mailing list, and
   the mailing list and all the subscribers) are a useful
   confidentiality measure even though they are not "end-to-end" in the
   sense of the sender directly to all recipients.

   Similarly, cryptographic signatures may play different roles in a
   mailing list, depending on the list's communication goals.  The
   mailing list itself might want to verify that an incoming message is
   cryptographically signed by an authorized sender before
   redistribution to the list subscribers.  It might also want to pass
   along the sender's signature in a way that the subscribers can all
   verify it.  Alternately, the mailing list might want to sign each
   redistributed message itself, and change the message so it appears to
   come from the list rather than the original sender.

   Yet another design for a mailing list with end-to-end cryptographic
   protections might involve redistributing shared secret keys to all
   recipients, or using some sort of proxied re-encryption scheme,
   similar to [I-D.wussler-openpgp-forwarding].

   A future version of this document or a separate but related document
   might describe some of these tradeoffs and provide guidance for
   safely meeting common requirements or use cases when combining end-
   to-end cryptographic protections with mailing lists.







Gillmor, et al.           Expires 12 July 2025                 [Page 63]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


Appendix B.  Document History

B.1.  Substantive changes from draft-ietf-...-16 to draft-ietf-...-17

   *  Update OpenPGP references to RFC 9580

   *  Clarify ciphertext malleability concerns

B.2.  Substantive changes from draft-ietf-...-15 to draft-ietf-...-16

   *  Address feedback from Last Call and IESG review:

   *  Add "Weak Encryption" section

   *  Add Future Work subsection on mailing lists

   *  Add Future Work subsection on human-readable names

   *  Mention possible user control over stripping quoted text in
      cleartext reply to encrypted message

   *  Simplify Bcc guidance about certificate inclusion

B.3.  Substantive changes from draft-ietf-...-14 to draft-ietf-...-15

   *  update IMAP reference to RFC 9051

   *  add webmail concerns as part of Future Work

B.4.  Substantive changes from draft-ietf-...-13 to draft-ietf-...-14

   *  Responded to SEC AD Review, including:

   *  clarify "conformant" vs "legacy" vs "non-cryptographic" MUA
      categories

   *  tighten up MUSTs for conformant MUAs

   *  explicitly recommend encrypting drafts

   *  clarify debugging as a use case for showing invalid signatures

   *  clarify "Headers" to "Header Fields"

   *  3 states for sending, 4 for receiving






Gillmor, et al.           Expires 12 July 2025                 [Page 64]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


B.5.  Substantive changes from draft-ietf-...-12 to draft-ietf-...-13

   *  clarify RFC 2119 guidance about not rendering cryptographic layers
      other than message cryptographic status

B.6.  Substantive changes from draft-ietf-...-11 to draft-ietf-...-12

   *  More nuance (and future work) around split attachments

   *  More nuance (and future work) around proxy-style design

   *  Clearer caveats about external resources in text/html parts

B.7.  Substantive changes from draft-ietf-...-10 to draft-ietf-...-11

   *  Mention List-* and Archived-At message header fields

   *  Add additional references to papers that describe flaws in e2e
      e-mail

B.8.  Substantive changes from draft-ietf-...-09 to draft-ietf-...-10

   *  Introduction: describe one major theme of Future Work

B.9.  Substantive changes from draft-ietf-...-08 to draft-ietf-...-09

   *  Clarify goals of document

   *  Identify cross-protocol attacks in more detail to justify
      prescription against key reuse

   *  Add informative references to Opportunistic Encryption RFC and
      Certificate Best Practice draft

   *  Add "Reading Encrypted Messages after Certificate Expiration"
      section to Common Pitfalls and Guidelines

   *  Clean up nits identified by Stephen Farrell and Eliot Lear

B.10.  Substantive changes from draft-ietf-...-07 to draft-ietf-...-08

   *  Add guidance about importing and exporting secret key material

   *  More explanation about "encryption outside, signature inside"

   *  Guidance about Intervening (resending) MUAs

   *  Include Sender and Resent-* as user-facing header fields



Gillmor, et al.           Expires 12 July 2025                 [Page 65]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  Guidance about external subresources for cryptographically
      protected messages

   *  Relax "user-facing" definition to be more advisory

B.11.  Substantive changes from draft-ietf-...-06 to draft-ietf-...-07

   *  Add Bernie Hoeneisen and Alexey Melnikov as editors

   *  Explicitly avoid requiring anything from IANA

   *  Simplify description of "attachments"

   *  Add concrete detail on how to compare e-mail addresses

   *  Explicitly define "Cryptographic Summary"

B.12.  Substantive changes from draft-ietf-...-05 to draft-ietf-...-06

   *  Expand proxy implementation warning to comparable APIs

   *  Move many marked TODO and FIXME items to "Future Work"

   *  More detailed guidance on local certificates

   *  Provide guidance on encrypting draft messages

   *  More detailed guidanc eon shipping certificates in outbound
      messages

   *  Recommend implementing header protection

   *  Added "Future Work" subsection about interactions with
      opportunistic approaches

B.13.  Substantive changes from draft-ietf-...-04 to draft-ietf-...-05

   *  Adopt and update text about Bcc from draft-ietf-lamps-header-
      protection

   *  Add section about the dangers of an implementation based on a
      network protocol proxy

B.14.  Substantive changes from draft-ietf-...-03 to draft-ietf-...-04

   *  Added reference to multipart/oracle attacks





Gillmor, et al.           Expires 12 July 2025                 [Page 66]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   *  Clarified that "Structural Header fields" are the same as
      RFC2045's "MIME Headers"

B.15.  Substantive changes from draft-ietf-...-02 to draft-ietf-...-03

   *  Added section about mixed recipients

   *  Noted SMIMEA and OPENPGPKEY DNS RR cert discovery mechanisms

   *  Added more notes about simplified mental models

   *  More clarification on one-status-per-message

   *  Added guidance to defend against EFAIL

B.16.  Substantive changes from draft-ietf-...-01 to draft-ietf-...-02

   *  Added definition of "user-facing" header fields

B.17.  Substantive changes from draft-ietf-...-00 to draft-ietf-...-01

   *  Added section about distinguishing Main Body Parts and Attachments

   *  Updated document considerations section, including reference to
      auto-built editor's copy

B.18.  Substantive changes from draft-dkg-...-01 to draft-ietf-...-00

   *  WG adopted draft

   *  moved Document History and Document Considerations sections to end
      of appendix, to avoid section renumbering when removed

B.19.  Substantive changes from draft-dkg-...-00 to draft-dkg-...-01

   *  consideration of success/failure indicators for usability

   *  clarify extendedKeyUsage and keyUsage algorithm-specific details

   *  initial section on certificate management

   *  added more TODO items

Authors' Addresses







Gillmor, et al.           Expires 12 July 2025                 [Page 67]

Internet-Draft   Guidance on End-to-End E-mail Security     January 2025


   Daniel Kahn Gillmor (editor)
   American Civil Liberties Union
   125 Broad St.
   New York, NY,  10004
   United States of America
   Email: dkg@fifthhorseman.net


   Bernie Hoeneisen (editor)
   pEp Project
   Oberer Graben 4
   CH- 8400 Winterthur
   Switzerland
   Email: bernie@ietf.hoeneisen.ch
   URI:   https://pep-project.org/


   Alexey Melnikov (editor)
   Isode Ltd
   14 Castle Mews
   Hampton, Middlesex
   TW12 2NP
   United Kingdom
   Email: alexey.melnikov@isode.com



























Gillmor, et al.           Expires 12 July 2025                 [Page 68]


name: draft-happel-structured-email-trust
rev: 04
title: Trust and security considerations for Structured Email
time: 2025-08-30T18:32:55Z
group_uri: /api/v1/group/group/2380/
expires: 2025-11-14T12:15:29Z
states: ["/api/v1/doc/state/4/", "/api/v1/doc/state/150/", "/api/v1/doc/state/36/"]
categories: ["Data formats/interop", "Agent identity/auth"]
tags: []
fetched_at: 2026-02-27T22:56:05.127597+00:00
abstract:
This document discusses trust and security considerations for
   structured email and provides recommendations for message user agents
   on how to deal with structured data in email messages.

full_text:
sml                                                         H.-J. Happel
Internet-Draft                                                   audriga
Intended status: Standards Track                          A. Gulbrandsen
Expires: 14 November 2025                                          ICANN
                                                             13 May 2025


         Trust and security considerations for Structured Email
                 draft-happel-structured-email-trust-04

Abstract

   This document discusses trust and security considerations for
   structured email and provides recommendations for message user agents
   on how to deal with structured data in email messages.

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 14 November 2025.

Copyright Notice

   Copyright (c) 2025 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.





Happel & Gulbrandsen    Expires 14 November 2025                [Page 1]

Internet-Draft                  SML Trust                       May 2025


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   3
   3.  Types of security concerns  . . . . . . . . . . . . . . . . .   3
     3.1.  Spam/virus filters  . . . . . . . . . . . . . . . . . . .   3
     3.2.  Formal display of data  . . . . . . . . . . . . . . . . .   3
     3.3.  Automated processing  . . . . . . . . . . . . . . . . . .   4
     3.4.  External references . . . . . . . . . . . . . . . . . . .   4
     3.5.  Social engineering  . . . . . . . . . . . . . . . . . . .   4
   4.  Trust mechanisms  . . . . . . . . . . . . . . . . . . . . . .   5
     4.1.  Trusted senders . . . . . . . . . . . . . . . . . . . . .   5
     4.2.  Sender signatures . . . . . . . . . . . . . . . . . . . .   6
     4.3.  Domain signatures . . . . . . . . . . . . . . . . . . . .   6
     4.4.  Recipient-generated identifiers . . . . . . . . . . . . .   6
     4.5.  Secrets and related messages  . . . . . . . . . . . . . .   6
   5.  Categories of use cases . . . . . . . . . . . . . . . . . . .   7
   6.  Implementation guidelines . . . . . . . . . . . . . . . . . .   7
     6.1.  Processing structured data  . . . . . . . . . . . . . . .   7
     6.2.  Inlining data . . . . . . . . . . . . . . . . . . . . . .   7
   7.  Implementation status . . . . . . . . . . . . . . . . . . . .   8
     7.1.  Structured Email plugin for Roundcube Webmail . . . . . .   8
   8.  Security considerations . . . . . . . . . . . . . . . . . . .   8
   9.  Privacy considerations  . . . . . . . . . . . . . . . . . . .   8
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     11.1.  Normative References . . . . . . . . . . . . . . . . . .   8
     11.2.  Informative References . . . . . . . . . . . . . . . . .   9
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   Structured email, as described in [I-D.sml-structured-email], makes
   the content of some email messages machine-readable, such that user
   agents can provide higher-level functions than displaying/replying,
   for example "add this to calendar".

   Naturally, new functions bring new trust and security considerations,
   or bring new urgency to existing issues.  This document discusses
   issues related to trust and security of structured email, and
   provides advice in some cases.









Happel & Gulbrandsen    Expires 14 November 2025                [Page 2]

Internet-Draft                  SML Trust                       May 2025


2.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Types of security concerns

   This section gives an overview of the various types of security and
   privacy concerns that arise when email messages contain structured
   data.  The same concerns often arise for other messages, of course.

3.1.  Spam/virus filters

   Structured email increases the syntactical and semantic complexity of
   email messages.  If a spam/virus filter parses structured email in
   order to block malevolent messages, the filter's parser will
   necessarily differ from that of the MUA that will finally act on the
   structured data, creating a risk of misclassification.

   These risks are elevated when a structured data format has complex
   syntax, syntax that offers several optional or alternative ways to
   express the same substance, and of course by parsers that deviate
   from the specification for better bug compatibiloty.

3.2.  Formal display of data

   A common example is displaying a received calendar invitation using
   dates/times in the recipient's timezone, in a fixed format.

   Formal display introduces additional possibilities of discrepancy
   between the different representations.  For example, a single message
   might contains a multipart/alternative containing a text/plain
   description of a flight itinerary, a text/html description of the
   same itinerary, and a structured representation.  All three may be
   different, leading to confusion (and in this example, perhaps to
   missing a flight).

   Unintentional discrepancy is a risk for senders; some recipients may
   be misinformed.

   If a message is sent to a group and there is a discrepancy, different
   members of the group may see it differently.






Happel & Gulbrandsen    Expires 14 November 2025                [Page 3]

Internet-Draft                  SML Trust                       May 2025


   If a particular MUA displays the formal representation within the
   message, a malevolent sender could try to mimic the visual
   representation using HTML with CSS, but with misleading content.

3.3.  Automated processing

   Automated processing covers actions that are taken as soon as the
   message arrives rather than when a human user reads the message.  For
   example, a user might want flight reservations to be automatically
   added to a travel itinerary application and/or a calendar.

   Such automation could be a custom MUA feature or a future extension
   of the Sieve email filtering language ([RFC5228]).  A related example
   for abuse in automated processing is calendar spam ([CalSpam]).

3.4.  External references

   Email messages with a text/html body part ("HTML email messages") may
   contain image resources that link to web servers.  Such links can be
   used for tracking user interaction with the message.

   Similar concerns apply to structured data types which include image
   references, such as the cover image of a music album or the teaser
   image of a news article.

   RDF structured data can be partial by design and include references
   to additional data.  Using a "follow your nose" approach, tools can
   follow URL references to obtain further structured data concerning a
   resource.  For example, a piece of structured data about an article
   could reference the article's authors only by URL.  For a meaningful
   processing of author information, one might try to obtain further
   data using that URL.

3.5.  Social engineering

   While the risks of social engineering are hardly new and the human-
   readable text in a message can in principle be used to persuade the
   human reader to do anything, structured data widens the variety of
   actions the human reader can easily perform.  If there are more
   buttons to click, then there's also a greater variety of attacks.

   Put differently: A user who might not be able to follow the
   instructions in a long and involved text-based social engineering
   attack may be able to follow simple instructions such as "click this
   ten that".






Happel & Gulbrandsen    Expires 14 November 2025                [Page 4]

Internet-Draft                  SML Trust                       May 2025


4.  Trust mechanisms

   Several implementations of structured email restrict processing to
   messages that are particularly trusted.  That is to say, an incoming
   message is in one of these three categories:

   1.  Spam.  Structured data is not processed.

   2.  Ordinary.  Structured data is not processed.

   3.  Trusted.  Structured data is processed.

   This section gives an overview of the trust mechanisms used at the
   time of writing.

   It does not attempt to describe whether a trust-based mechanism is
   appopriate in a particular case.

   It is RECOMMENDED to restrict trust to a simple "or", rather than
   e.g. an elaborate scoring mechanism that's difficult to understand
   for users.

4.1.  Trusted senders

   For the case of displaying remote images embedded in HTML email
   messages, MUAs often allow users to manually choose if they trust a
   certain sender.  Sometimes, addresses in the MUA's address book are
   considered trusted, or in a special list in the address book.  While
   this is mentioned in [RFC6132] and [RFC6134], this mechanism is
   currently not standardized.

   Several services manage trust centrally: trusted senders are trusted
   by the mail service rather than by the individual users.

   Some services differentiate between local mail and mail that arrived
   across the internet, and trust local mail.  In particular, one author
   has seen that attachments sent by remote senders are distrusted
   ("warning! do you really want to download this?") while attachments
   from senders within the recipient's organization are assumed to be
   benevolent.

   OPEN ISSUE: Whether this should discuss combining sender trust with
   sender/domain signatures.  Pro: A sender that has used DKIM may be
   assumed trustworthy if subsequent message also do it, less so if not.
   Contra: Isn't this what DMARC does, and best regulated only there?






Happel & Gulbrandsen    Expires 14 November 2025                [Page 5]

Internet-Draft                  SML Trust                       May 2025


4.2.  Sender signatures

   Sender signatures such as PGP or S/MIME could potentially be used as
   a trust indicator.  The authors aren't aware of any concrete examples
   of this in the past, perhaps because of limited deployment.

4.3.  Domain signatures

   DKIM defines a signature on sender domain that may be used to verify
   that a message was sent by the same sender as an earlier message.

   Some mail hosts restrict structured processing to messages with DKIM
   signatures, or to a set of senders who are identified by their DKIM
   signatures.

4.4.  Recipient-generated identifiers

   Part of the simplicity of email is the fact that just the email
   address is required to reach out to a recipient.  This however
   requires the the recipient to discern whether a message is desirable
   or abusive.

   Recipient-generated transaction identifiers aim to pass a certain
   secret to the sender, which helps to prove legitimacy.  One such
   approach are one-time email aliases, which are generated for a single
   transaction or series of transactions.

4.5.  Secrets and related messages

   A message may contain a secret or hard-to-guess identifier.

   A message may leverage another message's trust level by referencing
   an identifier from the other message.

   For example, a ticket sold by a concert venue may reference the
   payment transaction ID that's also mentioned in a message from the
   payment processor.  If these IDs are difficult to guess and the
   receiver trusts the payment processor, then this gives some reason to
   trust that the ticket is bona fide and could safely be added to the
   user's ticket/wallet app.

   In another example, a message with a calendar update may reference an
   identifier from the original calendar entry.  If this ID is hard to
   guess and the recipient acted on the message containing the original
   entry, then this gives some reason to trust that the change is bona
   fide.

   OPEN ISSUE: How to specify the secret.



Happel & Gulbrandsen    Expires 14 November 2025                [Page 6]

Internet-Draft                  SML Trust                       May 2025


   One possible solution: The leveraging message contains a
   specification of sender domain and optinal xpath query, and the MUA
   decides whether the sender is on its list.  But I don't like having
   xpath, its interop is said to be poor and a malevolent sender could
   specify something easily guessed.  For example, the messages I
   receive from a popular payment processor contain my name; an attacker
   could use an xpath query that results in my name.

   Another possible solution: The leveraging message specifies the
   sender of the leveraged message and the secret, and each MUA contains
   a hardcoded xpath query to find the ONLY kind of secret it trusts for
   that particular sender.

5.  Categories of use cases

   Certain types of structured data might need to be kept more secure
   than others.  For instance, the structured data representation of a
   music album shared by a friend would not contain major personal
   information, while e.g., medical records or financial statements
   certainly would.

6.  Implementation guidelines

6.1.  Processing structured data

   MUAs SHOULD consider structured data in incoming email messages only
   if either of these criteria hold:

   *  The sender is trusted (e.g., part of the user's address book) and
      the messsage either contains a valid personal or domain signature

   *  The message is part of an ongoing thread with a trusted sender

   If none of these criteria is fulfilled, MUAs should fall back to
   alternative presentations (e.g., "text/html" or "text/plain").

   Open issue 2: Really SHOULD?  I (Arnt) don't see this guidance as
   clearly right.  It doesn't match existing code well, and doesn't seem
   to be where we want to go.

6.2.  Inlining data

   Structured data included in an email message should be self-contained
   in order to avoid privacy problems.  This implies that if an MUA is
   able to provide meaningful user interaction (rather than mere
   display), then it should do that without loading additional
   referenced resources from the web.




Happel & Gulbrandsen    Expires 14 November 2025                [Page 7]

Internet-Draft                  SML Trust                       May 2025


7.  Implementation status

   RFC Editor: before publication please remove this section and the
   reference to [RFC7942].

   This section records the status of known implementations of the
   protocol defined by this specification at the time of posting of this
   Internet-Draft, and is based on a proposal described in [RFC7942].
   The description of implementations in this section is intended to
   assist the IETF in its decision processes in progressing drafts to
   RFCs.  Please note that the listing of any individual implementation
   here does not imply endorsement by the IETF.  Furthermore, no effort
   has been spent to verify the information presented here that was
   supplied by IETF contributors.  This is not intended as, and must not
   be construed to be, a catalog of available implementations or their
   features.  Readers are advised to note that other implementations may
   exist.

   According to [RFC7942], "this will allow reviewers and working groups
   to assign due consideration to documents that have the benefit of
   running code, which may serve as evidence of valuable experimentation
   and feedback that have made the implemented protocols more mature.
   It is up to the individual working groups to use this information as
   they see fit".

7.1.  Structured Email plugin for Roundcube Webmail

   The plugin currently uses the "trusted sender" feature of Roundcube
   to determine if structured data should be processed.

8.  Security considerations

   Security considerations are a core subject of this document.

9.  Privacy considerations

   Privacy considerations are a core subject of this document.

10.  IANA Considerations

   This document has no IANA actions at this time.

11.  References

11.1.  Normative References






Happel & Gulbrandsen    Expires 14 November 2025                [Page 8]

Internet-Draft                  SML Trust                       May 2025


   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

11.2.  Informative References

   [I-D.sml-structured-email]
              "*** BROKEN REFERENCE ***".

   [RFC5228]  Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email
              Filtering Language", RFC 5228, DOI 10.17487/RFC5228,
              January 2008, <https://www.rfc-editor.org/rfc/rfc5228>.

   [RFC6132]  George, R. and B. Leiba, "Sieve Notification Using
              Presence Information", RFC 6132, DOI 10.17487/RFC6132,
              July 2011, <https://www.rfc-editor.org/rfc/rfc6132>.

   [RFC6134]  Melnikov, A. and B. Leiba, "Sieve Extension: Externally
              Stored Lists", RFC 6134, DOI 10.17487/RFC6134, July 2011,
              <https://www.rfc-editor.org/rfc/rfc6134>.

   [RFC7942]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", BCP 205,
              RFC 7942, DOI 10.17487/RFC7942, July 2016,
              <https://www.rfc-editor.org/rfc/rfc7942>.

   [CalSpam]  "Calendar operator practices — Guidelines to protect
              against calendar abuse", n.d.,
              <https://standards.calconnect.org/csd/cc-18003.html>.

   [MachineReadable]
              "NIST IR 7511 Rev 4", n.d.,
              <https://csrc.nist.gov/glossary/term/Machine_Readable>.

Appendix A.  Acknowledgements

   The authors wish to thank Ben Bucksch, Alexey Melnikov, Phillip Tao
   and others whose suggestions were made before this paragraph was
   started.

Authors' Addresses





Happel & Gulbrandsen    Expires 14 November 2025                [Page 9]

Internet-Draft                  SML Trust                       May 2025


   Hans-Joerg Happel
   audriga
   Email: happel@audriga.com
   URI:   https://www.audriga.com


   Arnt Gulbrandsen
   ICANN
   6 Rond Point Schumann, Bd. 1
   1040 Brussels
   Belgium
   Email: arnt@gulbrandsen.priv.no
   URI:   https://icann.org/ua






































Happel & Gulbrandsen    Expires 14 November 2025               [Page 10]


name: draft-eggert-mailmaint-uaautoconf
rev: 04
title: Automatic Configuration of Email, Calendar, and Contact Server Settings
time: 2025-09-28T23:32:52Z
group_uri: /api/v1/group/group/1027/
expires: 2026-04-01T23:32:52Z
states: ["/api/v1/doc/state/4/", "/api/v1/doc/state/150/"]
categories: ["Agent discovery/reg", "Data formats/interop"]
tags: []
fetched_at: 2026-02-27T22:56:05.127603+00:00
abstract:
This document specifies an automatic configuration mechanism for
   email, calendar, and contact user agent applications.  Service
   providers publish standardized configuration information that user
   agent applications retrieve and use to simplify server setup
   procedures.

full_text:
mailmaint                                                      D. Eggert
Internet-Draft                                              M. Diephouse
Intended status: Informational                                 Apple Inc
Expires: 2 April 2026                                  29 September 2025


Automatic Configuration of Email, Calendar, and Contact Server Settings
                  draft-eggert-mailmaint-uaautoconf-04

Abstract

   This document specifies an automatic configuration mechanism for
   email, calendar, and contact user agent applications.  Service
   providers publish standardized configuration information that user
   agent applications retrieve and use to simplify server setup
   procedures.

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 2 April 2026.

Copyright Notice

   Copyright (c) 2025 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.




Eggert & Diephouse        Expires 2 April 2026                  [Page 1]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Document Conventions  . . . . . . . . . . . . . . . . . . . .   3
   3.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  JSON Configuration  . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Example . . . . . . . . . . . . . . . . . . . . . . . . .   5
     4.2.  Protocols . . . . . . . . . . . . . . . . . . . . . . . .   6
     4.3.  Authentication  . . . . . . . . . . . . . . . . . . . . .   7
     4.4.  Informational . . . . . . . . . . . . . . . . . . . . . .   7
       4.4.1.  Provider Information  . . . . . . . . . . . . . . . .   8
       4.4.2.  Help  . . . . . . . . . . . . . . . . . . . . . . . .   9
   5.  Flow  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
     5.1.  Email Address . . . . . . . . . . . . . . . . . . . . . .  10
     5.2.  Configuration Source  . . . . . . . . . . . . . . . . . .  10
       5.2.1.  Primary Source  . . . . . . . . . . . . . . . . . . .  10
       5.2.2.  DNS MX Fallback . . . . . . . . . . . . . . . . . . .  17
     5.3.  Configuration JSON Validation . . . . . . . . . . . . . .  21
     5.4.  Selecting Protocols and Authentication  . . . . . . . . .  21
       5.4.1.  OAuth . . . . . . . . . . . . . . . . . . . . . . . .  22
       5.4.2.  HTTP Authentication Mechanisms  . . . . . . . . . . .  23
       5.4.3.  Other Protocols Authentication Mechanisms . . . . . .  24
     5.5.  Confirming Server Names . . . . . . . . . . . . . . . . .  27
     5.6.  Username  . . . . . . . . . . . . . . . . . . . . . . . .  27
     5.7.  Configuring OAuth . . . . . . . . . . . . . . . . . . . .  28
     5.8.  Configuring Password-Based Authentication . . . . . . . .  28
   6.  Configuration Validation  . . . . . . . . . . . . . . . . . .  29
     6.1.  User Approval . . . . . . . . . . . . . . . . . . . . . .  29
     6.2.  OAuth2 requirements . . . . . . . . . . . . . . . . . . .  29
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  29
     7.1.  Mistyped Domain Names . . . . . . . . . . . . . . . . . .  30
     7.2.  Attacker Controlled JSON Configuration  . . . . . . . . .  30
     7.3.  DNS . . . . . . . . . . . . . . . . . . . . . . . . . . .  31
     7.4.  Transport Security Validation . . . . . . . . . . . . . .  31
     7.5.  Updating the Configuration  . . . . . . . . . . . . . . .  32
     7.6.  Provider Information  . . . . . . . . . . . . . . . . . .  32
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  32
     8.1.  The User-Agent Auto-Configuration Protocol Registry . . .  32
       8.1.1.  Registration Template . . . . . . . . . . . . . . . .  33
       8.1.2.  Initial Registrations . . . . . . . . . . . . . . . .  33
     8.2.  Registration  . . . . . . . . . . . . . . . . . . . . . .  34
       8.2.1.  Registration of Well-Known URI
               user-agent-configuration  . . . . . . . . . . . . . .  34
       8.2.2.  Registration of DNS Underscore Label
               _ua-auto-config . . . . . . . . . . . . . . . . . . .  34
   9.  Normative References  . . . . . . . . . . . . . . . . . . . .  34
   Appendix A.  Configuration JSON Schema  . . . . . . . . . . . . .  39
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  41



Eggert & Diephouse        Expires 2 April 2026                  [Page 2]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  41

1.  Introduction

   Manual configuration of email, calendar, and contact user agent
   applications requires users to correctly specify numerous technical
   parameters including server hostnames, port numbers, and
   authentication protocols.  This manual process frequently results in
   configuration errors and setup failures, even among technically
   skilled users.

   This document defines a mechanism that significantly simplifies this
   configuration process.  Service providers can publish standardized
   configuration data that user agents can automatically retrieve and
   use.  In most cases, users need only provide their email address and
   account password to complete the setup.

   For service providers that support the OAuth Profile for Open Public
   Clients [OAuthPublic], this mechanism also enables automatic OAuth
   configuration.  The user agent automatically determines all necessary
   details to set up OAuth authentication for the associated account.

2.  Document Conventions

   In protocol examples, this document uses a prefix of "C: " to denote
   lines sent by the user agent to the server, and "S: " for lines sent
   by the server to the user agent.  Lines prefixed with "// " are
   comments explaining the previous protocol line.  These prefixes and
   comments are not part of the protocol.  Lines without any of these
   prefixes are continuations of the previous line, and no line break is
   present in the protocol unless specifically mentioned.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Overview

   The automatic configuration process begins when a user wants to set
   up their user agent application.  The user agent requests the user's
   email address and then uses the domain portion of that address to
   retrieve configuration data for the account.







Eggert & Diephouse        Expires 2 April 2026                  [Page 3]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Configuration retrieval uses the Well-Known URIs mechanism defined in
   [RFC8615].  The specific suffix for this configuration is user-agent-
   configuration.  Section 5.2 provides detailed information about the
   retrieval process.

   The configuration is provided as a JSON document (detailed in
   Section 4) that informs the user agent about:

   *  Human-readable information about the service provider

   *  Supported protocols for this domain

   *  Server endpoints for each protocol

   *  OAuth Profile for Open Public Clients support availability

   The user agent uses this configuration to determine whether the
   provider supports protocols that the user agent can also use, helping
   decide whether to continue with the setup process.  For example, an
   email user agent might check for support of JMAP, IMAP, POP3, and
   SMTP protocols.

   Next, the user agent typically connects to the relevant services to
   verify which authentication methods they support and whether the user
   agent can use those methods.  For instance, if the user agent needs
   both IMAP and SMTP, it will connect to both servers to check their
   capabilities and confirm compatibility with the user agent's
   supported authentication mechanisms.

   Based on the available options, the user agent then proceeds with one
   of two approaches:

   1.  Continue configuration using OAuth Profile for Open Public
       Clients, or

   2.  Request the user's password for traditional authentication

   Finally, the user agent uses the obtained credentials (OAuth tokens
   or password) to connect to the servers specified in the configuration
   document and validates that the credentials work correctly with the
   desired protocols.

4.  JSON Configuration

   The configuration document describes which services are available and
   their corresponding endpoints for a specific domain.





Eggert & Diephouse        Expires 2 April 2026                  [Page 4]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   The configuration file MUST conform to the JSON schema specification
   provided in Appendix A.

   The configuration uses the media type application/json.  The HTTP
   server MUST set the corresponding Content-Type header as specified in
   [RFC9110].

4.1.  Example

   The following example demonstrates a typical JSON configuration:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   {
       "protocols": {
           "jmap": {
               "url": "https://jmap.example.com/session"
           },
           "imap": {
               "host": "imap.example.com"
           },
           "pop3": {
               "host": "pop3.example.com"
           },
           "smtp": {
               "host": "smtp.example.com"
           },
           "caldav": {
               "url": "https://sync.example.com/calendar/"
           },
           "carddav": {
               "url": "https://sync.example.com/contacts/"
           }
       },
       "authentication": {
           "oauth-public": {
               "issuer": "https://auth.example.com/"
           },
           "password": true
       },
       "info": {
           "provider": {
               "name": "Example Provider Name",
               "shortName": "Example",
               "logo": [
                   {
                       "url": "https://www.example.net/logo.svg",
                       "content-type": "image/svg+xml"



Eggert & Diephouse        Expires 2 April 2026                  [Page 5]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


                   }
               ]
           },
           "help": {
               "documentation": "https://help.example.net/howto/\
                   set-up-your-mail-app.html",
               "developer": "https://developer.example.net/\
                   client-apps/",
               "contact": ["mailto:it@team.example.net"]
           }
       }
   }

4.2.  Protocols

   The protocols object specifies all protocols that the domain supports
   and identifies the server endpoint for each protocol.

   For the following HTTP-based protocols:

   *  JMAP defined in [RFC8620],

   *  CalDAV defined in [RFC4791], and

   *  CardDAV defined in [RFC6352]

   *  WebDAV defined in [RFC4918]

   each protocol entry MUST include a url value containing a URL with
   the https scheme.  This URL MUST specify an endpoint that serves the
   corresponding protocol.  The server MUST use the default port 443 for
   HTTPS, and the URL MUST NOT include an explicit port number.

   Hostnames in URLs MUST support Internationalized Domain Names (IDNs)
   as defined in [RFC5890] and [RFC5891].  Service providers MAY use
   either Unicode labels (u-labels) or ASCII Compatible Encoding labels
   (a-labels) in their configuration.  User agents MUST support both
   forms and handle the conversion between them as specified in
   [RFC5891].

   Example:

   "jmap": {
       "url": "https://jmap.example.com/session"
   }

   For the following text-based protocols:




Eggert & Diephouse        Expires 2 April 2026                  [Page 6]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   *  IMAP defined in [RFC9051],

   *  SMTP defined in [RFC5321], and

   *  POP3 defined in [RFC1939]

   *  ManageSieve defined in [RFC5804]

   each protocol entry MUST include a host value specifying the hostname
   of the server that provides the corresponding protocol.  The server
   MUST use the default port number for that protocol, with connections
   secured using TLS.  Section 5.4.3 goes into details about TLS and
   which ports to use.

   Hostnames MUST support Internationalized Domain Names (IDNs) as
   defined in [RFC5890] and [RFC5891].  Service providers MAY use either
   Unicode labels (u-labels) or ASCII Compatible Encoding labels
   (a-labels) in their configuration.  User agents MUST support both
   forms and handle the conversion between them as specified in
   [RFC5891].

   Example:

   "imap": {
       "host": "imap.mail.example.com"
   }

4.3.  Authentication

   The authentication object specifies which authentication mechanisms
   the provider supports.

   The nested password value indicates whether the provider supports
   username and password authentication.

   The nested oauth-public object contains a single issuer value that
   specifies the authorization server's issuer identifier as defined in
   [RFC8414].  This value is a URL that uses the https scheme and has no
   query or fragment components.  User agents can use this identifier
   for authentication via [OAuthPublic].  The presence of the oauth-
   public object indicates that the provider supports OAuth.

4.4.  Informational

   The info object contains information that user agents can present to
   users.  The only required field is info/provider/name, which SHOULD
   clearly identify the provider to the user.  The optional
   info/provider/shortName provides a shorter version of name.



Eggert & Diephouse        Expires 2 April 2026                  [Page 7]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   The info/provider/logo array can contain one or more entries pointing
   to the provider's logo images.  User agents can use these to display
   the provider's logo to users.

   The info/help/documentation field provides a URL that can be
   presented to users for additional information about the provider.
   The info/help/developer field contains a URL with information
   specifically for user agent developers.  The info/help/contact array
   lists URLs that users can use to contact the provider, such as mailto
   URLs.

   A minimal info example:

   "info": {
       "provider": {
           "name": "Example Provider Name"
       }
   }

4.4.1.  Provider Information

   provider object can have name, shortName, and logo properties.

   The name and shortName values are intended for display to the user.

   The name property specifies the provider's display name, such as the
   name used in the provider's marketing materials.  It SHOULD be no
   longer than 30 characters, but MUST be no longer than 60 characters.

   The shortName property is optional.  It specifies a brief version of
   the provider's name, as commonly recognized by users.  It SHOULD be
   no longer than 12 characters, and it MUST NOT be longer than 20
   characters.

   Both name and shortName MUST NOT include any Control-characters and
   SHOULD NOT include any excessive white space.

   The logo property contains an array of provider logo variants.  User
   agents select the variant that best matches their UI requirements and
   technical constraints.

   Each object in the array contains the following properties:

   *  url - Location where the logo can be retrieved.  User agents MAY
      download the logo file during configuration and store it locally.






Eggert & Diephouse        Expires 2 April 2026                  [Page 8]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   *  content-type - Media type of the logo image.  This follows
      [RFC2045] media type format, specifying the main type and subtype
      without parameters.  The main media type MUST be image.

   *  width - Image width in pixels.  Optional.  Omitted for SVG files.

   *  height - Image height in pixels.  Optional.  Omitted for SVG
      files.

   The logos SHOULD at least include one of each

   *  image/svg+xml

   *  image/png with size 128 by 128

   *  image/png with size 512 by 512

   If the server provides images in the SVG format, these images MUST
   use the SVG Tiny PS Profile specified in [I-D.svg-tiny-ps-abrotman].

4.4.2.  Help

   These fields are intended to allow a service provider to provide
   additional information about configuring user agents.

   The documentation property should link to a document intended for
   users.  It can provide additional information to users about how to
   configure their user agent.  A user agent MAY choose to display a
   link to this URL.  User agent SHOULD NOT display links with a URL
   scheme other than https.

   The developer property should link to a document intended for user
   agent developers.  The document this URL links to can provide
   additional information to the developer.

   The contact property should provide a way for user agent developers
   to contact the service providers.  It is _not_ intended as a way for
   users to contact the service provider.  User agents MUST NOT display
   this link in their user interface.  This URL would typically be a
   mailto URL or a URL linking to a contact form for developers to use.

5.  Flow

   Section 3 provides a high-level overview of the automatic
   configuration process.  This section details the individual steps
   involved in this process.





Eggert & Diephouse        Expires 2 April 2026                  [Page 9]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.1.  Email Address

   During the initial configuration process, the user agent requests the
   user's email address.  User agents SHOULD accept any valid mailbox
   format as specified in Section 3.4 of [RFC5322].

5.2.  Configuration Source

   After the user provides their email address, the user agent extracts
   the domain part of the user's email address according to
   Section 3.4.1 of [RFC5322].  For example:

           +================================+=================+
           | Text Entered by User           | domain          |
           +================================+=================+
           | jdoe@foo.example.com           | foo.example.com |
           +--------------------------------+-----------------+
           | "J Doe" <jdoe@foo.example.com> | foo.example.com |
           +--------------------------------+-----------------+
           | <jdoe@foo.example.com>         | foo.example.com |
           +--------------------------------+-----------------+

                    Table 1: Domain from email address

   This domain is then used to retrieve the JSON configuration resource.

   There are two methods for retrieving the JSON configuration: a
   primary method and an MX fallback method.  The primary method should
   be attempted first, with the MX fallback method used only if the
   primary method fails.

5.2.1.  Primary Source

   The primary method for retrieving configuration data uses well-known
   URIs with DNS-based digest validation.

5.2.1.1.  Well-Known Uniform Resource Identifier

   The user agent retrieves configuration data over HTTP using the
   format described in Section 4.

   Configuration retrieval uses [RFC8615] Well-Known URIs.  The user
   agent constructs the URI using the _domain_ from the user's email
   address and the _configuration name_ user-agent-configuration.  The
   detailed URI construction process is specified in [RFC8615].






Eggert & Diephouse        Expires 2 April 2026                 [Page 10]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   The domain name MUST support Internationalized Domain Names (IDNs) as
   defined in [RFC5890] and [RFC5891].  User agents MUST handle both
   Unicode labels (u-labels) and ASCII Compatible Encoding labels
   (a-labels) when processing domain names from email addresses, and
   convert them appropriately for URI construction as specified in
   [RFC5891].

   The URI follows this template:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   https://ua-auto-config.{domain}/\
     .well-known/user-agent-configuration.json

   If the user's email address' domain is foo.example.com, the user
   agent constructs the following URI:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   https://ua-auto-config.foo.example.com/\
     .well-known/user-agent-configuration.json

   This URI always uses the https scheme.  User agents MUST retrieve the
   configuration file only via https (HTTP over TLS).

   The user agent MUST validate that the connection is secured by TLS.
   See Section 7.4 for details about TLS with respect to retrieving the
   configuration.

   The media type of the configuration is application/json, and the HTTP
   server MUST set a corresponding Content-Type type header.  See
   [RFC9110].  The user agent MUST validate that the content-type of the
   returned resource is application/json.

   The HTTP server that serves the JSON configuration MUST NOT require
   any form of HTTP authentication to return the configuration.

   For example:













Eggert & Diephouse        Expires 2 April 2026                 [Page 11]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   C: GET /.well-known/user-agent-configuration.json HTTP/2
   C: Host: foo.example.com
   C: user-agent: curl/8.4.0
   C: accept: application/json
   C:

   S: HTTP/2 200
   S: server: nginx/1.25.3
   S: date: Mon, 23 Oct 2025 10:30:00 GMT
   S: content-type: application/json
   S: content-length: 1184
   S:
   S: {
   S:     "protocols": {
   S:         "jmap": {
   S: ...

5.2.1.2.  DNS-Based Digest Validation

   After retrieving the auto-configuration resource from the well-known
   URI as described in Section 5.2.1.1, the user agent MUST validate its
   integrity before use.  This validation is performed by comparing a
   locally computed digest of the resource against a digest published in
   a DNS TXT resource record (RR).

   If the validation fails, the user agent MUST ignore the auto-
   configuration resource.

5.2.1.2.1.  Validation Procedure

   The user agent MUST perform the following steps to validate the auto-
   configuration resource:

   1.  Let the "decoded message content" be the payload body of the HTTP
       response after all Transfer-Encoding (e.g., "chunked") and
       Content-Encoding (e.g., "gzip", "br") transformations have been
       reversed.  This is the final, decompressed representation of the
       resource.  See Section 6.1 of [RFC9112] and Section 8.4 of
       [RFC9110] for details on these encodings.

   2.  Construct a DNS query QNAME using the template _ua-auto-
       config.{domain}, where {domain} is the domain part of the user's
       identifier (e.g., "foo.example.com" for "jdoe@foo.example.com").

   3.  Perform a DNS query for the TXT RR type at the constructed QNAME.
       The response may contain multiple TXT RRs.

   4.  For each TXT RR returned in the DNS response:



Eggert & Diephouse        Expires 2 April 2026                 [Page 12]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


       a.  Parse the record according to the syntax in
           Section 5.2.1.2.2.  If the record is malformed or is missing
           any of the mandatory tags (v, a, d), discard this RR and
           proceed to the next one.

       b.  Let the "remote algorithm" be the value of the a tag.  If the
           user agent does not support this algorithm, discard this RR
           and proceed to the next one.

       c.  Let the "remote digest" be the Base64-decoded value of the d
           tag.  If decoding fails, discard this RR and proceed to the
           next one.

       d.  Using the "remote algorithm", compute a "local digest" of the
           "decoded message content" obtained in step 1.

       e.  Perform a byte-for-byte comparison of the "local digest" and
           the "remote digest".  If they are identical, the validation
           is successful.  The user agent MUST immediately stop
           processing further TXT RRs and MAY use the auto-configuration
           resource.

   5.  If, after checking all valid and supported TXT RRs, no match is
       found, the validation has failed.  The user agent MUST discard
       the "decoded message content" and behave as if no auto-
       configuration resource was found.

   Note: A compliant HTTP client library will typically handle the
   decoding of Transfer-Encoding and Content-Encoding transparently.
   The requirement in this document is to ensure that the digest is
   computed on the final data, not on an intermediate, encoded
   representation.

5.2.1.2.2.  DNS Resource Record for Auto-Configuration

   Configuration information for a given domain is published as a DNS
   TXT resource record (RR) at a special name, _ua-auto-config,
   prepended to the domain name.  For example, for the domain
   example.com, the lookup would be for a TXT record at _ua-auto-
   config.example.com.

5.2.1.2.2.1.  Record Syntax

   The content of the TXT RR is a string of tag=value pairs separated by
   semicolons (;).  Tags are short ASCII strings that identify a
   particular parameter.  Values are ASCII strings whose format depends
   on the tag.




Eggert & Diephouse        Expires 2 April 2026                 [Page 13]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   The formal syntax of the record is described using ABNF [RFC5234] as
   follows:

   config-record   = tag-value *( *WSP ";" *WSP tag-value ) *WSP [";"]

   tag-value       = version-tag / alg-tag / digest-tag / future-tag

   version-tag     = "v" *WSP "=" *WSP "UAAC1"
   alg-tag         = "a" *WSP "=" *WSP digest-algorithm
   digest-algorithm = "sha256" / "sha512" / "sha3-512"
   digest-tag      = "d" *WSP "=" *WSP 1*base64-char

   future-tag      = 1*tag-name *WSP "=" *WSP 1*tag-value-char

   tag-name        = ALPHA / DIGIT
   tag-value-char  = %x21-3A / %x3C-7E ; Any visible ASCII char
                                     ; except semicolon

   base64-char     = ALPHA / DIGIT / "+" / "/" / "="
   ; As defined in Section 4 of RFC 4648

   WSP             = " " / HTAB
   ; As defined in Appendix B.1 of RFC 5234

5.2.1.2.2.2.  Tags

   The following tags are defined.  Tag names are case-sensitive and
   MUST be processed as lowercase.

      +-----+------------------------------------------+-----------+
      | Tag | Description                              | Status    |
      +-----+------------------------------------------+-----------+
      | v   | Version.  The value MUST be "UAAC1" for  | Mandatory |
      |     | records compliant with this              |           |
      |     | specification.                           |           |
      +-----+------------------------------------------+-----------+
      | a   | Digest Algorithm.  The value MUST be one | Mandatory |
      |     | of "sha256", "sha512", or "sha3-512".    |           |
      |     | This identifies the algorithm used to    |           |
      |     | create the digest in the 'd' tag.        |           |
      +-----+------------------------------------------+-----------+
      | d   | Digest.  The Base64-encoded digest of    | Mandatory |
      |     | the JSON resource described in           |           |
      |     | Section 5.2.1.1.  The encoding MUST      |           |
      |     | follow Section 4 of [RFC4648].           |           |
      +-----+------------------------------------------+-----------+

                          Table 2: Defined Tags



Eggert & Diephouse        Expires 2 April 2026                 [Page 14]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.2.1.2.2.3.  Digest Algorithm

   Three digest algorithms are supported:

   *  SHA-256 ("sha256") as defined in [RFC6234]

   *  SHA-512 ("sha512") as defined in [RFC6234]

   *  SHA-3-512 ("sha3-512") as defined in [RFC8702]

   The digest is computed over the raw bytes of the JSON resource
   retrieved from the well-known URI, after any HTTP transfer or content
   encoding has been decoded.

   Servers MUST publish DNS records for both SHA-256 and SHA-512
   algorithms.  Servers MAY additionally publish records using SHA-
   3-512.

5.2.1.2.2.4.  Parsing Rules

   A client parsing the record MUST adhere to the following rules:

   *  The record MUST contain the v, a, and d tags.  If any of these
      tags are missing, the record is invalid and MUST be ignored.

   *  The order of the tags is not significant.

   *  Whitespace (WSP) is permitted on either side of the = and ;
      separators and MUST be ignored.

   *  If a tag is encountered that is not defined in this document
      (e.g., a tag from a future version), the parser MUST ignore that
      entire tag=value pair.  This allows for future extensions.

   *  If any of the mandatory tags (v, a) have values other than those
      specified in this document, the record is invalid and MUST be
      ignored.

5.2.1.2.3.  Primary Source Example

   This example demonstrates the primary configuration retrieval process
   for a user with email address user@example.com.

   The user agent performs the following steps:

   1.  Constructs the well-known URI from the email domain:





Eggert & Diephouse        Expires 2 April 2026                 [Page 15]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


      ========== NOTE: '\' line wrapping per RFC 8792 ===========

      https://ua-auto-config.example.com/\
        .well-known/user-agent-configuration.json

   2.  Retrieves the JSON configuration over HTTPS and receives:

      {
          "protocols": {
              "jmap": {
                  "url": "https://jmap.example.com/session"
              },
              "imap": {
                  "host": "imap.example.com"
              },
              "smtp": {
                  "host": "smtp.example.com"
              }
          },
          "authentication": {
              "oauth-public": {
                  "issuer": "https://auth.example.com/"
              },
              "password": true
          },
          "info": {
              "provider": {
                  "name": "Example Provider"
              }
          }
      }

   3.  Queries DNS for TXT record at _ua-auto-config.example.com and
       receives:

      ========== NOTE: '\' line wrapping per RFC 8792 ===========

      _ua-auto-config.example.com.    TXT    "v=UAAC1; a=sha256; \
        d=K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols="

   4.  Computes the SHA-256 digest of the retrieved JSON configuration
       and verifies it matches the digest in the DNS TXT record.

   5.  Since validation succeeds, the user agent may proceed to use this
       configuration for account setup.






Eggert & Diephouse        Expires 2 April 2026                 [Page 16]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.2.2.  DNS MX Fallback

   If the user agent is unable to retrieve a configuration from the
   well-known URL described in Section 5.2.1, the user agent MUST
   attempt to construct URLs for the configuration resource using DNS MX
   records as described in this section.

   Conversely, if the user agent was able to retrieve a configuration
   from the well-known URL described in Section 5.2.1, the user agent
   MUST NOT perform the fallback described in this section.

   This fallback mechanism allows user agents to discover configuration
   information when the primary method fails, using the email domain's
   MX records to identify alternative sources for the auto-configuration
   resource.

5.2.2.1.  MX Fallback Procedure

   The user agent MUST perform the following steps to retrieve
   configuration using MX records:

   1.  Verify that the email domain supports MTA Strict Transport
       Security as described in Section 5.2.2.2.  If MTA STS is not
       supported, MUST abort the MX fallback process.

   2.  Perform a DNS query for MX resource records for the email domain.

   3.  Identify all MX records that share the same highest priority
       (lowest numerical value).  For example, if the MX records have
       priorities 10, 10, and 20, the highest priority MX records are
       those with priority 10.

   4.  For each MX record identified in the previous step:

       a.  Construct a well-known URI based on the MX hostname as
           described in Section 5.2.2.3.

       b.  Retrieve the JSON auto-configuration resource from the
           constructed URI.

       c.  Validate the retrieved resource using DNS-based digest
           validation as described in Section 5.2.1.2, but using the DNS
           query name _ua-auto-config.{mx-hostname} where {mx-hostname}
           is the hostname from the MX record.







Eggert & Diephouse        Expires 2 April 2026                 [Page 17]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   5.  Verify that all successfully retrieved and validated
       configurations are bitwise identical.  If any configurations
       differ, the user agent MUST reject all configurations and treat
       the MX fallback as failed.

   6.  If at least one configuration was successfully retrieved and
       validated, and all retrieved configurations are identical, the
       user agent MAY use this configuration.

5.2.2.2.  MTA Strict Transport Security

   MTA Strict Transport Security (MTA STS) defined in [RFC8461] provides
   a way to validate MX records against a resource retrieved over HTTP
   with TLS.

   The user agent MUST validate that the email domain supports the MTA
   STS profile.  If the email domain does not support MTA STS, the user
   agent MUST NOT use any MX records to perform auto-configuration.

   When performing the HTTPS Policy Fetching outlined in Section 3.3 of
   [RFC8461], the user agent MUST use the same, strict TLS checks as for
   the auto-configuration JSON resource.  See Section 7.4 of this
   document for detail.

5.2.2.3.  MX-Based Well-Known URI

   The user agent constructs a Well-Known URI based on the MX hostname
   using this template:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   https://ua-auto-config.{mx-hostname}/\
     .well-known/user-agent-configuration.json

   For the MX hostname bar.mail.example.com, the user agent constructs
   the following URI:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   https://ua-auto-config.bar.mail.example.com/\
     .well-known/user-agent-configuration.json

   This URI construction follows the same pattern as described in
   Section 5.2.1.1, but uses the MX hostname instead of the email
   domain.  The user agent MUST apply the same TLS validation
   requirements as specified in Section 7.4.





Eggert & Diephouse        Expires 2 April 2026                 [Page 18]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.2.2.4.  MX Fallback Example

   This example demonstrates the MX fallback process for a user with
   email address user@example.com.

   First, the user agent attempts to retrieve the configuration from the
   primary well-known URI:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   https://ua-auto-config.example.com/.well-known/\
    user-agent-configuration.json

   but this fails (perhaps the server is unreachable or returns an
   error).

   The user agent then begins the MX fallback process:

   1.  The user agent verifies MTA STS support:

       a.  Queries DNS for a TXT record at _mta-sts.example.com and
           receives:

          _mta-sts.example.com.    TXT    "v=STSv1; id=20240101120000;"

       b.  Retrieves the MTA STS policy from https://mta-
           sts.example.com/.well-known/mta-sts.txt and receives:

          version: STSv1
          mode: enforce
          mx: mail1.example.com
          mx: mail2.example.com
          mx: *.backup.example.com
          max_age: 604800

       c.  Queries DNS for MX records for example.com and receives:

          example.com.    MX    10 mail1.example.com.
          example.com.    MX    10 mail2.example.com.
          example.com.    MX    20 backup.example.com.

       d.  Validates that the MX records are consistent with the MTA STS
           policy.  All MX hostnames (mail1.example.com,
           mail2.example.com, and backup.example.com) match entries in
           the policy, so MTA STS validation succeeds.






Eggert & Diephouse        Expires 2 April 2026                 [Page 19]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   2.  The user agent identifies that mail1.example.com and
       mail2.example.com both have the highest priority (10), so these
       are the MX records to process for auto-configuration.

   3.  For each highest priority MX record:

       *  For mail1.example.com:

          -  Constructs URI:

             ========== NOTE: '\' line wrapping per RFC 8792 ===========

             https://ua-auto-config.mail1.example.com/\
              .well-known/user-agent-configuration.json

          -  Retrieves the JSON configuration successfully

          -  Validates the configuration against DNS TXT record at _ua-
             auto-config.mail1.example.com

       *  For mail2.example.com:

          -  Constructs URI:

             ========== NOTE: '\' line wrapping per RFC 8792 ===========

             https://ua-auto-config.mail2.example.com/\
              .well-known/user-agent-configuration.json

          -  Retrieves the JSON configuration successfully

          -  Validates the configuration against DNS TXT record at _ua-
             auto-config.mail2.example.com

   4.  The user agent verifies that both retrieved configurations are
       bitwise identical.

   5.  Since both configurations were successfully retrieved, validated,
       and are identical, the user agent may proceed to use this
       configuration for account setup.

   If any step in this process fails (MTA STS not supported, MX records
   don't match the MTA STS policy, no MX records found, configurations
   differ, or validation fails), the user agent treats the MX fallback
   as unsuccessful and may need to prompt the user for manual
   configuration.





Eggert & Diephouse        Expires 2 April 2026                 [Page 20]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.3.  Configuration JSON Validation

   After successfully retrieving a configuration resource, user agents
   MUST validate that the configuration contains valid JSON syntax
   according to RFC 8259.  Additionally, user agents MUST validate the
   retrieved configuration against the JSON schema specification
   provided in Appendix A.  If the JSON syntax is invalid, user agents
   MUST ignore the configuration entirely and not use any portion of it.

   User agents MUST process only the properties that they support and
   MUST ignore properties not specified in the schema.  This requirement
   enables future extensions of the format without breaking existing
   user agent implementations.

5.4.  Selecting Protocols and Authentication

   After successfully retrieving and validating the configuration JSON,
   the user agent needs to determine:

   *  Which protocols to use

   *  Which authentication mechanism to employ

   Both user agents and servers support multiple protocols.  The user
   agent needs to decide which protocols to use and determine whether
   the protocols specified in the configuration are sufficient to
   proceed.  This document does not provide recommendations regarding
   protocol preferences or minimum protocol requirements, as these
   decisions depend on the specific needs and implementation details of
   individual user agents.

   The automatic configuration flow supports two distinct authentication
   types:

   *  Username and password-based authentication

   *  OAuth-based authentication

   User agents can support one or both authentication methods.
   Similarly, servers for each protocol can support one or both methods.
   Additionally, the specific implementation details of authentication
   can vary between protocols.

   User agents SHOULD probe each protocol and server of interest to
   determine compatible authentication methods.  This probing process
   can influence the user agent's protocol selection and allows the user
   agent to verify server availability.




Eggert & Diephouse        Expires 2 April 2026                 [Page 21]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   This document does not provide recommendations regarding protocol
   preferences.  The user agent MUST make these decisions based on its
   needs.

   If the user agent determines that it can use either password-based
   authentication or OAuth authentication, the user agent SHOULD prefer
   OAuth-based authentication.

5.4.1.  OAuth

   The JSON configuration includes an oauth-public entry when the
   provider supports OAuth.  The issuer value specifies the
   authorization server's issuer identifier.  According to Section 2.2
   of [OAuthPublic], the OAuth Authorization Server Metadata is served
   at a URL constructed using this issuer value with the template

   {issuer}/.well-known/oauth-authorization-server

   For example, if the JSON configuration contains this entry:

   "oauth-public" : {
       "issuer" : "https://auth.example.com"
   },

   the OAuth Authorization Server Metadata would be at the URL
   https://auth.example.com/.well-known/oauth-authorization-server

   Note that as defined in [RFC8414], the authorization server's issuer
   identifier MUST be a URL that uses the https scheme without any query
   or fragment components.  Clients MUST verify that the issuer value is
   valid according to [RFC8414].

   Before the user agent chooses to use OAuth for any protocols, it
   SHOULD make sure that it can retrieve the OAuth Authorization Server
   Metadata from the corresponding URI.

   The user agent SHOULD connect to each protocol that it might be
   interested in to detect which authentication mechanism it supports.
   The user agent MUST NOT perform any authentication at this point, but
   it SHOULD record which mechanism(s) the server for each protocol of
   interest supports.

   The user agent SHOULD still probe each server as described in the
   next sections 5.4.2 and 5.4.3 to check that the servers it is
   interested in have OAuth support.






Eggert & Diephouse        Expires 2 April 2026                 [Page 22]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.4.2.  HTTP Authentication Mechanisms

   To check which HTTP authentication schemes a particular HTTP server
   supports, the user agent SHOULD send a request to the server's
   endpoint without any Authorization header.  For example:

   GET /jmap/session HTTP/1.1
   host: api.example.com
   accept: application/json

   As detailed in [RFC9110] the server SHOULD respond to this with a 401
   Unauthorized status code and a www-authenticate response header
   indicating which authentication scheme(s) are supported.

   The user agent SHOULD include an accept header with the content type
   it would expect for the given protocol.  For JMAP, for example, the
   user agent SHOULD include accept: application/json as a header in
   this request.

   If the server supports OAuth, the www-authenticate response header
   would include Bearer.  [RFC6749] describes this in more detail.
   [RFC6750] and [RFC7616] describe username + password authentication
   using the so-called 'Basic' HTTP authentication scheme and the HTTP
   digest access authentication respectively.  Other password based
   authentication mechanisms exist for HTTP, but their discussion is
   outside the scope of this document.

   For example, a response header

   HTTP/1.1 401 Unauthorized
   www-authenticate: Bearer realm="api.example.com"

   would indicate that the server supports OAuth.

   Alternatively, a response such as

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   HTTP/1.1 401 Unauthorized
   www-authenticate: Digest realm="api.example.com", qop="auth", \
   algorithm=SHA-256, nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", \
   opaque="5ccc069c403ebaf9f0171e9517f40e41"

   would indicate that the server supports digest access authentication.







Eggert & Diephouse        Expires 2 April 2026                 [Page 23]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Details of HTTP authentication are described in [RFC9110] but it is
   worth noting that a server supporting multiple authentication methods
   can return either multiple www-authenticate header fields in its
   response or a single www-authenticate header field with multiple
   authentication methods.

5.4.3.  Other Protocols Authentication Mechanisms

   For text-based protocols (IMAP, POP3, and SMTP) the user agent SHOULD
   connect to the server to check that:

   *  the user agent can reach the server,

   *  the server implements the expected protocol, and

   *  which authentication mechanisms the server supports.

   The user agent MUST attempt to connect to the server on the default
   ports:

   *  port 993 for IMAP

   *  port 995 for POP3

   *  port 465 for SMTP

   using TLS.  See [RFC2595] and [RFC3207] for details about using TLS
   with these protocols.

   The user agent SHOULD NOT attempt to connect to an IMAP, POP3, or
   SMTP server on their cleartext ports.

   The user agent MUST NOT allow for configuration with a cleartext
   protocol that is not protected by TLS.

   The user agent MUST validate that the connection is secured by TLS,
   and that the server certificate is valid and matches the expected
   domain name.  See Section 7.4 for details on transport security
   validation.

   If the server announces the OAUTHBEARER SASL authentication method,
   the user agent can assume that this server supports using
   [OAuthPublic].  For IMAP for example, if the server's CAPABILITY
   contains AUTH=OAUTHBEARER this would indicate this support.







Eggert & Diephouse        Expires 2 April 2026                 [Page 24]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Servers SHOULD NOT announce support for the OAUTHBEARER SASL
   mechanism if they do not support [OAuthPublic].  Servers MUST
   announce support for the OAUTHBEARER SASL mechanism if they support
   OAuth Profile for Open Public Clients.  Servers SHOULD NOT use the
   XOAUTH2 SASL mechanism.

   There are various SASL authentication mechanisms for password-based
   authentication, and additionally IMAP and POP3 also support password-
   based authentication through LOGIN and APOP respectively.  The user
   agent needs to probe each server to determine which authentication
   methods are supported by both the user agent and the server.

5.4.3.1.  IMAP

   The IMAP protocol provides various other authentication mechanisms.
   There are various SASL mechanisms for username + password
   authentication.  [RFC4959] describes how to use SASL with IMAP.

   Unless the server sends the LOGINDISABLED capability, clients know
   that they can use the LOGIN command for username + password
   authentication.

   For IMAP, a sample session might look like this:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   S: * OK [CAPABILITY IMAP4 IMAP4rev1 SASL-IR AUTH=PLAIN \
   AUTH=OAUTHBEARER] IMAP Server
   C: A1 LOGOUT
   S: * BYE
   S: A1 OK

   In this case the server returned its IMAP capabilities as part of the
   so-called greeting messages.  The support for the OAUTHBEARER SASL
   authentication mechanism indicates to the client that the server
   supports OAuth.  Similarly the PLAIN SASL authentication mechanism
   indicates that the server supports username + password
   authentication.  The absence of the LOGINDISABLED also indicates
   support for username and password authentication.

   If the server doesn't include its capabilities in the server
   greeting, the client SHOULD send a CAPABILITY command as outlined in
   Section 6.1.1 of [RFC9051].  The client SHOULD send a LOGOUT command
   as outlined in Section 6.1.3 of [RFC9051] and check that the server
   sends an untagged BYE response.






Eggert & Diephouse        Expires 2 April 2026                 [Page 25]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


5.4.3.2.  SMTP

   SMTP similarly announces which authentication mechanisms is supports.
   [RFC4954] describes how to use SASL with SMTP.

   For SMTP, the client would use the EHLO command to retrieve the SMTP
   server's supported authentication mechanisms.  For example:

   S: 220 smtp.example.com ESMTP service ready
   C: EHLO client.example.com
   S: 250-smtp.example.com
   S: 250-PIPELINING
   S: 250-SIZE 10240000
   S: 250-AUTH PLAIN LOGIN OAUTHBEARER
   S: 250-ENHANCEDSTATUSCODES
   S: 250 8BITMIME
   C: QUIT
   S: 221 Bye

   Section 3.2 of [RFC5321] describe this client initiation of the SMTP
   protocol.  [RFC4954] describes SMTP authentication in detail.  In the
   above example PLAIN and LOGIN indicate that the server supports
   username + password based authentication, and OAUTHBEARER indicates
   that the server supports OAuth.

   The client SHOULD send a QUIT command and check for the server's 221
   Bye response.

5.4.3.3.  POP3

   For POP3 [RFC5034] describes how to use SASL.  POP3 additionally
   supports password based authentication using its USER and PASS
   commands, or through the optional APOP command.  The client can check
   which SASL authentication methods the server supports using the CAPA
   command.

   For example:

   S: +OK pop.example.com POP3 server ready
   C: CAPA
   S: +OK List of capabilities follows
   S: SASL PLAIN OAUTHBEARER
   S: IMPLEMENTATION BlurdyBlurp POP3 server
   S: .
   C: QUIT
   S: +OK POP3 server signing off (maildrop empty)





Eggert & Diephouse        Expires 2 April 2026                 [Page 26]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   The client SHOULD send a QUIT command and check for the server's +OK
   response.

5.5.  Confirming Server Names

   The client SHOULD display to the user the hostnames of all servers
   that it intends to authenticate with.  This list of server hostnames
   gives the user a chance to validate if they want to move ahead.

   The client MAY choose to limit the hostnames to their second-level
   domain names when displaying this list.  Instead of displaying
   mail.example.com the client would display example.com if it chooses
   to do so.  Limiting the hostnames to their second-level domain names
   helps users identify if this is the domain they intend to connect to
   or not.

   The client MUST NOT cut off parts of long second-level domains, to
   avoid spoofing.  At least 63 characters of the second-level domain
   names MUST be displayed.

   If the user mistyped their email address in Section 5.1, letting the
   user confirm the server hostnames gives the user a chance to notice
   this.

   Clients can enhance the user experience by using the info section of
   the configuration (described in Section 4.4) to display the
   provider's name and logo during this configuration step.

   Section 7.1 list security considerations related to the user
   confirming these hostnames.

5.6.  Username

   For password-based authentication, the full addr-spec part of the
   email address MUST be used as the username.  For example:

             +============================+==================+
             | Text Entered by User       | username         |
             +============================+==================+
             | jdoe@example.com           | jdoe@example.com |
             +----------------------------+------------------+
             | "J Doe" <jdoe@example.com> | jdoe@example.com |
             +----------------------------+------------------+
             | <jdoe@example.com>         | jdoe@example.com |
             +----------------------------+------------------+

                    Table 3: Username from email address




Eggert & Diephouse        Expires 2 April 2026                 [Page 27]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   For OAuth Profile for Open Public Clients, the client MUST send this
   username as the login_hint in the authorization request URL.

   The provider MUST ensure that any valid email address that the user
   might enter during setup is a valid username for all servers given in
   this configuration.  This will require a mapping on the server level
   from email address to internal username.  This mapping happens
   internally in the server and the client is not involved in this
   mapping.

5.7.  Configuring OAuth

   If the client and the provider both support OAuth Profile for Open
   Public Clients, and if the servers that the client wants to use
   support OAuth, the client can configure OAuth.

   The authentication section in the JSON configuration described in
   Section 4.3 will let the client create a URL to retrieve the OAuth
   Authorization Server Metadata as described in section Section 5.4.1.
   With this metadata, the client can then use [OAuthPublic] to
   configure OAuth.

   Part of this will require opening the authorization request URL in an
   external user-agent, which is typically the default browser.  The
   client SHOULD make it very apparent to the user which hostname is
   being used for the authorization request URL.  The client SHOULD make
   the user confirm least the second-level domain name(s) of the
   hostname of this URL.  This is to minimize the risk of the user
   exposing their credentials to a third party.

   As described in Section 5.5, the client SHOULD also confirm the
   server hostnames with the user.  For OAuth authentication, the client
   SHOULD include the hostname of the authorization request URL in this
   list of hostnames.

5.8.  Configuring Password-Based Authentication

   If the client and provider both support password-based
   authentication, and if the servers that the client wants to use
   support password-based authentication, the client can configure
   itself to use these servers.

   The client SHOULD at this point ask the user for the password for
   their account with the provider.







Eggert & Diephouse        Expires 2 April 2026                 [Page 28]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Once the user has entered their password, the client SHOULD validate
   that it is able to authenticate using the entered password with all
   servers that it is interested in.  Only then would it save the new
   configuration.

6.  Configuration Validation

6.1.  User Approval

   Regardless of the mechanism used to obtain the configuration, clients
   SHOULD display the configuration details to users and request
   explicit confirmation before use.  During this confirmation process:

   *  At least the second-level domain names of all involved hostnames
      MUST be displayed clearly and prominently.

   *  Clients MUST NOT truncate long second-level domain names to
      prevent spoofing attacks.  At least 63 characters MUST be
      displayed.

6.2.  OAuth2 requirements

   If OAuth2 is used, the OAuth2 server MUST adhere to [OAuthPublic].

   Notably, the Dynamic Client Registration MUST be implemented and
   return a working Client ID in response HTTP calls defined by the
   specification.

   The OAuth2 scopes defined in [OAuthPublic] MUST be included and MUST
   give access to the servers returned in the JSON configuration
   described in Section 4.

   A single token MUST work for all servers in the JSON configuration,
   such that a single user login is sufficient for all services.  For
   that purpose, the client will include all relevant scopes in the
   authentication requests.

7.  Security Considerations

   While the mechanism described in this document makes it easier for
   users to correctly configure their user agent, there's an associated
   risk with making it easier for users to expose their credentials to a
   third party.

   User agents using the mechanism described in this document need to
   design their user interface and user experience such that this risk
   is minimized.  Actual affordances depend on implementation details of
   the user interface and are outside the scope of this document.



Eggert & Diephouse        Expires 2 April 2026                 [Page 29]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


7.1.  Mistyped Domain Names

   As part of the first step of the mechanism described in this
   document, the user enters their email address.  If the user mistyped
   the domain part of their email address, and if the mistyped domain
   exists and supports the mechanism described in this document, the
   user could expose their credentials to the owner of that domain.  An
   attacker could use this in an attempt to gain knowledge of the user's
   credentials.

   As a result, user agents need to carefully design their user
   interface and user experience as to let the user know which domain is
   being used.  It would make sense to display this very clearly to the
   user, before they enter any credentials.

   The user agent would want to display a list of all second-level
   domains (SLDs) for all the servers that it intends to use.  The user
   can then confirm these.

   When the mechanism described in this document uses OAuth, it would
   make sense to ask the user to confirm the domains of the servers that
   will be used and additionally confirm the domains of

   *  the URL to retrieve the OAuth Authorization Server Metadata and/or

   *  the authorization request URL.

   When asking the user to confirm these domains, it would make sense to
   only display the second-level domain (SLD) of those domains.  This
   would make it more difficult for an attacker to do URL obfuscation
   and use subdomain phishing.

   When using a browser for OAuth, the user agent would want to display
   the second-level domain (SLD) that the browser is currently
   displaying, and update this when redirects happen or new pages are
   loaded.

7.2.  Attacker Controlled JSON Configuration

   If an attacker can direct the user agent to use an attacker-
   controlled JSON configuration, the attacker would be able to direct
   the user to servers of the attacker's choosing.

   In Section 7.1 some mechanisms to limit this attack vector are
   described.

   However, the user agent needs to combine this with a conservative
   trust policy for its TLS when retrieving the JSON configuration.



Eggert & Diephouse        Expires 2 April 2026                 [Page 30]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


7.3.  DNS

   If the user agent uses the DNS mechanisms described in
   Section 5.2.1.2, care needs to be taken to make sure that an attacker
   hasn't altered the DNS response.  Using DNSSEC is one method of
   improving the security aspects of this approach.  Alternatively, user
   agents MAY choose not use the DNS based mechanisms described in
   Section 5.2.1.2 at all.

7.4.  Transport Security Validation

   Whenever secure transport is used (including TLS for HTTPS
   connections and QUIC's TLS-based security layer for HTTP/3), user
   agents MUST check the certificates presented by the server.  This
   certificate MUST be within its validity period (prior to its
   expiration date) and MUST chain to a root CA that is trusted by the
   user agent.  The certificate MUST have a subject alternative name
   (SAN) ([RFC5280]) with a DNS-ID ([RFC9525]) matching the hostname,
   per the rules given in [RFC9525].  The certificate MAY also be
   checked for revocation via OCSP ([RFC6960]), CRLs ([RFC6818]), or
   some other mechanism.  The general TLS usage guidance in [RFC9525]
   SHOULD be followed.

   If these checks fail or the server certificate is otherwise invalid,
   the user agent MUST disconnect and MUST NOT use any configuration
   retrieved from that URI.

   Certificate validation failures represent significant security risks,
   as they may indicate attempts to redirect users' credentials to an
   attacker.  User agents SHOULD NOT allow users to override certificate
   validation checks.

   User agents MAY implement more restrictive transport security
   policies for configuration retrieval than those typically required
   for web browsing, in order to provide stronger security guarantees.
   For TLS connections, user agents MAY want to limit the allowed
   protocol version(s) to recent versions, and MAY similarly want to
   restrict the allowed cipher suites.  For QUIC connections, user
   agents MAY apply similar restrictions to the underlying TLS handshake
   parameters.

   The HTTP server serving the Well-Known resource described in
   Section 5.2.1.1 MUST have support for TLS 1.3 ([RFC8446]) or higher.








Eggert & Diephouse        Expires 2 April 2026                 [Page 31]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


7.5.  Updating the Configuration

   The mechanism described in this document can be used to upgrade a
   user's configuration.  The user agent could check for configurations
   even when it has a working configuration for an account.  If the user
   agent finds a configuration that is better (in some way) than the
   already existing configuration, it could then upgrade the existing
   configuration.

   But in doing so, the user agent would increase the attack window that
   a potential attacker has.  Instead of only giving an attacker the
   opportunity when the user configures their user agent for the first
   time, the attacker would now have an opportunity each time the user
   agent checks for a better configuration.  That could be undesirable.

7.6.  Provider Information

   Image parsers are a common attack vector, and clients MUST NOT
   display the logo images described in Section 4.4.1 unless they can do
   so in a way that doesn't expose the client to such attacks.

8.  IANA Considerations

8.1.  The User-Agent Auto-Configuration Protocol Registry

   This document establishes the user-agent auto-configuration protocol
   registry.

   User-agent auto-configuration protocols are registered on the advice
   of one or more Designated Experts (appointed by the IESG or their
   delegate), with a Specification Required (using terminology from
   [RFC8126]).  However, to allow for the allocation of values prior to
   publication, the Designated Expert(s) may approve registration once
   they are satisfied that such a specification will be published.

   Registration requests are sent to the ____@ietf.org mailing list for
   review and comment, with an appropriate subject (e.g., "Request for
   well-known URI: example").

   Before a period of 14 days has passed, the Designated Expert(s) will
   either approve or deny the registration request, communicating this
   decision both to the review list and to IANA.  Denials should include
   an explanation and, if applicable, suggestions as to how to make the
   request successful.  Registration requests that are undetermined for
   a period longer than 21 days can be brought to the IESG's attention
   (using the iesg@iesg.org mailing list) for resolution.





Eggert & Diephouse        Expires 2 April 2026                 [Page 32]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   Registry Name:
      User-Agent Auto-Configuration Protocols

   Registration Procedure:
      Specification Required (per [RFC8126])

8.1.1.  Registration Template

   Name
      The commonly used name of the protocol

   Protocol Key:
      The JSON key using in the protocols object in the JSON
      configuration described in Section 4

   URL Scheme:
      (Optional) The URL scheme to be used for this protocol.  HTTP
      based protocols specify https.  If left empty, the protocols entry
      in the JSON configuration will only specify a hostname using host.
      If a URL scheme is specified, the JSON configuration entry will
      instead use url with a URL using this URL scheme.

   Specification
      Which RFC(s) or document(s) specify the protocol

   Additional Properties:
      Which additional property values are present in the protocol's
      JSON object.

8.1.2.  Initial Registrations

   +=============+=============+========+================+============+
   | Name        | Protocol    | URL    | Specification  | Additional |
   |             | Key         | scheme |                | Properties |
   +=============+=============+========+================+============+
   | JMAP        | jmap        | https  | RFC 8620, RFC  |            |
   |             |             |        | 8621, RFC      |            |
   |             |             |        | 8887, RFC 9610 |            |
   +-------------+-------------+--------+----------------+------------+
   | IMAP        | imap        |        | RFC 9051       |            |
   +-------------+-------------+--------+----------------+------------+
   | POP3        | pop3        |        | RFC 1939, RFC  |            |
   |             |             |        | 5034           |            |
   +-------------+-------------+--------+----------------+------------+
   | SMTP        | smtp        |        | RFC 5321, RFC  |            |
   |             |             |        | 2822           |            |
   +-------------+-------------+--------+----------------+------------+
   | CalDAV      | caldav      | https  | RFC 4791       |            |



Eggert & Diephouse        Expires 2 April 2026                 [Page 33]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   +-------------+-------------+--------+----------------+------------+
   | CardDAV     | carddav     | https  | RFC 6352       |            |
   +-------------+-------------+--------+----------------+------------+
   | WebDAV      | webdav      | https  | RFC 4918       |            |
   +-------------+-------------+--------+----------------+------------+
   | ManageSieve | managesieve |        | RFC 5804, RFC  |            |
   |             |             |        | 5228           |            |
   +-------------+-------------+--------+----------------+------------+

          Table 4: Initial registrations to the User-Agent Auto-
                     Configuration Protocol Registry

   The _Additional Properties_ field is empty in all of the initial
   values.

8.2.  Registration

8.2.1.  Registration of Well-Known URI user-agent-configuration

   This registers the user-agent-configuration name from Section 5.2.1.1
   in the "Well-Known URIs" registry as specified in [RFC8615].

    +==========================+==========+===============+===========+
    | URI suffix               |Change    | Specification |Related    |
    |                          |controller| document(s)   |information|
    +==========================+==========+===============+===========+
    | user-agent-configuration |IETF      | This document |/          |
    +--------------------------+----------+---------------+-----------+

             Table 5: Registration in Well-Known URIs Registry

8.2.2.  Registration of DNS Underscore Label _ua-auto-config

   This registers the DNS underscore label _ua-auto-config used in
   Section 5.2.1.2 in the "Underscored and Globally Scoped DNS Node
   Names" registry as specified in [RFC8552].

               +=========+=================+===============+
               | RR Type | _NODE NAME      | Reference     |
               +=========+=================+===============+
               | TXT     | _ua-auto-config | This document |
               +---------+-----------------+---------------+

                  Table 6: Registration in Underscored and
                  Globally Scoped DNS Node Names Registry

9.  Normative References




Eggert & Diephouse        Expires 2 April 2026                 [Page 34]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   [RFC1939]  Myers, J. and M. Rose, "Post Office Protocol - Version 3",
              STD 53, RFC 1939, DOI 10.17487/RFC1939, May 1996,
              <https://www.rfc-editor.org/info/rfc1939>.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
              <https://www.rfc-editor.org/info/rfc2045>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC2595]  Newman, C., "Using TLS with IMAP, POP3 and ACAP",
              RFC 2595, DOI 10.17487/RFC2595, June 1999,
              <https://www.rfc-editor.org/info/rfc2595>.

   [RFC3207]  Hoffman, P., "SMTP Service Extension for Secure SMTP over
              Transport Layer Security", RFC 3207, DOI 10.17487/RFC3207,
              February 2002, <https://www.rfc-editor.org/info/rfc3207>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

   [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
              "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
              DOI 10.17487/RFC4791, March 2007,
              <https://www.rfc-editor.org/info/rfc4791>.

   [RFC4918]  Dusseault, L., Ed., "HTTP Extensions for Web Distributed
              Authoring and Versioning (WebDAV)", RFC 4918,
              DOI 10.17487/RFC4918, June 2007,
              <https://www.rfc-editor.org/info/rfc4918>.

   [RFC4954]  Siemborski, R., Ed. and A. Melnikov, Ed., "SMTP Service
              Extension for Authentication", RFC 4954,
              DOI 10.17487/RFC4954, July 2007,
              <https://www.rfc-editor.org/info/rfc4954>.

   [RFC4959]  Siemborski, R. and A. Gulbrandsen, "IMAP Extension for
              Simple Authentication and Security Layer (SASL) Initial
              Client Response", RFC 4959, DOI 10.17487/RFC4959,
              September 2007, <https://www.rfc-editor.org/info/rfc4959>.






Eggert & Diephouse        Expires 2 April 2026                 [Page 35]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   [RFC5034]  Siemborski, R. and A. Menon-Sen, "The Post Office Protocol
              (POP3) Simple Authentication and Security Layer (SASL)
              Authentication Mechanism", RFC 5034, DOI 10.17487/RFC5034,
              July 2007, <https://www.rfc-editor.org/info/rfc5034>.

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
              <https://www.rfc-editor.org/info/rfc5280>.

   [RFC5321]  Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
              DOI 10.17487/RFC5321, October 2008,
              <https://www.rfc-editor.org/info/rfc5321>.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              DOI 10.17487/RFC5322, October 2008,
              <https://www.rfc-editor.org/info/rfc5322>.

   [RFC5804]  Melnikov, A., Ed. and T. Martin, "A Protocol for Remotely
              Managing Sieve Scripts", RFC 5804, DOI 10.17487/RFC5804,
              July 2010, <https://www.rfc-editor.org/info/rfc5804>.

   [RFC5890]  Klensin, J., "Internationalized Domain Names for
              Applications (IDNA): Definitions and Document Framework",
              RFC 5890, DOI 10.17487/RFC5890, August 2010,
              <https://www.rfc-editor.org/info/rfc5890>.

   [RFC5891]  Klensin, J., "Internationalized Domain Names in
              Applications (IDNA): Protocol", RFC 5891,
              DOI 10.17487/RFC5891, August 2010,
              <https://www.rfc-editor.org/info/rfc5891>.

   [RFC6234]  Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
              (SHA and SHA-based HMAC and HKDF)", RFC 6234,
              DOI 10.17487/RFC6234, May 2011,
              <https://www.rfc-editor.org/info/rfc6234>.

   [RFC6352]  Daboo, C., "CardDAV: vCard Extensions to Web Distributed
              Authoring and Versioning (WebDAV)", RFC 6352,
              DOI 10.17487/RFC6352, August 2011,
              <https://www.rfc-editor.org/info/rfc6352>.




Eggert & Diephouse        Expires 2 April 2026                 [Page 36]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <https://www.rfc-editor.org/info/rfc6749>.

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012,
              <https://www.rfc-editor.org/info/rfc6750>.

   [RFC6818]  Yee, P., "Updates to the Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 6818, DOI 10.17487/RFC6818, January
              2013, <https://www.rfc-editor.org/info/rfc6818>.

   [RFC6960]  Santesson, S., Myers, M., Ankney, R., Malpani, A.,
              Galperin, S., and C. Adams, "X.509 Internet Public Key
              Infrastructure Online Certificate Status Protocol - OCSP",
              RFC 6960, DOI 10.17487/RFC6960, June 2013,
              <https://www.rfc-editor.org/info/rfc6960>.

   [RFC7616]  Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
              Digest Access Authentication", RFC 7616,
              DOI 10.17487/RFC7616, September 2015,
              <https://www.rfc-editor.org/info/rfc7616>.

   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/info/rfc8126>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8414]  Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
              Authorization Server Metadata", RFC 8414,
              DOI 10.17487/RFC8414, June 2018,
              <https://www.rfc-editor.org/info/rfc8414>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC8461]  Margolis, D., Risher, M., Ramakrishnan, B., Brotman, A.,
              and J. Jones, "SMTP MTA Strict Transport Security (MTA-
              STS)", RFC 8461, DOI 10.17487/RFC8461, September 2018,
              <https://www.rfc-editor.org/info/rfc8461>.




Eggert & Diephouse        Expires 2 April 2026                 [Page 37]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   [RFC8552]  Crocker, D., "Scoped Interpretation of DNS Resource
              Records through "Underscored" Naming of Attribute Leaves",
              BCP 222, RFC 8552, DOI 10.17487/RFC8552, March 2019,
              <https://www.rfc-editor.org/info/rfc8552>.

   [RFC8615]  Nottingham, M., "Well-Known Uniform Resource Identifiers
              (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
              <https://www.rfc-editor.org/info/rfc8615>.

   [RFC8620]  Jenkins, N. and C. Newman, "The JSON Meta Application
              Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
              2019, <https://www.rfc-editor.org/info/rfc8620>.

   [RFC8702]  Kampanakis, P. and Q. Dang, "Use of the SHAKE One-Way Hash
              Functions in the Cryptographic Message Syntax (CMS)",
              RFC 8702, DOI 10.17487/RFC8702, January 2020,
              <https://www.rfc-editor.org/info/rfc8702>.

   [RFC9051]  Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
              Access Protocol (IMAP) - Version 4rev2", RFC 9051,
              DOI 10.17487/RFC9051, August 2021,
              <https://www.rfc-editor.org/info/rfc9051>.

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/info/rfc9110>.

   [RFC9112]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
              June 2022, <https://www.rfc-editor.org/info/rfc9112>.

   [RFC9525]  Saint-Andre, P. and R. Salz, "Service Identity in TLS",
              RFC 9525, DOI 10.17487/RFC9525, November 2023,
              <https://www.rfc-editor.org/info/rfc9525>.

   [I-D.svg-tiny-ps-abrotman]
              Brotman, A. and J. T. Adams, "SVG Tiny Portable/Secure",
              Work in Progress, Internet-Draft, draft-svg-tiny-ps-
              abrotman-10, 1 May 2025,
              <https://datatracker.ietf.org/doc/html/draft-svg-tiny-ps-
              abrotman-10>.









Eggert & Diephouse        Expires 2 April 2026                 [Page 38]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


   [OAuthPublic]
              Jenkins, N. and B. Bucksch, "OAuth Profile for Open Public
              Clients", Work in Progress, Internet-Draft, draft-ietf-
              mailmaint-oauth-public,
              <https://datatracker.ietf.org/doc/html/draft-ietf-
              mailmaint-oauth-public>.

Appendix A.  Configuration JSON Schema

   The following JSON schema defines the format of the JSON
   configuration in Section 4

   ========== NOTE: '\' line wrapping per RFC 8792 ===========

   {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "$id": "ua-auto-conf",
       "title": "User-Agent Automatic Configuration",
       "description": "Automatic Configuration of Email, Calendar, \
           and Contact Server Settings",
       "type": "object",
       "properties": {
           "protocols": {
               "type": "object",
               "properties": {
                   "caldav": { "$ref": "#/$defs/http-server" },
                   "carddav": { "$ref": "#/$defs/http-server" },
                   "imap": { "$ref": "#/$defs/text-server" },
                   "jmap": { "$ref": "#/$defs/http-server" },
                   "managesieve": { "$ref": "#/$defs/text-server" },
                   "pop3": { "$ref": "#/$defs/text-server" },
                   "smtp": { "$ref": "#/$defs/text-server" },
                   "webdav": { "$ref": "#/$defs/http-server" }
               }
           },
           "authentication": {
               "properties": {
                   "oauth-public": {
                       "properties": {
                           "issuer": {
                               "format": "uri",
                               "type": "string"
                           }
                       },
                       "required": [
                           "issuer"
                       ],
                       "type": "object"



Eggert & Diephouse        Expires 2 April 2026                 [Page 39]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


                   },
                   "password": {
                       "type": "boolean"
                   }
               },
               "required": [ "password" ]
           },
           "info": {
               "type": "object",
               "properties": {
                   "provider": {
                       "type": "object",
                       "properties": {
                           "name": { "type": "string", "minLength": 1 },
                           "shortName": { "type": "string", \
                               "minLength": 1 },
                           "logo": {
                               "type": "array",
                               "items": {
                                   "type": "object",
                                   "properties": {
                                       "url": { "type": "string", \
                                           "format": "uri" },
                                       "content-type": { \
                                           "type": "string", \
                                           "minLength": 1 },
                                       "width": { "type": "integer", \
                                           "minimum": 1 },
                                       "height": { "type": "integer", \
                                           "minimum": 1 }
                                   },
                                   "required": [ "url", "content-type" ]
                               }
                           }
                       },
                       "required": [ "name" ]
                   },
                   "help": {
                       "type": "object",
                       "properties": {
                           "documentation": { "type": "string", \
                               "format": "uri" },
                           "developer": { "type": "string", \
                               "format": "uri" },
                           "contact": {
                               "type": "array",
                               "items": { "type": "string", \
                                   "minLength": 1 }



Eggert & Diephouse        Expires 2 April 2026                 [Page 40]

Internet-Draft    Auto-Config of Email Server Settings    September 2025


                           }
                       }
                   }
               },
               "required": [ "provider" ]
           }
       },
       "required": [ "protocols", "info" ],
       "$defs": {
           "http-server": {
               "type": "object",
               "properties": {
                   "url": { "type": "string", "format": "uri" }
               },
               "required": ["url"]
           },
           "text-server": {
               "type": "object",
               "properties": {
                   "host": { "type": "string", "format": "hostname" }
               },
               "required": ["host"]
           }
       }
   }

Acknowledgements

   This document is based on the work of Ben Bucksch.

Authors' Addresses

   Daniel Eggert
   Apple Inc
   One Apple Park Way
   Cupertino,  CA 95014
   United States of America
   Email: deggert@apple.com
   URI:   https://www.apple.com


   Matt Diephouse
   Apple Inc
   One Apple Park Way
   Cupertino,  CA 95014
   United States of America
   Email: diephouse@apple.com
   URI:   https://www.apple.com



Eggert & Diephouse        Expires 2 April 2026                 [Page 41]


name: draft-tojens-dhcp-option-concat-considerations
rev: 01
title: DHCP Option Concatenation Considerations
time: 2025-09-04T07:09:37Z
group_uri: /api/v1/group/group/1027/
expires: 2025-09-04T23:36:02Z
states: ["/api/v1/doc/state/2/", "/api/v1/doc/state/150/"]
categories: ["Data formats/interop"]
tags: []
fetched_at: 2026-02-27T22:56:05.127607+00:00
abstract:
DHCP has a length limit of 255 on individual options because of its
   one-byte length field for options.  To accommodate longer options,
   splitting option data across multiple instances of the same Option
   Type is defined by RFC 3396.  However, this mechanism was defined to
   require support for all option types.  This has led to real-world
   implementations in the years since the RFC was published to deviate
   from these requirements to avoid breaking basic functionality.  This
   document updates RFC 3396 to be more flexible regarding when DHCP
   agents are required to concatenate options to reflect deployement
   experiences.

full_text:
dhc                                                            T. Jensen
Internet-Draft                                                 M. Justel
Updates: 3396 (if approved)                                    Microsoft
Intended status: Informational                              3 March 2025
Expires: 4 September 2025


                DHCP Option Concatenation Considerations
           draft-tojens-dhcp-option-concat-considerations-01

Abstract

   DHCP has a length limit of 255 on individual options because of its
   one-byte length field for options.  To accommodate longer options,
   splitting option data across multiple instances of the same Option
   Type is defined by RFC 3396.  However, this mechanism was defined to
   require support for all option types.  This has led to real-world
   implementations in the years since the RFC was published to deviate
   from these requirements to avoid breaking basic functionality.  This
   document updates RFC 3396 to be more flexible regarding when DHCP
   agents are required to concatenate options to reflect deployement
   experiences.

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 4 September 2025.

Copyright Notice

   Copyright (c) 2025 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.



Jensen & Justel         Expires 4 September 2025                [Page 1]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   3
   3.  Previous Definition of Concatenation  . . . . . . . . . . . .   3
   4.  Implementation Challenges . . . . . . . . . . . . . . . . . .   3
   5.  What Concatenation Intends to Achieve . . . . . . . . . . . .   4
   6.  Changes to How Options are Split  . . . . . . . . . . . . . .   4
   7.  Changes to How Options are Concatenated . . . . . . . . . . .   4
     7.1.  Duplicates of Options with Defined Concatenation
           Behavior  . . . . . . . . . . . . . . . . . . . . . . . .   4
     7.2.  Duplicates of Fixed-length Options  . . . . . . . . . . .   5
     7.3.  Duplicates of Multiple-of-fixed-length Options  . . . . .   5
     7.4.  Duplicates of Arbitrary-length Options  . . . . . . . . .   5
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     10.1.  Normative References . . . . . . . . . . . . . . . . . .   6
     10.2.  Informative References . . . . . . . . . . . . . . . . .   6
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   7
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Introduction

   [RFC3396] defines how DHCP agents are to split and concatenate option
   data within an DHCP message.  This has proven to be valuable as more
   DHCP options are defined that require support for concatenation as
   their data can exceed the 255 octet limit for options.  Examples
   include [RFC4702], [RFC6731] (as a MAY), [RFC7291], [RFC8572],
   [RFC8973], and [RFC9463].

   However, the way that [RFC3396] defined concatenation is not the way
   it is supported by major DHCP agent implementations today.
   Additionally, [RFC3396] allows for non-sensical deployments, such as
   handling multiple Lease Times, because it requires concatenations
   whenever any option is duplicated.  As a result, new or existing
   implementors of DHCP will find real-world behavior differs from the
   documented standard.







Jensen & Justel         Expires 4 September 2025                [Page 2]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


   This document updates [RFC3396] to clarify how option concatenation
   works in practice along with why it needs to differ from the previous
   standard.  It is not intended to invent new DHCP mechanisms; rather,
   it clarifies with the benefit of hindsight how DHCP behaves in
   practice and what implementors need to account for.

2.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Previous Definition of Concatenation

   [RFC3396] defines the terms "concatenation-requiring" and "non-
   concatenation-requiring" to describe DHCP Options.  While at multiple
   points in the document it requires implementors to handle
   concatenation of Options defined as concatenation-requiring, it also
   contains the following text which effectively requires implementors
   to handle concatenation of either Option type:

   "However, an implementation which supports any concatenation-
   requiring option MUST be capable of concatenating received options
   for both concatenation-requiring and non-concatenation-requiring
   options."

4.  Implementation Challenges

   In combination with the only permitted use of duplicate instances of
   an option type in the same DHCP message being option data splitting
   that then requires concatenation, this means that there is no way to
   recover from real-world DHCP deployment mistakes that can otherwise
   be handled under Jon Postel's Robustness Principle [RFC791].

   For example, if a DHCP server sends two instances of an option type
   with fixed length, such as Option 51 (IP Address Lease Time)
   [RFC2132], concatenating these into an eight-octet payload will
   result in a protocol violation: Option 51 has to be four octets long
   exactly.  In common deployments of DHCP agents today, we observe that
   this situation is handled by choosing one of the option instances
   that has the correct length to accept as the Option 51 value and
   ignoring the other instances.  If implementations decided instead to
   strictly adhere to always concatenating multiple instances of the
   same option type, this would entirely block IPv4 network connectivity
   for the network stack.




Jensen & Justel         Expires 4 September 2025                [Page 3]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


5.  What Concatenation Intends to Achieve

   DHCP option concatenation is intended to allow option data to exceed
   the 255 octet limit imposed by its single-octet length field.  This
   can also be used for splitting options across DHCP message section
   boundaries when the Overload Option indicates that the sname field,
   file field, or both also contain option data.

6.  Changes to How Options are Split

   To support the intention of option concatenation without causing the
   challenges described in (Section 4), this document updates [RFC3396]
   to limit concatenation to concatenation-requiring options.  DHCP
   agents SHOULD NOT provide multiple instances of an option type unless
   that option type is defined as concatenation-requiring.  To split
   non-concatenation-requiring options is out-of-spec behavior that
   leads to implementation-specific message processing.

7.  Changes to How Options are Concatenated

   When DHCP agents receive messages with split options that are
   concatenation- required options, they MUST concatenate the duplicate
   concatenation-required options as described in [RFC3396].

   If DHCP agents sending messages never split non-concatenation-
   requiring options, no further guidance would be needed.  However,
   real-world deployments have seen out-of-spec behavior that clients
   may wish to be defensive against and liberal in parsing.  Therefore,
   when DHCP agents receive messages with split options that are not
   concatenation-requiring options, they MAY make best-effort attempts
   to interpret the message or fail processing entirely as a protocol
   error.  This is implementation-specific, though some reasonable
   suggestions are broken down in this section based on four types of
   situations involving non-concatenation- requiring options still being
   split (even though they should not be).

7.1.  Duplicates of Options with Defined Concatenation Behavior

   Some non-concatenation-requiring options may still define how they
   are to be processed when DHCP agents receive multiple instances of
   the option type.  In this case, DHCP agents SHOULD follow the
   guidance defined by the option's standard.









Jensen & Justel         Expires 4 September 2025                [Page 4]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


7.2.  Duplicates of Fixed-length Options

   Fixed-length options are options that only allow a single length
   value, such as Option 51 Lease Time which can only be four octets
   long.  DHCP agents receiving messages with more than one instance of
   fixed-length non-concatenation-requiring options MAY choose to
   attempt processing one of the instances if it has the correct length.

7.3.  Duplicates of Multiple-of-fixed-length Options

   Multiple-of-fixed-length options are options that are lists of fixed-
   length elements, such as Option 6 DNS Name servers which MUST be a
   multiple of four octets long.  DHCP agents receiving messages with
   more than one instance of multiple-of-fixed-length options MAY choose
   to attempt processing one of the instances if it has a correct
   length.

   It MAY also choose to concatenate the options if the length of the
   concatenated option data is a correct length (which may indicate a
   need to split a long list because the total length is longer than 255
   octets).  DHCP agents MAY choose to only do this if the length of the
   concatenated option data is greater than 255 octets if it wants to
   reduce how permissive it is.

7.4.  Duplicates of Arbitrary-length Options

   Arbitrary-length options are options that may have any non-zero octet
   length, such as Option 114 Captive-Portal [RFC8910].  DHCP agents
   receiving messages with more than one instance of arbitrary-length
   options MAY concatenate or choose one instance to process.  It MAY
   choose to do some validation of the content that would result from
   each approach, meaning if the data only makes sense in the context of
   the option's definition, it could use that to decide which approach
   to take.

8.  Security Considerations

   This document changes the conditions under which a DHCP agent accepts
   or rejects option data.  The only way this might reduce a DHCP
   agent's security posture would be if it would have previously refused
   to process data from the network that it will now process.  However,
   this was always possible for an attacker crafting DHCP messages.  Any
   attacker capable of creating a malformed message could instead craft
   a well-formed message (which would be processed in the same way
   before and after this document).  Therefore, this document does not
   introduce any additional security considerations beyond the previous
   definitions of DHCP and option concatenation.




Jensen & Justel         Expires 4 September 2025                [Page 5]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


9.  IANA Considerations

   This document has no IANA actions.

10.  References

10.1.  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,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC3396]  Lemon, T. and S. Cheshire, "Encoding Long Options in the
              Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396,
              DOI 10.17487/RFC3396, November 2002,
              <https://www.rfc-editor.org/rfc/rfc3396>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

10.2.  Informative References

   [RFC2132]  Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
              Extensions", RFC 2132, DOI 10.17487/RFC2132, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2132>.

   [RFC4702]  Stapp, M., Volz, B., and Y. Rekhter, "The Dynamic Host
              Configuration Protocol (DHCP) Client Fully Qualified
              Domain Name (FQDN) Option", RFC 4702,
              DOI 10.17487/RFC4702, October 2006,
              <https://www.rfc-editor.org/rfc/rfc4702>.

   [RFC6731]  Savolainen, T., Kato, J., and T. Lemon, "Improved
              Recursive DNS Server Selection for Multi-Interfaced
              Nodes", RFC 6731, DOI 10.17487/RFC6731, December 2012,
              <https://www.rfc-editor.org/rfc/rfc6731>.

   [RFC7291]  Boucadair, M., Penno, R., and D. Wing, "DHCP Options for
              the Port Control Protocol (PCP)", RFC 7291,
              DOI 10.17487/RFC7291, July 2014,
              <https://www.rfc-editor.org/rfc/rfc7291>.

   [RFC791]   Postel, J., "Internet Protocol", STD 5, RFC 791,
              DOI 10.17487/RFC0791, September 1981,
              <https://www.rfc-editor.org/rfc/rfc791>.




Jensen & Justel         Expires 4 September 2025                [Page 6]

Internet-Draft  DHCP Option Concatenation Considerations      March 2025


   [RFC8572]  Watsen, K., Farrer, I., and M. Abrahamsson, "Secure Zero
              Touch Provisioning (SZTP)", RFC 8572,
              DOI 10.17487/RFC8572, April 2019,
              <https://www.rfc-editor.org/rfc/rfc8572>.

   [RFC8910]  Kumari, W. and E. Kline, "Captive-Portal Identification in
              DHCP and Router Advertisements (RAs)", RFC 8910,
              DOI 10.17487/RFC8910, September 2020,
              <https://www.rfc-editor.org/rfc/rfc8910>.

   [RFC8973]  Boucadair, M. and T. Reddy.K, "DDoS Open Threat Signaling
              (DOTS) Agent Discovery", RFC 8973, DOI 10.17487/RFC8973,
              January 2021, <https://www.rfc-editor.org/rfc/rfc8973>.

   [RFC9463]  Boucadair, M., Ed., Reddy.K, T., Ed., Wing, D., Cook, N.,
              and T. Jensen, "DHCP and Router Advertisement Options for
              the Discovery of Network-designated Resolvers (DNR)",
              RFC 9463, DOI 10.17487/RFC9463, November 2023,
              <https://www.rfc-editor.org/rfc/rfc9463>.

Acknowledgments

   Thank you to Dieter Siegmund, Stuart Cheshire, and Ted Lemon for
   their comments and suggestions.

Authors' Addresses

   Tommy Jensen
   Microsoft
   Email: tojens.ietf@gmail.com


   Milan Justel
   Microsoft
   Email: milanjustel@microsoft.com
















Jensen & Justel         Expires 4 September 2025                [Page 7]


name: draft-cui-nmrg-llm-nm
rev: 01
title: A Framework for LLM Agent-Assisted Network Management with Human-in-the-Loop
time: 2025-10-19T00:36:24Z
group_uri: /api/v1/group/group/1027/
expires: 2026-04-22T00:36:24Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Human-agent interaction", "Autonomous netops", "ML traffic mgmt", "AI safety/alignment"]
tags: []
fetched_at: 2026-02-27T22:56:05.127614+00:00
abstract:
This document defines an interoperable framework that facilitates
   collaborative network management between Large Language Models (LLMs)
   agents and human operators.  The proposed framework introduces an
   enhanced telemetry module, an LLM agent decision module, and
   interaction data models between human operators and LLM agent-driven
   systems, and workflows to enforce human oversight.  The approach
   ensures compatibility with existing network management systems and
   protocols while improving automation and decision-making capabilities
   in network operations.

full_text:
Network Management                                                Y. Cui
Internet-Draft                                       Tsinghua University
Intended status: Informational                                   M. Xing
Expires: 21 April 2026                                          L. Zhang
                                                 Zhongguancun Laboratory
                                                         18 October 2025


A Framework for LLM Agent-Assisted Network Management with Human-in-the-
                                  Loop
                        draft-cui-nmrg-llm-nm-01

Abstract

   This document defines an interoperable framework that facilitates
   collaborative network management between Large Language Models (LLMs)
   agents and human operators.  The proposed framework introduces an
   enhanced telemetry module, an LLM agent decision module, and
   interaction data models between human operators and LLM agent-driven
   systems, and workflows to enforce human oversight.  The approach
   ensures compatibility with existing network management systems and
   protocols while improving automation and decision-making capabilities
   in network operations.

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://xmzzyo.github.io/draft_llm_nm/draft-cui-nmrg-llm-nm.html.
   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-cui-nmrg-llm-nm/.

   Discussion of this document takes place on the Network Management
   Research Group mailing list (mailto:nmrg@irtf.org), which is archived
   at https://mailarchive.ietf.org/arch/browse/nmrg.  Subscribe at
   https://www.ietf.org/mailman/listinfo/nmrg/.

   Source for this draft and an issue tracker can be found at
   https://github.com/xmzzyo/draft_llm_nm.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.






Cui, et al.               Expires 21 April 2026                 [Page 1]

Internet-Draft                   LLM4Net                    October 2025


   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 21 April 2026.

Copyright Notice

   Copyright (c) 2025 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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Problem Statement . . . . . . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.  Acronyms and Abbreviations  . . . . . . . . . . . . . . .   4
   3.  Framework Overview  . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Enhanced Telemetry Module . . . . . . . . . . . . . . . .   5
     3.2.  LLM Agent Decision Module . . . . . . . . . . . . . . . .   5
       3.2.1.  RAG Module  . . . . . . . . . . . . . . . . . . . . .   6
       3.2.2.  Task Agent Module . . . . . . . . . . . . . . . . . .   6
       3.2.3.  Task Agent Communication Module . . . . . . . . . . .   7
       3.2.4.  Task Agent Management Module  . . . . . . . . . . . .   8
     3.3.  Config Verification Module  . . . . . . . . . . . . . . .  10
       3.3.1.  Syntax Validation Module  . . . . . . . . . . . . . .  10
       3.3.2.  Access Control Module . . . . . . . . . . . . . . . .  10
       3.3.3.  Feedback Module . . . . . . . . . . . . . . . . . . .  11
     3.4.  Operator Audit Module . . . . . . . . . . . . . . . . . .  11
   4.  Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . .  13
     4.1.  DDoS Intelligent Defense  . . . . . . . . . . . . . . . .  13
     4.2.  Traffic Scheduling and Optimization . . . . . . . . . . .  15
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  17
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  17



Cui, et al.               Expires 21 April 2026                 [Page 2]

Internet-Draft                   LLM4Net                    October 2025


     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  17
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  17
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  18
   Appendix  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
     Appendix A.1 Data Model . . . . . . . . . . . . . . . . . . . .  18
       LLM Response Data Model . . . . . . . . . . . . . . . . . . .  18
       Human Audit Data Model  . . . . . . . . . . . . . . . . . . .  19
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  20

1.  Introduction

1.1.  Motivation

   Traditional network automation systems often face challenges in
   handling unanticipated scenarios and managing complex multi-domain
   data dependencies.  Large Language Models (LLMs) offer advanced
   multimodal data comprehension, adaptive reasoning, and generalization
   capabilities, making them a promising tool for network management and
   autonomous network[TM-IG1230].  However, full automation remains
   impractical due to risks such as model hallucination, operational
   errors, and a lack of accountability in decision-making[Huang25].
   This document proposes a structured framework that integrates LLMs
   into network management through human-in-the-loop collaboration,
   leveraging their strengths while ensuring oversight, reliability, and
   operational safety.

1.2.  Problem Statement

   Network management faces significant challenges, including the
   complexity of multi-vendor configurations, the real-time correlation
   of heterogeneous telemetry data, and the need for rapid responses to
   dynamic security threats.  LLMs offer a promising approach to
   addressing these challenges through their advanced multimodal data
   understanding and adaptive reasoning capabilities.  However, the
   direct application of LLMs in network management introduces several
   technical considerations.  These include the need for semantic
   enrichment of network telemetry to enhance LLM comprehension, a
   decision execution mechanism with confidence-based escalation, and
   auditability of LLM-generated decisions through provenance tracking.
   Addressing these requirements is critical to integrating LLM agents
   effectively into network management workflows while maintaining
   reliability, transparency, and interoperability.









Cui, et al.               Expires 21 April 2026                 [Page 3]

Internet-Draft                   LLM4Net                    October 2025


2.  Terminology

2.1.  Acronyms and Abbreviations

   *  LLM: Large Language Model

   *  RAG: Retrieve Augmented Generation

   *  MCP: Model Context Protocol

   *  A2A: Agent-to-Agent Protocol

3.  Framework Overview

   +-------------------------------------------------------------+
   |         LLM-Agent Assisted Network Management System        |
   +-------------------------------------------------------------+
   |+---------------LLM Agent Decision Module-------------------+|
   ||                                                           ||
   ||               +----Task Agent Module---+  +-------------+ ||
   ||               | +---------------------+|  | Task Agent  <-----+
   ||               | |      MCP & A2A      ||<-> Mgt Module  | ||  |
   ||               | +---------------------+|  +-------------+ ||  |
   ||               | +------+  +----------+ |  |Syntax Verify| ||  |
   ||               | |Prompt|  |Fine-Tuned| <->|     Module  | ||  |
   ||               | | Lib  |  |Weight Lib| |  +-------------+ ||  |
   || +----------+  | +------+  +----------+ |  +--------------+||  |
   || |RAG Module|<-> +--------------------+ |  |Access Control|||  |
   || +-----^----+  | |Foundation Model Lib| -->|    Module    |||  |
   ||       |       | +--------------------+ |  +-------|------+||  |
   ||       |       +----^---------------^---+          |       ||  |
   |+-------|------------|---------------|--------------|-------+|  |
   |+-------v------------v----+ +--------v--------------v-------+|  |
   ||Enhanced Telemetry Module| |   Operator Audit Module       ||  |
   |+-----------^-------------+ +--------------|-------------^--+|  |
   +------------|------------------------------|-------------|---+  |
                |                              |       +-----v---+  |
                |                              |       |Operator <--+
                |                              |       +---------+
   +------------v------------------------------v------------------+
   |               Original Network Management System             |
   +------------------------------^-------------------------------+
                                  |
   +------------------------------v-------------------------------+
   |                       Physical Network                       |
   +--------------------------------------------------------------+

   Figure 1: The LLM-Assisted Network Management Framework



Cui, et al.               Expires 21 April 2026                 [Page 4]

Internet-Draft                   LLM4Net                    October 2025


   The proposed framework is shown in Figure 1, highlighting the key
   components of LLM agent-assisted network management.  The human
   operator can generate a specific task agent, e.g., fault analysis or
   topology optimization, using the task agent management module by
   specifying foundation model, prompt, and adaptation fine-tuned
   parameters[Hu22].  The enhanced telemetry module improves the
   semantics of raw telemetry data from original network management
   system, providing supplementary information to the LLM agent decision
   module for more informed decision-making.  After the decision-making,
   the generated configuration parameters are validated against the YANG
   model and enforced with access control rules.  The operator audit
   module provides a structured mechanism for human oversight of LLM-
   generated configurations, and the configuration can be issued to the
   original network management system for deployment once the operator
   approves.

3.1.  Enhanced Telemetry Module

   The Enhanced Telemetry Module improves the semantics of raw telemetry
   data, providing supplementary information to the LLM agent decision
   module for more informed decision-making.  Telemetry data retrieved
   from network devices via NETCONF[RFC6241], e.g., in XML format, often
   lacks field descriptions, structured metadata, and vendor-specific
   details.  Since this information is not included in the pre-trained
   knowledge of LLMs, it can lead to misinterpretation and erroneous
   reasoning.  To address this limitation, an external knowledge base
   should be introduced to store YANG model schema, device manuals, and
   other relevant documentation.  The Enhanced Telemetry Module
   functions as middleware between the network management system and the
   external knowledge base.  Through its southbound interface, it
   retrieves NETCONF data from the NETCONF client of existing network
   management system.  Through its northbound interface, the module
   queries the external knowledge base for the corresponding YANG model
   or device manual.  To enhance semantic richness, the Enhanced
   Telemetry Module processes the retrieved data by simplifying
   formatted content (e.g., removing redundant or closing XML tags) and
   appending XML path and description information from the YANG tree to
   the relevant fields.  This approach ensures that the LLM has access
   to structured, contextually enriched data, improving its ability to
   analyze and reason about network telemetry.

3.2.  LLM Agent Decision Module









Cui, et al.               Expires 21 April 2026                 [Page 5]

Internet-Draft                   LLM4Net                    October 2025


3.2.1.  RAG Module

   The pre-trained LLM may not encompass specific task requirements or
   vendor-specific knowledge.  To address this kind of limitation, the
   Retrieve-Augmented Generation (RAG)[Lewis20] approach is widely used.
   This module retrieves relevant information from operator-defined
   sources, such as device documentation and expert knowledge, and
   integrates it with the Enhanced Telemetry Module to obtain YANG model
   schema.  The retrieved textual data is stored in a database, either
   as raw text or in a vectorized format for efficient search and
   retrieval.  For a given task context, the module retrieves relevant
   knowledge from the database and incorporates it into the input
   context, improving the understanding and response accuracy of LLM.

3.2.2.  Task Agent Module

   To execute a specific task, such as traffic analysis, traffic
   optimization, or fault remediation, a corresponding task agent must
   be created.  A task agent consists of a selected LLM foundation
   model, an associated prompt, and fine-tuned weights.

   *  Foundation Model Library.  Operators must select an appropriate
      foundation model based on the specific task requirements.
      Examples include general-purpose models such as GPT-4, LLaMA, and
      DeepSeek, as well as domain-specific models fine-tuned on private
      datasets.  Since foundation models are trained on different
      datasets using varying methodologies, their performance may differ
      across tasks.

   *  Fine-Tuned Weight Library.  For domain-specific applications,
      fine-tuned weights can be applied on top of a foundation model to
      efficiently adapt it to private datasets.  One commonly used
      approach is to store the fine-tuned weights as the difference
      between the original foundation model and the adapted model, which
      can largely reduce storage requirements.  The Fine-Tuned Weights
      Module supports the selection and loading of an appropriate
      foundation model along with the corresponding fine-tuned weights,
      based on the selection of operators.  This ensures flexibility in
      leveraging both general-purpose and domain-specific knowledge
      while maintaining computational efficiency.











Cui, et al.               Expires 21 April 2026                 [Page 6]

Internet-Draft                   LLM4Net                    October 2025


   *  Prompt Library.  For each task, it is essential to accurately
      define the task description, the format of its inputs and outputs.
      These definitions are stored in a structured prompt library.  When
      an operator instantiates a task, the corresponding prompt,
      including placeholders for contextual information, is
      automatically retrieved. operator inputs and device data are then
      incorporated into the prompt at the designated placeholders,
      ensuring a structured and consistent interaction with the language
      model.

3.2.3.  Task Agent Communication Module

   Task agent can interact with external tools (e.g., Python scripts,
   Batfish or ILP solver) to acquire additional knowledge and perform
   specific actions.  The Model Context Prtocol (MCP)[mcp] enables task
   agents to securely and efficiently interact with external tools and
   services.  MCP defines a standardized interface for tool invocation,
   data exchange, and state synchronization between the agent and
   external systems.  MCP consists of two primary components:

   *  MCP Client: Embedded within the task agent, the MCP client is
      responsible for:

      -  Serializing agent-generated tool invocation requests into
         structured MCP messages.

      -  Managing authentication and session tokens for secure tool
         access.

      -  Handling timeouts, retries, and error propagation from tool
         responses.

      -  Injecting tool outputs back into the agent context as
         structured observations.

   *  MCP Server: Hosted alongside or within external tools, the MCP
      server:

      -  Exposes a well-defined set of capabilities via a manifest
         (e.g., tool_name, tool_description, input_schema,
         output_schema, authentication_method).

      -  Validates incoming MCP requests against the tool’s schema and
         permissions.

      -  Executes the requested operation and returns structured results
         in a deterministic format.




Cui, et al.               Expires 21 April 2026                 [Page 7]

Internet-Draft                   LLM4Net                    October 2025


      -  Supports streaming for long-running operations (e.g., iterative
         optimization or real-time telemetry polling).

   In many complex scenarios, multiple task agents may collaborate to
   achieve a shared network management objective.  The Agent-to-Agent
   Protocol (A2A)[a2a] is a coordination protocol that enables multiple
   task agents to exchange information, delegate subtasks, negotiate
   resource usage, and synchronize execution states in a distributed
   network management environment.  A2A ensures semantic
   interoperability, temporal consistency, and conflict avoidance across
   heterogeneous agents.  Key design principles of A2A include:

   *  Decentralized orchestration: No central controller is required;
      agents coordinate peer-to-peer using shared intents and
      commitments.

   *  Intent-based messaging: Communication is driven by high-level
      intents (e.g., “optimize latency for flow X”) rather than low-
      level commands, allowing flexibility in implementation.

   *  State-aware handoffs: Agents share partial execution states (e.g.,
      intermediate results, constraints, confidence scores) to enable
      context-preserving collaboration.

   Additionally, A2A integrates with the Task Agent Management Module to
   dynamically spawn or terminate agents based on collaboration needs,
   ensuring scalability and resource efficiency.

3.2.4.  Task Agent Management Module

   The Task Agent Management Module is responsible for the creation,
   update, and deletion of task agents.  This module ensures that each
   agent is appropriately configured to align with the intended network
   management objective.

   The agent lifecycle operations are defined as follows:

   1.  Creation of Task Agents.  A task agent is instantiated in
       response to an operator request, an automated policy trigger, or
       a higher-level orchestration workflow.  The creation process
       involves the following steps:

       *  Intent Parsing: The module parses the high-level intent (e.g.,
          “remediate BGP flapping on router R5”) to identify the
          required task type, target network scope, and performance
          constraints.





Cui, et al.               Expires 21 April 2026                 [Page 8]

Internet-Draft                   LLM4Net                    October 2025


       *  Agent Template Selection: Based on the parsed intent, the
          module selects a pre-registered agent template from the Prompt
          Library.

       *  Resource Allocation: The module allocates necessary compute
          resources (CPU/GPU, memory) and instantiates the LLM runtime
          environment.

       *  Context Initialization: The agent is initialized with: Network
          context (e.g., device inventory, topology from Enhanced
          Telemetry), security credentials, and session ID and logging
          context for auditability.

       *  Registration: The newly created agent is registered with its
          metadata, status (“initializing”), and heartbeat endpoint.

   2.  Update of Task Agents.  Task agents may require updates due to
       changing network conditions, model improvements, or revised
       operator policies.  Updates should be performed in a non-
       disruptive manner whenever possible:

       *  Configuration Update: Operators or automated controllers may
          modify agent parameters (e.g., optimization thresholds, output
          verbosity).

       *  Model or Weight Swapping: If a newer fine-tuned weight version
          becomes available, the module can hot-swap the adapter weights
          while preserving the agent’s execution state, provided the
          base foundation model remains compatible.

       *  State Preservation: During updates, the module snapshots the
          agent’s working memory (e.g., conversation history,
          intermediate plans) and restores it post-update to maintain
          task continuity.

   3.  Deletion of Task Agents.  Task agents are terminated when their
       assigned task completes, when an unrecoverable error occurs, or
       upon an explicit teardown request.  The deletion process ensures
       proper resource reclamation and audit compliance:

       *  Graceful Shutdown: The module issues a termination signal,
          allowing the agent to complete any pending operations (e.g.,
          commit configuration changes, MCP calls, A2A communications).

       *  State Archival: The final agent state, including input
          context, generated actions, and performance metrics, is
          serialized and stored in the Audit Log for replayability and
          compliance.



Cui, et al.               Expires 21 April 2026                 [Page 9]

Internet-Draft                   LLM4Net                    October 2025


       *  Resource Deallocation: Compute resources (GPU memory, threads)
          are released, and MCP sessions are invalidated.

       *  Deregistration: The agent entry is removed, and its lifecycle
          event is logged.

   By providing structured, auditable, and policy-governed lifecycle
   management, the Task Agent Management Module enables scalable and
   trustworthy deployment of LLM Agent-driven network automation.

3.3.  Config Verification Module

3.3.1.  Syntax Validation Module

   To ensure correctness and policy compliance, LLM-generated
   configurations must pass the YANG schema validation steps before
   being queued for human approval.  This module ensures that only
   syntactically correct configurations are presented for operator
   review, thereby reducing errors and enhancing network reliability.

3.3.2.  Access Control Module

   Although the Configuration Verify Module can guarantee the syntactic
   correction, LLMs may generate unintended or potentially harmful
   operations on critical network devices, it is essential for operators
   to enforce clear permission boundaries for LLM task agent to ensure
   security and operational integrity.  The Network Configuration Access
   Control Model defined in [RFC8341] provides a framework for
   specifying access permissions, which can be used to grant access to
   LLM task agents.  This data model includes the concepts of users,
   groups, access operation types, and action types, which can be
   applied as follows:

   *  User and Group: Each task agent should be registered as a specific
      user, representing an entity with defined access permissions for
      particular devices.  These permissions control the types of
      operations the LLM is authorized to perform.  A task agent (i.e.,
      user) is identified by a unique string within the system.  Access
      control can also be applied at the group level, where a group
      consists of zero or more members, and a task agent can belong to
      multiple groups.

   *  Access Operation Types: These define the types of operations
      permitted, including create, read, update, delete, and execute.
      Each task agent may support different sets of operations depending
      on its assigned permissions.





Cui, et al.               Expires 21 April 2026                [Page 10]

Internet-Draft                   LLM4Net                    October 2025


   *  Action Types: These specify whether a given operation is permitted
      or denied.  This mechanism determines whether an LLM request to
      perform an operation is allowed based on predefined access control
      rules.

   *  Rule List: A rule governs access control by specifying the content
      and operations a task agent is authorized to handle within the
      system.

   This module must enforce explicit restrictions on the actions an LLM
   is permitted to perform, ensuring that network configurations remain
   secure and compliant with operational policies.

3.3.3.  Feedback Module

   As the generated configuration might not be always aligned with YANG
   model schema, access control, or bussiness constrains, they need
   further modification to meet the multi-dimensional requirements.  The
   Feedback Module is used to provide semantic-rich feedback (e.g.,
   represented in structure text) and hints to LLM agent to improve the
   generated configuration.

3.4.  Operator Audit Module

   The Operator Audit Module provides a structured mechanism for human
   oversight of LLM-generated configurations before deployment.  The
   output from the LLM Decision Module should include both the generated
   configuration parameters and an associated confidence score.  The
   configuration parameters are validated for compliance with the YANG
   model and are subject to Access Control Rules enforcement.  The
   confidence score, e.g., ranging from 0 to 100, serves as a reference
   for operators to assess the reliability of the generated
   configuration.  Each audit process must track the input context
   (e.g., input data, RAG query content, model selection, configuration
   files) and the corresponding output results.  The auditing steps are
   as follows:

   *  Result Verification: The operator verifies the LLM-generated
      output to ensure alignment with business objectives and policy
      requirements.

   *  Compliance Check: The operator ensures that the LLM output adheres
      to regulatory standards and legal requirements.

   *  Security Verification: The operator examines the output for
      potential security risks, such as misconfigurations or
      vulnerabilities.




Cui, et al.               Expires 21 April 2026                [Page 11]

Internet-Draft                   LLM4Net                    October 2025


   *  Suggestions and Corrections: If issues are identified, the
      operator documents the findings and proposes corrective actions.

   Upon completing the audit, the system maintains an audit decision
   record to ensure traceability of operator actions.  The audit record
   includes the following information:

   *  Timestamp of the audit action

   *  LLM Task Agent ID associated with the action

   *  Operator decisions, including approval, rejection, modification,
      or pending status

   *  Executed command reflecting the final action taken

   *  Operation type (e.g., configuration update, deletion, or
      execution)

   This structured approach ensures that all LLM-generated
   configurations undergo rigorous human review, maintaining operational
   accountability, and security.

   The Operator Audit Module is enhanced with Explainability
   functionality to improve transparency and trust in LLM-assisted
   decision-making.  This enhancement ensures that operators can
   understand the reasoning behind LLM-generated configurations, verify
   their reliability, and take corrective actions when necessary.

   To achieve Explainability, the module provides a structured breakdown
   of the decision-making process by capturing key influencing factors,
   justification logs, and confidence scores.  Each LLM-generated
   configuration must include a detailed rationale explaining why a
   particular decision was made.  For example, if the system recommends
   increasing bandwidth allocation, the decision log should indicate
   whether this was due to high latency detected in telemetry, SLA
   thresholds being exceeded, or other contributing factors.

   Additionally, the audit process incorporates counterfactual analysis,
   allowing operators to assess alternative outcomes.  For instance, the
   system may indicate that if no action is taken, packet loss is
   expected to increase by 20% in the next ten minutes.  This capability
   enhances operational decision-making by providing a comparative
   assessment of different actions.

   To further ensure reliability, the module includes a mechanism to
   detect potential biases or hallucinations in LLM-generated outputs.
   If an LLM agent decision is based on incomplete or uncertain data,



Cui, et al.               Expires 21 April 2026                [Page 12]

Internet-Draft                   LLM4Net                    October 2025


   the system flags it accordingly, allowing operators to make informed
   judgments.  For example, if real-time telemetry data is insufficient,
   the system may indicate that the confidence in a particular
   recommendation is low.

   By integrating these Explainability features, the Operator Audit
   Module strengthens human oversight, ensuring that LLM-generated
   configurations align with business policies, security requirements,
   and regulatory standards.  This structured approach enhances
   accountability and mitigates risks associated with automated
   decision-making.

4.  Use Cases

4.1.  DDoS Intelligent Defense

   Distributed Denial of Service (DDoS) attacks remain a critical
   operational threat.  While conventional systems use rate-limiting and
   signature matching, they often fail to adapt in real-time or generate
   fine-grained filtering rules based on multi-dimensional telemetry
   data.

   This use case demonstrates how the LLM agent-assisted framework
   enables intelligent filtering rule generation and secure deployment
   with human oversight.

   1.  *Telemetry Collection and Semantic Enrichment* The Enhanced
       Telemetry Module retrieves real-time traffic statistics and
       interface metrics from network devices using NETCONF.  These raw
       telemetry data are semantically enriched by referencing YANG
       models and device-specific documentation to generate a context-
       rich dataset suitable for LLM processing.

   2.  *DDoS Filtering Task Instantiation* The operator initiates a
       ddos-mitigation task.  The Task Agent Module selects a security-
       specialized foundation model and task-specific prompt.

       It first analyzes the following conclusions: - Interface
       GigabitEthernet0/1 receiving sustained traffic > 100,000 pps -
       95% of incoming packets are TCP SYN - Top source prefixes
       identified as: IP1/24, IP2/24

       The RAG Module supplements the analysis with: - Cisco ACL syntax
       documentation - Prior incident response templates

   3.  *LLM-Generated Firewall Configuration Output* The LLM agent
       reasons that a TCP SYN flood is underway and generates the
       following ACL-based filtering policy:



Cui, et al.               Expires 21 April 2026                [Page 13]

Internet-Draft                   LLM4Net                    October 2025


   ip access-list extended BLOCK-DDOS
   deny tcp IP1 0.0.0.255 any
   deny tcp IP2 0.0.0.255 any
   permit ip any any

   interface GigabitEthernet0/1
   ip access-group BLOCK-DDOS in

   This configuration includes both source-based filtering and a global
   SYN rate-limiter.  It is passed to the Config Verify Module for
   syntax validation and to the Access Control Module for permission
   checks.

   1.  *Operator Audit and Decision* The Operator Audit Module provides
       the following metadata:

   *  *Task Agent ID*: ddos-mitigation-task-01

   *  *Confidence Score*: 85/100

   *  *RAG Context*: Cisco IOS ACL Syntax, Internal Threat List v5

   *  *Input Summary*:

      -  Affected Interface: GigabitEthernet0/1

      -  Malicious Sources: IP1/24, IP2/24

   The human operator performs the audit with the following steps:

   *  *Result Verification*: ACL syntax matches Cisco IOS 15.6
      standards.

   *  *Compliance Check*: Confirmed that both prefixes appear in the
      enterprise blacklist.

   *  *Security Review*: Low false-positive risk for blanket deny of SYN
      traffic from identified prefixes.

   *  *Audit Record*:

      -  Timestamp: 2025-07-16T17:03:00Z

      -  Decision: _Approved_

      -  Action: Apply via NMS interface





Cui, et al.               Expires 21 April 2026                [Page 14]

Internet-Draft                   LLM4Net                    October 2025


      -  Operator Note: “Confirmed match with active threat list.
         Monitor for collateral traffic drops.”

   The configuration is deployed through the network management system,
   completing the defense workflow with human oversight and
   traceability.

   This simplified case shows how the LLM agent can assist in quickly
   generating actionable filtering rules in response to DDoS patterns,
   while adhering to operational safeguards.

4.2.  Traffic Scheduling and Optimization

   In large-scale networks, dynamic traffic scheduling is required to
   adapt to fluctuating loads, ensure QoS, and meet SLA requirements.
   Traditional methods may lack responsiveness or cross-domain
   visibility.

   The proposed framework enables intelligent, context-aware traffic
   scheduling through LLM agent-based reasoning.  The following
   illustrates the process:

   1.  *Telemetry Data Acquisition* The Enhanced Telemetry Module
       gathers link utilization, queue occupancy, and delay metrics from
       multiple routers.  The semantic enrichment process tags each
       metric with human-readable labels from the YANG model, including
       path topology and policy tags (e.g., gold/silver/bronze service
       classes).

   2.  *Optimization Task Execution* An operator initiates a traffic
       scheduling task.  The Task Agent Module selects a foundation
       model fine-tuned on traffic engineering datasets and uses a
       structured prompt to describe current constraints: high
       utilization on core links L1-L3, SLA violations for gold-class
       VoIP traffic.

   3.  *Sample Configuration Output* The LLM agent suggests adjusting
       RSVP-TE path metrics to reroute gold traffic via underutilized
       backup paths:












Cui, et al.               Expires 21 April 2026                [Page 15]

Internet-Draft                   LLM4Net                    October 2025


   policy-options {
       policy-statement reroute-gold {
           term gold-traffic {
               from {
                   community gold-voip;
               }
               then {
                   metric 10;
                   next-hop [IP];
               }
           }
       }
   }
   protocols {
       rsvp {
           interface ge-0/0/0 {
               bandwidth 500m;
           }
       }
   }

   This configuration is syntax-validated and checked against the Access
   Control Module to ensure that traffic engineering policy updates are
   permitted for this task agent.

   1.  *Operator Audit and Decision* The Operator Audit Module presents:

   *  *Confidence Score*: 91/100

   *  *Audit Metadata*:

      -  Task Agent: traffic-opt-te-v2

      -  Input Context: “Link L1 (95% utilization), gold-voip SLA
         latency breach”

      -  Recommendation: “Increase TE path metric to reroute VoIP via L2
         backup path”

   The operator reviews:

   *  *Result Verification*: Simulates expected path shift via NMS.

   *  *Compliance Check*: Confirms SLA routing rules permit TE
      adjustment.

   *  *Security Review*: Confirms backup link L2 is secure and isolated.




Cui, et al.               Expires 21 April 2026                [Page 16]

Internet-Draft                   LLM4Net                    October 2025


   *  *Final Action*: _Approved with modification_: “Set bandwidth cap
      to 400m on backup to avoid overuse.”

   The revised configuration is stored and forwarded to the network
   management system for application.

   This use case illustrates how the framework enables LLM agents to
   propose adaptive, policy-compliant traffic engineering strategies
   while maintaining operator control, traceability, and auditability.

5.  IANA Considerations

   This document includes no request to IANA.

6.  Security Considerations

   *  Model Hallucination: A key challenge is that, without proper
      constraints, the LLM agent may produce malformed or invalid
      configurations.  This issue can be mitigated using techniques such
      as Constrained Decoding, which enforces syntactic correctness by
      modeling the configuration syntax and restricting the output to
      conform to predefined rules during the generation process.

   *  Training Data Poisoning: LLMs can be trained on malicious or
      biased data, potentially leading to unintended behavior or
      security vulnerabilities.  To mitigate this risk, LLMs should be
      trained on curated, high-quality datasets with rigorous validation
      and filtering processes.  Periodic retraining and adversarial
      testing should also be conducted to detect and correct anomalies
      before deployment.

7.  References

7.1.  Normative References

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/rfc/rfc6241>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/rfc/rfc8341>.

7.2.  Informative References





Cui, et al.               Expires 21 April 2026                [Page 17]

Internet-Draft                   LLM4Net                    October 2025


   [a2a]      "Announcing the Agent2Agent Protocol (A2A)", July 2025,
              <https://developers.googleblog.com/en/a2a-a-new-era-of-
              agent-interoperability/>.

   [Hu22]     Hu, E. J., Shen, Y., Wallis, P., Allen-Zhu, Z., Li, Y.,
              Wang, S., Wang, L., and W. Chen, "LoRA Low-Rank Adaptation
              of Large Language Models", n.d..

   [Huang25]  Huang,, L., Yu, W., Ma, W., Zhong, W., Feng, Z., Wang, H.,
              Chen, Q., Peng, W., Feng, X., Qin, B., and T. Liu, "A
              Survey on Hallucination in Large Language Models
              Principles, Taxonomy, Challenges, and Open Questions",
              n.d..

   [Lewis20]  Lewis, P., Perez, E., Piktus, A., Petroni, F., Karpukhin,
              V., Goyal, N., Küttler, H., Lewis, M., Yih, W.-t.,
              Rocktäschel, T., and S. Riede, "Retrieval-augmented
              generation for knowledge-intensive NLP tasks", n.d..

   [mcp]      "Model Context Protocol", July 2025,
              <https://modelcontextprotocol.io/introduction>.

   [TM-IG1230]
              McDonnell, K., Machwe, A., Milham, D., O’Sullivan, J.,
              Niemöller, J., Varvello, L. F., Devadatta, V., Lei, W.,
              Xu, W., Yuan, X., and Y. Stein, "Autonomous Networks
              Technical Architecture", February 2023.

Acknowledgments

   We thanks Shailesh Prabhu from Nokia for his contributions to this
   document.

Appendix

Appendix A.1 Data Model

   This section defines the essential data models for LLM agent-assisted
   network management, including the LLM agent decision response and
   human audit records.

LLM Response Data Model

   The LLM agent decision module should respond with the generated
   configuration parameters along with an associated confidence score.
   If the LLM is unable to generate a valid configuration, it should
   return an error message accompanied by an explanation of the issue.




Cui, et al.               Expires 21 April 2026                [Page 18]

Internet-Draft                   LLM4Net                    October 2025


   module: llm-response-module
     +--rw llm-response
        +--rw config?         string
        +--rw confidence?     uint64
        +--rw error-reason?   enumeration

   The LLM response YANG model is structured as follows:

   module llm-response-module {
     namespace "urn:ietf:params:xml:ns:yang:ietf-nmrg-llmn4et";
     prefix llmresponse;
     container llm-response {
       leaf config {
         type string;
       }
       leaf confidence {
         type uint64;
       }
       leaf error-reason {
         type enumeration {
           enum unsupported-task;
           enum unsupported-vendor;
         }
       }
     }
   }

Human Audit Data Model

   This data model defines the structure for human audit operations and
   record-keeping.  It facilitates collaborative decision-making by
   allowing LLMs to generate actionable insights while ensuring that
   human operators retain final operational authority.

   module: human-audit-module
     +--rw human-audit
        +--rw task-id?      string
        +--rw generated-config?   string
        +--rw confidence?         int64
        +--rw human-actions
           +--rw operator?          string
           +--rw action?            enumeration
           +--rw modified-config?   string
           +--rw timestamp?         yang:date-and-time

   The human audit YANG model is structured as follows:





Cui, et al.               Expires 21 April 2026                [Page 19]

Internet-Draft                   LLM4Net                    October 2025


   module human-audit-module {
     namespace "urn:ietf:params:xml:ns:yang:ietf-nmrg-llmn4et";
     prefix llmaudit;
     import ietf-yang-types { prefix yang; }

     container human-audit {
       leaf task-id {
         type string;
         }
       leaf generated-config {
         type string;
         }
       leaf confidence {
         type int64;
         }
       container human-actions {
         leaf operator {
           type string;
           }
         leaf action {
           type enumeration {
             enum approve;
             enum modify;
             enum reject;
             }
           }
         leaf modified-config {
           type string;
           }
         leaf timestamp {
           type yang:date-and-time;
           }
       }
     }
   }

Authors' Addresses

   Yong Cui
   Tsinghua University
   Beijing, 100084
   China
   Email: cuiyong@tsinghua.edu.cn
   URI:   http://www.cuiyong.net/







Cui, et al.               Expires 21 April 2026                [Page 20]

Internet-Draft                   LLM4Net                    October 2025


   Mingzhe Xing
   Zhongguancun Laboratory
   Beijing, 100094
   China
   Email: xingmz@zgclab.edu.cn


   Lei Zhang
   Zhongguancun Laboratory
   Beijing, 100094
   China
   Email: zhanglei@zgclab.edu.cn







































Cui, et al.               Expires 21 April 2026                [Page 21]


name: draft-eckert-anima-acp-free-ani
rev: 01
title: ACP free "Automation Network Infrastructure" for simple in-network automation (aNI)
time: 2025-10-20T18:51:47Z
group_uri: /api/v1/group/group/1027/
expires: 2026-04-23T18:51:47Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Autonomous netops", "Agent identity/auth", "A2A protocols", "Agent discovery/reg"]
tags: []
fetched_at: 2026-02-27T22:56:05.127618+00:00
abstract:
This document describes how to to build the software infrastructure
   for distributed automation agents using a lightweight variation of
   the "Autonomic Networking Infrastructure" (ANI), by using the
   existing ANI domain keying material (certificates and trust anchors)
   as well as the protocols GRASP and BRSKI protocols, but eliminating
   the expensive to implement "Autonomic Control Plane" (ACP) and adding
   proxying "Autonomic Software Agents" (ASA) instead.

   The resulting infrastructure is called "automation Network
   Infrastructure" and can be implemented solely as application level
   software components on routers, switches or co-located managemenet
   devices, avoiding the need to change any router or switches
   forwarding or control-plane protocols.

   The aNI achieves mosts of the benefits of the ANI but foregoes the
   ability to easily make pre-existing, insecure control-plane protocols
   secure or provide all the same protection against operator or SDN
   controller misconfigurations that the ACP provides.

full_text:
ANIMA                                                     T. Eckert, Ed.
Internet-Draft                                Futurewei Technologies USA
Intended status: Informational                                    B. Liu
Expires: 23 April 2026                               Huawei Technologies
                                                         20 October 2025


   ACP free "Automation Network Infrastructure" for simple in-network
                            automation (aNI)
                   draft-eckert-anima-acp-free-ani-01

Abstract

   This document describes how to to build the software infrastructure
   for distributed automation agents using a lightweight variation of
   the "Autonomic Networking Infrastructure" (ANI), by using the
   existing ANI domain keying material (certificates and trust anchors)
   as well as the protocols GRASP and BRSKI protocols, but eliminating
   the expensive to implement "Autonomic Control Plane" (ACP) and adding
   proxying "Autonomic Software Agents" (ASA) instead.

   The resulting infrastructure is called "automation Network
   Infrastructure" and can be implemented solely as application level
   software components on routers, switches or co-located managemenet
   devices, avoiding the need to change any router or switches
   forwarding or control-plane protocols.

   The aNI achieves mosts of the benefits of the ANI but foregoes the
   ability to easily make pre-existing, insecure control-plane protocols
   secure or provide all the same protection against operator or SDN
   controller misconfigurations that the ACP provides.

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 23 April 2026.



Eckert & Liu              Expires 23 April 2026                 [Page 1]

Internet-Draft                ACP free aNI                  October 2025


Copyright Notice

   Copyright (c) 2025 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Background  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Overview  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Architecture Example  . . . . . . . . . . . . . . . . . .   5
   2.  Architecture  . . . . . . . . . . . . . . . . . . . . . . . .   7
     2.1.  Credentuals and mutual trust  . . . . . . . . . . . . . .   7
     2.2.  Area segmented connectivity . . . . . . . . . . . . . . .   8
     2.3.  End-to-end transport protocols  . . . . . . . . . . . . .   9
     2.4.  GRASP security and transport substrate  . . . . . . . . .   9
     2.5.  Distributed ASA coordination via GRASP  . . . . . . . . .  10
     2.6.  Inter-area communications . . . . . . . . . . . . . . . .  11
       2.6.1.  Inter-area information flooding . . . . . . . . . . .  13
       2.6.2.  Loop prevention in inter-area GRASP flooding  . . . .  13
       2.6.3.  Inter-area GRASP policy filtering . . . . . . . . . .  13
       2.6.4.  Inter-area service announcements  . . . . . . . . . .  13
       2.6.5.  inter-area transport proxy ASA  . . . . . . . . . . .  14
     2.7.  Pledge Bootstrap  . . . . . . . . . . . . . . . . . . . .  14
       2.7.1.  Unsecured pledges bringup . . . . . . . . . . . . . .  15
       2.7.2.  BRSKI pledges . . . . . . . . . . . . . . . . . . . .  16
       2.7.3.  aNI bootstrap . . . . . . . . . . . . . . . . . . . .  16
     2.8.  Inter-domain aNI communications . . . . . . . . . . . . .  16
     2.9.  Using aNI domain credentials  . . . . . . . . . . . . . .  17
     2.10. Using federated aNI credentials . . . . . . . . . . . . .  17
     2.11. Using WebPKI certificates . . . . . . . . . . . . . . . .  17
   3.  Summary . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
   4.  Security considerations . . . . . . . . . . . . . . . . . . .  19
     4.1.  Proxying and Security . . . . . . . . . . . . . . . . . .  19
     4.2.  Infrastructure security . . . . . . . . . . . . . . . . .  19
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  20
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .  20
     5.2.  Informative References  . . . . . . . . . . . . . . . . .  20
   Appendix A.  Changelog  . . . . . . . . . . . . . . . . . . . . .  21



Eckert & Liu              Expires 23 April 2026                 [Page 2]

Internet-Draft                ACP free aNI                  October 2025


     A.1.  draft-eckert-anima-acp-free-ani-01  . . . . . . . . . . .  21
     A.2.  draft-eckert-anima-acp-free-ani-00  . . . . . . . . . . .  21
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21

1.  Introduction

1.1.  Background

   [RFC8993] describes the reference model for Autonomic Networking
   which consists of a so-called "Autonomic Network Infrastructure"
   (ANI) and in-network (devices) software agents called "Autonomic
   Service Agents" (ASA).

   ASA can be imagined as simple as scripts in programming languages
   such as python or javascript developed by bendors, integrators or
   operators.  They are primarily intended to run on network devices
   such as router or switches, or on control equipment that is also
   decentrally deployed, such as management servers in network equipment
   locations often called point of presence (PoP).  These agents can
   operate alone or in support of centralized network management systems
   including controller or orchestrators.

   One of the core components of that ANI is the so-called "Autonomic
   Control Plane" (ACP, [RFC8994]), a set of functionalities
   establishing an autonomously (zero-touch) created and maintained VRF
   across all network that is primarily intended to provide always-on
   network reachability even in the absence of any operator or
   management established provisioning of the nodes.  The ACP then
   allows operators, centralized management software or ASA to
   communicate across it to manage the network and for example provision
   both the basic network addressing and routing (so-called data-plane)
   or specific subscriber services or to perform monitoring actions/
   automations.  See also [RFC8368].

   Unfortunately, implementing an ACP in network devices, especially
   those with legacy operating system software infrastructures can be a
   challenging exercise, and as of today, no widely adopted production
   implementations on commercial routers exist.

   Without an ANI, it is challenging to build simple automation agents
   running on (or near to) network devices because they are missing
   functionalities not ubiquitously found in networks today: credentials
   for secure communications with mutual trust, connectivity and
   discovery of other agents, defining new protocols for communication
   between agents and ability to communicate when the network or
   specific nodes are not yet configured for correct end-to-end
   reachability or when that reachability is broken.




Eckert & Liu              Expires 23 April 2026                 [Page 3]

Internet-Draft                ACP free aNI                  October 2025


   This document describes the mechanisms how these support functions
   can be supported for ASA and via ASA.  The resulting design is called
   by this document the "automation Network Infrastructure" (aNI).
   Lowercase 'a' is used to distinguish it from the ANI which does
   include an ACP.

   Like the ANI, the aNI is defined so that it does not introduce
   dependencies against external, centralized components, such as
   orchestrators or management controllers.  Like the ANI the aNI can
   therefore support those centralized components.

1.2.  Overview

   This document introduces the concepts and components of an ACP-free
   automation Network Infrastructure (aNI), which leverages the
   components developed for the ANI except for its ACP.  The ACP is
   replaced by the assumed to be pre-established data-plane of the
   network, and as necessary by proxy ASA.

   Unlike the ANI with ACP, this aNI solution can easily be introduced
   into existing networks simply though the development of control-plane
   programs, for example developed in scripting languages such as python
   or javascript (whatever can best run on routers).  The aNI does not
   require any changes to routers forwarding planes and does not expect
   more than basic IPv4 and/or IPv6 end-to-end connectivity across
   segments of the network.

   In summary, the aNI differs from the ANI as follows:

   *  The networks existing and assumed to be pre-configured IPv4 or
      IPv6 connectivitiy (called data-plane) is used to provide end-to-
      end connectivity for GRASP or other protocols used to build ASA.
      Unlike the ACP, IPv4 is a fully permitted option, especially
      because large and complex industrial networks will continue to
      depend on it because it has some significant simplicity benefits
      over IPv6 in options such as [RFC1819] addressing.  Nevertheless,
      for any new deployments where there is no clear benefit of IPv4
      over IPv6, IPv6 is recommended.

   *  Discovery between ASA and between ASA and central network
      management components utilizes GRASP in the same ways as it does
      with ACP.  It requires on every network node a GRASP ASA, which is
      a lightweight (potentially scripted in python) user-level process
      that forwards GRASP discovery messages hop-by-hop.  This GRASP ASA
      can automatically be started and requires no configuration.  The
      hop-by-hop connections between these GRASP ASA is TLS.





Eckert & Liu              Expires 23 April 2026                 [Page 4]

Internet-Draft                ACP free aNI                  October 2025


   *  Mutual trust for end-to-end GRASP connections between ASA, and
      between GRASP agents, but also for any other existing protocols
      that may be used is based on the domain certificate model of
      [RFC8994]: Each node is identified by a certificate which also
      identifies the (aNI) domain and also indicates the primary network
      layer address of the node which is used for aNI communications.
      Like the ANI, the aNI can therefore operate without any
      dependencies against DNS.

   *  The aNI encourages re-use of any existing protocols such as HTTPS
      or others, that can help to avoid re-coding any already working
      ASA functionality.  GRASP is recommended whenever new designs
      could be easier than with potentially more complex frameworks that
      exist for HTTPS or CoAP(s).  Combinations of existing protocols
      with GRASP is also a recommended option, for example to use GRASP
      to automate existing protocols by amending announcement and
      discovery via GRASP and therefore eliminating manual or SDN
      controller based provisioning steps.

   *  All signaling protocols that are considered to be part of the aNI
      MUST use transport layer encryption of at least the security
      provided by TLS1.3.  If there are any existing or new protocols
      that do not meet this expectation, they are simply not considered
      to be part of the aNI.  For example existing routing protocols do
      typically not confirm to this level of security.  They can
      continue to operate unaffected from aNI.  They just do not conform
      to the security level of the aNI.

   *  Enrollment of security credentials for new network rollouts is
      recommended to use BRSKI ([RFC8995]) or any specified variation
      thereof, depending on the operational requirements of the network
      enrollment process.  In existing and pre-configured networks,
      alternatives such as netconf zero-touch with certificate
      enrollment may be viable alternatives, but are not equally
      comprehensively document as a solution.

   *  To support automation in the presence of missing end-to-end
      connectivity between all necessary nodes including new to-be-
      provisioned "pledges", proxies are used.  These proxies likely are
      a combination of generic transport proxies (e.g.: HTTP proxies) or
      service specific proxies (ASA with proxy functionality) depending
      on requirements.

1.3.  Architecture Example

   The following Figure 1 summaries the archticture components.  These
   are all introduced in more details in the following architecture
   section.



Eckert & Liu              Expires 23 April 2026                 [Page 5]

Internet-Draft                ACP free aNI                  October 2025


                                  inter-area
                                  GRASP and
   ASAs      ASAs       ASAs      Transport    ASAs      ASAs        ASAs
                                  Proxy ASA
                                    /  \
   GRAS      GRASP      GRASP    GRASP GRASP  GRASP      GRASP       GRASP
   Coord.    Coord.    Coord.   Coord.  Coord. Coord.    Coord.    Coord.
   ASA        ASA        ASA      ASA1 ASA2    ASA        ASA        ASA
       \     /    \     /    \     |    |     /   \      /    \     /
 +------+   +------+   +------+   +------+   +------+   +------+   +------+
 |Router|---|Router|---|Router|-.-|NAT/FW|-.-|Router|---|Router|---|Router|
 |  1   |   |  2   |   |  3   |   |      |   |  4   |   |  5   |   |  6   |
 | with |   | with |   | with |   | with |   | with |   | with |   | with |
 |domain|   |domain|   |domain|   |domain|   |domain|   |domain|   |domain|
 | cert |   | cert |   | cert |   | cert |   | cert |   | cert |   | cert |
 +------+   +------+   +------+   +------+   +------+   +------+   +------+

   |<----------------------------->|   |<----------------------------->|
       GRASP-NA subdomain 1                  GRASP-NA subdomain 2
     forwarding of GRASP discovery        forwarding of GRASP discovery
       between nodes with same              between nodes with same
      end-to-end connectivity                 end-to-end connectivity
        example: IPv4 only                     example: IPv6 only
 |<----------------------------------------------------------------------->|
                aNI domain (mutually trusted aNI certificates) ~~~~

                  Figure 1: aNI Architecture example

   The example architecture picture outlines the most relevant aspects
   of an aNI that where introduced in the overview section above and
   where they are the same or differ from the ANI with ACP.

   *  An aNI domain is the set of all nodes using the same aNI domain
      credentials (certificates and trust anchors).  These are using the
      same concept as ACP certificates/trust anchors.

   *  Enrollment of keying materials can use any protocol but prefers
      BRSKI (as in ACP).

   *  Addressing can use IPv4 and/or IPv6 and is solely the data-plane
      of the existing network.

   *  aNI domains may be subdivided into areas connected by inter-area
      nodes, as shown in the picture a NAT/FW.  Inside each area
      unrestricted connectivity between ASA is expected, across areas it
      is not.





Eckert & Liu              Expires 23 April 2026                 [Page 6]

Internet-Draft                ACP free aNI                  October 2025


   *  Inside each area, GRASP coordination agents enable distribution of
      information and service discovery.  This is the equivalent of
      GRASP inside the ACP ([RFC8994]).

   *  Between areas, forwarding of GRASP messages is managed by inter-
      area GRASP proxy ASA as well as existing specialized forwarding
      such as NAT and Firewall forwarding, or additional user-level
      transport proxy ASA.  The latter are generalizing the concept of
      BRSKI or HTTP proxies.

2.  Architecture

2.1.  Credentuals and mutual trust

   aNI relies on the same domain trust model as the ANI.  All nodes in
   an aNI domain are expected to have an aNI certificate and trust
   anchor(s) that allow to verify and authenticate the aNI certificates
   of other domain members.

   aNI certificates carry an aNI node name attributes, which differs
   from acp-node-names ([RFC8994], section 6.2.2) as follows:

   *  The address part can either be an IPv6 address or an IPv4 address.
      (ABNF TBD).  The aNI address of a node is a data-plane address
      that is known to be permanently assigned to the node, routable and
      reachable across a segment of the aNI domain.  There is no new
      address assignment with ULA addresses as in the ACP.

   *  This document does not discuss the more complex additional options
      such as extensions or routing subdomains, but syntactically they
      are possible as they are for ACP certificates.

   *  Encoding into the X.509 aNI domain certificate is via a new
      "OTHER-NAME" attribute to allow distinguishing it from ACP
      addresses.  A node can therefore have a single certificate with
      both an aNI name element and (potentially later) an ACP name
      element without conflicts between them.

   Enrollment of these certificates is, as in [RFC8994] by arbitrary
   methods, preferrably BRSKI.  BRSKI details for aNI are discussed
   further domain in this document.










Eckert & Liu              Expires 23 April 2026                 [Page 7]

Internet-Draft                ACP free aNI                  October 2025


2.2.  Area segmented connectivity

   aNI domains may not have transparent end-to-end connectivity across
   all nodes.  Instead, thay may be partitioned by nodes implementing
   functionality such as NAT or Firewall which provide only partial
   connectivity.  Or they may be partitioned without any connectivity
   because of different VRFs.  Or they may the partitioned by different
   network layers.  One part of the network may only use IPv4, another
   only IPv6.

   An aNI connectivity area is a contiguous set of nodes between which
   the data-plane provides in the absence of errors transparent end-to-
   end connectivity for all the traffic desired for the aNI.  This
   primarily involves traffic between ASA, but also traffic considered
   to be used in conjunction with ASA or aNI, such as traffic between
   central management nodes (controller/orchestrators), servers (NTP,
   DHCP, ...) and other required sockets on nodes.  This means that
   there may be filtering and limitations of traffic at the edge or
   inside such aNI areas, for example to prohibit traffic between these
   nodes and nodes outside the area (such as subscriber nodes).

   Note that these requirements should allow to add the aNI without
   change of any existing data-plane setup in most existing networks
   (private or service provider), and that many of them do not even need
   to consider multiple aNI connectivity areas.

   Note that that incorrect configuration of filtering of filtering will
   cause errors in the aNI in the same way as it does cause errors for
   any other management traffic.  The aNI does not - unlike the ACP -
   protect against such misconfiguration.

           connectivity area 1 ASA's           connectivity area 1 ASA's
       |<..............................>|  |<..............................>|

       ASAs      ASAs       ASAs      ASA  ASA      ASAs      ASAs        ASAs
        |          |          |        |    |        |          |          |
        |          |          |        |    |        |          |          |
     +------+   +------+   +------+   +------+   +------+   +------+   +------+
     |Router|---|Router|---|Router|-.-|NAT/FW|-.-|Router|---|Router|---|Router|
     |  1   |   |  2   |   |  3   |   |      |   |  4   |   |  5   |   |  6   |
     | with |   | with |   | with |   | with |   | with |   | with |   | with |
     |domain|   |domain|   |domain|   |domain|   |domain|   |domain|   |domain|
     | cert |   | cert |   | cert |   | cert |   | cert |   | cert |   | cert |
     +------+   +------+   +------+   +------+   +------+   +------+   +------+

     |<----------------------------------------------------------------------->|
                    aNI domain (mutually trusted aNI certificates)




Eckert & Liu              Expires 23 April 2026                 [Page 8]

Internet-Draft                ACP free aNI                  October 2025


                    Figure 2: aNI domain and areas

   Figure 1 shows a simple example of a single aNI domain with two
   connectivity areas, for example because of a NAT/FW node separating
   the two areas.  In the most simple case, an ASA connects only into a
   single area and sends/receives traffic only within a single area.
   There is no connectivity between ASA across the two areas in this
   example.

2.3.  End-to-end transport protocols

   End-to-end connections considered to be part of the aNI MUST use a
   transport layer protocol with at least the level of encryption/
   security as TLS1.3.  Compared to the ACP this means that it is not
   possible to simply use existing, non-end-to-end transport layer
   encrypted protocols such as (non-TLS version of) DHCP, DNS, NTP, SNMP
   or other common (and older) management protocols.  If and where TLS/
   DTLS (or QUIC) variations to the protocols exist, they of course are
   applicable to the aNI.

   Connunication SHOULD use existing protocols and extend them as
   necessary instead of re-inventing new protocols unnecessary.  New
   protocol development for purposes for which no suitable existing
   protocols are available SHOULD use GRASP.  This applies to peer-to-
   peer and client-server connectivity between ASA or any other traffic
   considered to be part of the aNI.

2.4.  GRASP security and transport substrate

   [RFC8990] requires that GRASP relies on a "security and transport"
   substrate, which in [RFC8994] is the ACP, TLS >= 1.2 and ACP domain
   certificates for mutual authentication.

   In the aNI, the "security and transport" substrate is the data-plane
   for connectivity, meaning the pre-existing IPv4 and/or IPv6
   connectivity, TLS >= 1.3 for any GRASP connection (except for link-
   local DULL GRASP for link-local discovery), and aNI domain
   certificates for mutual authentication.  The security considerations
   effectively ae the same as for GRASP across an ACP, but end-to-end
   (unicast) GRASP connections depend on proper functioning of data-
   plane routing.  Workarounds for this are descussed later in this
   document.









Eckert & Liu              Expires 23 April 2026                 [Page 9]

Internet-Draft                ACP free aNI                  October 2025


2.5.  Distributed ASA coordination via GRASP

   ASA need to be able to self coordinate and orchestrate.  Responders
   need to be able to announce themselves to be discovered and selected
   by responders.  ASA may have other information that needs to be
   disseminated to multiple interested ASA across the domain.

   GRASP supports these operations through Discovery and Flood messages
   which are flooded hop-by-hop through the network by GRASP
   coordination agents.  Loops are prevented by sequence number
   duplicate elimination on reception, so that these agents donot
   require any routing information.  These age that can easily be
   implemented, for example as lightweight python scripts.

   The procedures for GRASP coordination agents are the same as
   described in [RFC8994].  Nodes discover their neighbors on interfaces
   via DULL GRASP, and they build TLS1.3 connections to their neighbors,
   mutually authenticating each others by their aNI certificates.  DULL
   GRASP uses a new port number (IANA assignment TBD) to distinguish it
   from DULL GRASP for the ACP.  Therefore, GRASP in the aNI can co-
   exist with GRASP in an ACP, hence a migration from an aNI to a full
   ANI with ACP is easily possible.

   aNI nodes MUST support a GRASP coordination ASA.  They MAY support
   other methods for coordination and orchestration including service
   announcement discovery and selection, such as DNS, but this
   specification does not specify any way how to automatically establish
   a sufficient DNS infrastructure and hence also no functionality that
   depends on DNS.  Instead, DNS-SD compatible service announcement,
   discovery and selecction is suggested to rely on GRASP as described
   in [I-D.eckert-anima-grasp-dnssd].




















Eckert & Liu              Expires 23 April 2026                [Page 10]

Internet-Draft                ACP free aNI                  October 2025


           connectivity area 1 ASA's           connectivity area 2 ASA's
       |<..............................>|  |<..............................>|

       ASAs      ASAs       ASAs      ASA  ASA      ASAs      ASAs        ASAs
        |          |          |        |    |        |          |          |
        |          |          |        |    |        |          |          |
       GRAS      GRASP      GRASP    GRASP GRASP  GRASP      GRASP       GRASP
       Coord.    Coord.    Coord.  Coord.  Coord. Coord.     Coord.      Coord.
       ASA        ASA        ASA      ASA1 ASA2    ASA        ASA        ASA
           \     /    \     /    \     |    |     /   \      /    \     /
     +------+   +------+   +------+   +------+   +------+   +------+   +------+
     |Router|---|Router|---|Router|-.-|NAT/FW|-.-|Router|---|Router|---|Router|
     |  1   |   |  2   |   |  3   |   |      |   |  4   |   |  5   |   |  6   |
     | with |   | with |   | with |   | with |   | with |   | with |   | with |
     |domain|   |domain|   |domain|   |domain|   |domain|   |domain|   |domain|
     | cert |   | cert |   | cert |   | cert |   | cert |   | cert |   | cert |
     +------+   +------+   +------+   +------+   +------+   +------+   +------+

       |<----------------------------->|   |<----------------------------->|
             connectivity  area 1                 connectivity  area 2
         forwarding of GRASP messages       forwarding of GRASP messages
           between nodes with same              between nodes with same
          end-to-end connectivity               end-to-end connectivity
            example: IPv4 only                     example: IPv6 only
     |<----------------------------------------------------------------------->|
                    aNI domain (mutually trusted aNI certificates)

                 Figure 3: GRASP connectivity agents

   Figure 2 above shows the GRASP coordination ASA added to the prior
   example.  GRASP agents need to be able to determine all interfaces
   that belong to the same area and forward messages only between those
   interfaces.  If the node has interfaces in multiple areas, a separate
   instance of forwarding of GRASP messages needs to be run for each
   area.  In the example, this is shown for the NAT/FW node, which has
   interfaces in two areas.

   Note that ASA only need to rely on the GRASP coordination agent for
   sending and receiving of GRASP coordination messages.  GRASP
   "unicast" traffic to other nodes can simply use direct TLS
   connections to the nodes ASA.

2.6.  Inter-area communications

   This section explains how to implement inter-area ASA communications
   using the model shown in Figure 4.





Eckert & Liu              Expires 23 April 2026                [Page 11]

Internet-Draft                ACP free aNI                  October 2025


           connectivity area 1                 connectivity area 2
       |<..............................>|  |<..............................>|

     Initiator                         GRASP                           Responder
       ASA1                    inter-area proxy ASA [1]                   ASA6
        |                          and optional                            |
        |                  inter-area transport ASA [2]                    |
        |                              |    |                              |
       GRAS      GRASP      GRASP    GRASP GRASP  GRASP      GRASP       GRASP
       Coord.    Coord.    Coord.  Coord.  Coord. Coord.     Coord.      Coord.
           \     /    \     /    \     |    |     /   \      /    \     /
     +------+   +------+   +------+   +------+   +------+   +------+   +------+
     |Router|---|Router|---|Router|-.-|NAT/FW|-.-|Router|---|Router|---|Router|
     |  1   |   |      |   |      |   |Fwd[3]|   |      |   |      |   |  6   |
     ........   ........   ........   ........   ........   ........   ........

     |<----------------------------------------------------------------------->|
                    aNI domain (mutually trusted aNI certificates)

                 Figure 4: Inter Area communications

   A responder ASA6 on Router 6 in area 2 intends to provide services
   also to be consumable by an Initiator ASA1 on Router 1 in area 1.

   Direct inter-area network layer connectivity from ASA1 to ASA6 may be
   possible in some cases, such as when area 1 is on the inside of a NAT
   and area 2 is on its outside.  However, ASA1 would have no way to
   even discover the availability of ASA6 without the introduction of
   the elements described in this section, because no GRASP messages are
   forwarded by the GRASP coordination ASA across area boundaries.
   Likewise in the opposite case, when ASA6 is on the inside, and ASA1
   is on the outside, not only does a connection require likely special
   setups, but it is also a matter of additional policy if that type of
   communication is even desired.  Likewise are the conditions
   different, when the impeding element is a Firewall or the areas are
   different VRF.

   The three type of components of the solution are called the GRASP
   inter-area proxy ASA [1], optional inter-area transport ASA [2] and
   Forwarding functionality [3] in the forwarding plane of the inter-
   area node.










Eckert & Liu              Expires 23 April 2026                [Page 12]

Internet-Draft                ACP free aNI                  October 2025


2.6.1.  Inter-area information flooding

   The most simple example of inter-area forwarding is that of GRASP
   Flood messages used for information distribution.  All information is
   contained in the GRASP Flood message and thus no dependend inter-area
   communications is expected.  Examples of such information
   distribution could be simple router configurations for common
   functions.  Nevertheless, forwarding of such information betwween
   areas does very likely need to be policy filtered if not policy
   modified.  This is a job of specific GRASP inter-area proxy ASA.

2.6.2.  Loop prevention in inter-area GRASP flooding

   In any case where GRASP inter-area proxy ASA flood GRASP messages
   across area boundaries, care must be taken to avoid looping messages.
   This specifically means that the GRASP signaling elemtn that is used
   to detect looping messages must not be changed when passing GRASP
   messages to another area, and the identifier in it needs to be unique
   across areas.

2.6.3.  Inter-area GRASP policy filtering

   Inter-area flooding of GRASP messages should support policy filtering
   independent of the below described mechanisms to ensure the necessary
   connectivity.  This policy filtering may be derived automatically
   from specific subset of the Objective namespace or other novel GRASP
   signaling elements.

2.6.4.  Inter-area service announcements

   As described in this sections introduction, in many cases a GRASP
   Flood Message may be a service announcement for one or more responder
   sockets of the announcer, or a third-party node (in case the
   announcement is not directly from the responder ASA).

   In this case, there is the expectation that nodes receiving this
   announcement may want to initiate connections to those responder
   sockets.  The inter-area forwarding ASA does thus need to understand
   if or how those responder sockets can be connected to from the area
   into which it forwards the GRASP Flood message.

   In the aforementioned outside-to-inside flooding across a NAT inter-
   area node, the GRASP inter-area proxy ASA does not need to change
   anything in the GRASP Flood message if inside and outside use the
   same IP address family.






Eckert & Liu              Expires 23 April 2026                [Page 13]

Internet-Draft                ACP free aNI                  October 2025


   If instead the desired reachability is from outside to inside, or if
   the address families differ, then it is typically necessary to set up
   specific NAT/PAT between inside and outside to enable the
   communication, and to also change the announced service address in
   the announced GRASP Flood to the other area.

   The use of GRASP in all these cases does cleanly resolve the problem
   that such communication setups are facing when the service
   announcement and discovery are not readily available in-band on the
   inter-area nodes, which today is almost always the case.

   In one example, ASA6 is on the inside, uses an RFC1918 addres, but
   its service should be available on the outside.  The GRASP inter-area
   proxy ASA learns about the service and establishes the necessary PAT,
   mapping a port available on the outside to that inside service, and
   accordingly adjusts the GRASP announcement before it passes it to the
   outside area towards ASA1.  When ASA1 then connects, it effectively
   connects to the outside address of the inter-area node, where the
   existing NAT forwarding plane connects it to the inside RFC1918
   address and server port for ASA6.

2.6.5.  inter-area transport proxy ASA

   Instead of relying on such pre-existing/configurable forwarding
   plajne connectivity, such inter-area connectivity can and depending
   on use case must be implemented at user-level by so-called inter-
   arrea transport proxy ASA.  These are typically what in BRSKI (and
   HTTP) terms are called connection or stateful proxies, but they could
   equally be stateless proxies if this is ensured to be supported by
   the responders.

   (stateful) BRSKI proxies simply act on one side as TCP responders,
   recreating a new TCP connection on the other side as initiators and
   then forwarding traffic bidirectionally across that proxies
   connection.  HTTP proxies operate as HTTP message proxies, but can
   also be turned into TCP connection proxies through the HTTP CONNECT
   method.

2.7.  Pledge Bootstrap

   With ANI, new nodes (pledges) for a domain are bootstrapped by
   provisioning them first with domain credentials via BRSKI and then
   provisioning them with any desirable protocols via the ACP.








Eckert & Liu              Expires 23 April 2026                [Page 14]

Internet-Draft                ACP free aNI                  October 2025


   With aNI, these pledges do not have end-to-end data-plane
   connectivity after BRSKI enrollment.  They still will likely only
   have link-local connectivity.  While automatic DHCP or IPv4 SLAAC
   connectivity may be something a data-plane provides for end-user
   nodes, this is typicaly not the case for router in the domain that
   are newly added (or replaced).

   For this reason, the aNI requires some form of proxy-connectivity ASA
   setup for such newly enrolled network nodes on a link-local connected
   aNI domain node, for example the same node that was providing the
   BRSKI proxy ASA.  This of course is only necessary if those new nodes
   are assumed to be remotely configured/provisioned instead of being
   able to fully self-provision through appropriate autonomous service
   agents.

2.7.1.  Unsecured pledges bringup

   If new devices need to be brought into a domain that does not have
   BRSKI or another stand-alone mechanism to provision domain
   credentials, then a bootstrap proxy agent on a neighboring domain
   node can provide connectivity to such a pledge.  This ASA would
   involve the following aspects:

   *  The ASA is capable to discover the presence of such pledges
      through any pre-existing protocol on the pledge.  This can include
      LLDP, or simply the signaling elements that may be provided by by
      the pledge in DHCP requests and help to identify it.  Use of such
      pre-existing mechanisms would allow to avoid expecting any changes
      to pledges software in factory-fresh condition.  This is
      especially valuable on pledges that allow to later install
      additional softeware easily, such as ASA, e.g.: after enrolment.

   *  The bootstrap proxy agent on this neighboring node indicates the
      presence of such a new pledge through an appropriate new-pledge-
      announcement protocol to an enrollment service that may run on a
      central management node.  For example that server announces via
      GRASP its availaility and the bootstrap proxy agent signals
      presence of new plege(s) to that GRASP discovered server.













Eckert & Liu              Expires 23 April 2026                [Page 15]

Internet-Draft                ACP free aNI                  October 2025


   *  The bootstrap proxy agent implements or orchestrates a transport
      proxy that allows the enrollment servers to connect to sockets on
      the pledge via it. known or assumed to allow remote configuration.
      For example, the transport proxy could be a simple HTTPS server
      implementing only the CONNECT method to such ports on directly
      connected pledges.  The prior step GRASP signaling would inform
      the management node of the discovered (link-local) addresses and
      port(s) on those pledges through appropriate URLs.  Once the
      management station connects to the bootstrap proxy agent and
      issues the HTTP CONNECT, it has a transparent TCP connection to
      the plege.

2.7.2.  BRSKI pledges

   If the pledge can already be enrolled with BRSKI or an equivalently
   secure alternative protocol into the aNI domain, there are a range of
   more options, but it may be a good start to simply use the same
   mechanisms as for an unsecured pledge except for the following.

   Any connections into the pledge after being enrolled via BRSKI SHOULD
   only be via TLS 1.3 or better and use the aNI domain credentials for
   authentication.  Ideally, no insecure ports should need to be open on
   such a to-be-provisioned node.

2.7.3.  aNI bootstrap

   Whether a new, to-be-provisioned node uses BRSKI or not, any aNI
   functionality such as the GRASP coordination agent or any other ASA
   SHOULD be enabled through the provisioning system only after the
   required data-plane connectivity has been provisioned.

   This is beneficial, so that the GRASP coordination agent can
   determine the necessary information about which interface belongs to
   which area from the data-plane configuration.  In the most easy
   provisioning option, the data-plane configuration explicitly labels
   interfaces or addresses with aNI area numbers, so that the GRASP
   coordination agent has this information readily available.
   Otherwise, areas have to be determined by examining VRF membership
   and NAT inside/outside of interfaces/addresses, to automatically
   determine which area they should be assigned to.

2.8.  Inter-domain aNI communications

   Many use cases require communications between ASA that are not in the
   same automation domain.  This section discusses options how to
   support this.





Eckert & Liu              Expires 23 April 2026                [Page 16]

Internet-Draft                ACP free aNI                  October 2025


2.9.  Using aNI domain credentials

   Secure communication via TLS 1.3 or any other equal or better
   strength transport protocol with mutual certificate authentication
   with a peer in a different aNI domain requires mutual trust in the
   other domains aNI certificates.  If for example the domain of a peer1
   is peer1domain.example.com, then secure transport connections to
   peer1 needs a prior provisioning of the trust anchors for
   peer1domain.example.com on the local node.

   aNI certificates and trust-anchors, just like ACP certificates and
   trust anchors are not required to be WebPKI certificates, so no trust
   or enrolment into WebPKI systems is required.  This allows aNI to
   contually operate without any Internet connectivity.  It also
   eliminates any challenges that would otherwise easily be introduced
   with the desire for the certificate to contain private information
   such as the aNI domain information field.  Equally, enrollment and
   renewal of certificates is easily and automated with BRSKI or other
   protocol alternatives.

   In return to these benefits of private aNI certificates, it is
   necessary to provision mapping information between a trusted remote
   aNI domain trust anchors and that domains domain name.

2.10.  Using federated aNI credentials

   To avoid configuring the above described aNI credential to domain
   mapping, typical deployhment cases such as service provider to
   customer interdomain connections, or collaborating service provider
   connections could rely on a common trust anchor and shared private
   (e.g.: BRSKI based certificate enrollment) system.  With such a
   setup, the single root trust anchor of that federation would allow to
   authenticate all federation member certificates, whereas the trust
   anchor of each domains aNI is an intermediate trust anchor, allowing
   all intradomain security to be managed in the same way as without a
   federation.

2.11.  Using WebPKI certificates

   If using WebPKI certificates, including enrollment and renewal, is
   feasible, including the typical necessity of Internet connectivity,
   then aNI nodes requiring interdomain connections could also use such
   WebPKI to communicate with each other, reducing the operational
   complexity to simply configuring which web domain a remote peer is
   expected/permitted to be from.






Eckert & Liu              Expires 23 April 2026                [Page 17]

Internet-Draft                ACP free aNI                  October 2025


3.  Summary

   In-network automation through simply programmed software agents
   called ASA requires a set of underlying infrastructure functions.  In
   the ANI, [RFC8993], these are provided through the combination of
   ACP, BRSKI and GRASP.

   This document outlines how the mayority of this ANI functionality can
   be provided without the need for the expensive to implement ACP, by
   simply making ASA rely on the the already existing connectivity in
   the network, the so-called data-plane.

   The resulting infrastructure module introduced in this document is
   called aNI - automation Network Infrastructure and can be implement
   solely as application-level software running on switches, routers or
   co-located management nodes, not requiring any changes to existing
   IPv6 and/or IPv6 routing and forwarding planes, but instead relying
   solely on transport-layer security (authentication and encryption of
   signaling protocols).

   Most importantly, the aNI can also work in the presence of the wide
   range of connectivity impairing functions in networks such as
   firewalls, NATs, traffic filtering and VRFs.  In the ANI, the ACP
   provided a parallel, unfethered IPv6 connectivity to overcome such
   impairments.  In contrast, in the aNI proxy ASA are required to
   establish connectivity, ranging from simple GRASP service
   announcement proxies that provide the missing connectivity when the
   impairment is because of NAT/PAT, to actual GRASP signaling and
   transport connection proxies, when there is no connectivity possible
   otherwise.  This approach generalizes the approach already used by
   BRSKI proxies.

   The fundamental security of the aNI is the same as in the ANI: domain
   certificates with automatic enrolment via BRSKI or other protocols.
   Like proposed in the ANI, role-based extensions can help to provide
   more fine-grained authentication.















Eckert & Liu              Expires 23 April 2026                [Page 18]

Internet-Draft                ACP free aNI                  October 2025


   The main "shortcoming" of the aNI compared to the ANI is that it does
   not provide (in its current version) transparent end-to-end security
   for pre-existing unsecured signaling protocols such as NTP, SNMP,
   DHCP, DNS, TFTP or other commonly used protocols for the networks
   control and management plane.  This is because since the definition
   of the ACP, secure versions or variations of these protocols have
   become more commonplace, and it is thus more appropriate today to
   expect for those secure evolutions to be used instead of investing
   large amounts of efforts to layer security underneath old protocol
   options. aNI domain certificates enable the seamless security for any
   protocol with TLS 1.3 or better transport layer security options -
   including of course also datagram protocols with DTLS 1.3.

4.  Security considerations

4.1.  Proxying and Security

   Providing remote access to not configured or incorrectly configured
   nodes constitutes a significant security challenge because those
   nodes are most often vulerable to attacks, with typical security
   issues such as open ports with default passwords.

   All proxying of connections towards such nodes described in this
   document is designed such that it can only be initiated from trusted
   nodes with aNI domain certificates - with the assumnption that ithis
   is a sufficient level of security to ensure that the initator is not
   malicious.  If this level of security is deemed insufficient, then
   more fine-grained role based authentication can be added to aNI
   domain certificates as already outline for ANI domain certificates in
   [RFC8994], limiting use of such connection proxies to more
   trustworthy nodes such as management stations.

4.2.  Infrastructure security

   By not building an ACP, the aNI does not have the same level of
   infrastructure security as an ANI.  Specifically attackers that gain
   access to physical links between nodes can inject packets and attempt
   to attack any weak (responder) sockets of network equipment.  The ACP
   prohibits this because it carries all control plane traffic across
   encrypted point-to-point tunnels.  Nevertheless, the aNI does expect
   that all control plane considered to be part of the aNI is protected
   by certifcate based transport layer security, so it does conform to
   todays best established standards for end-to-end security and extends
   it into the hop-by-hop infrastructure.

   To compensate for this lack of infrastructure security, it is
   recommended to not only deploy the "clamshell security" model common
   in service provider networks, but to also design ASA that automate



Eckert & Liu              Expires 23 April 2026                [Page 19]

Internet-Draft                ACP free aNI                  October 2025


   its establishment: Network connectivity to and from IPv4/IPv6
   addresses used between nodes of the aNI SHOULD be filtered on the
   edge of an aNI domain in the forwarding plane (with destination IPv4/
   IPv6 address ACL) so that attackers without access to a physcial link
   between aNI node can not inject the above described attacks.

5.  References

5.1.  Normative References

   [RFC1819]  Delgrossi, L., Ed. and L. Berger, Ed., "Internet Stream
              Protocol Version 2 (ST2) Protocol Specification - Version
              ST2+", RFC 1819, DOI 10.17487/RFC1819, August 1995,
              <https://www.rfc-editor.org/rfc/rfc1819>.

   [RFC8368]  Eckert, T., Ed. and M. Behringer, "Using an Autonomic
              Control Plane for Stable Connectivity of Network
              Operations, Administration, and Maintenance (OAM)",
              RFC 8368, DOI 10.17487/RFC8368, May 2018,
              <https://www.rfc-editor.org/rfc/rfc8368>.

   [RFC8990]  Bormann, C., Carpenter, B., Ed., and B. Liu, Ed., "GeneRic
              Autonomic Signaling Protocol (GRASP)", RFC 8990,
              DOI 10.17487/RFC8990, May 2021,
              <https://www.rfc-editor.org/rfc/rfc8990>.

   [RFC8993]  Behringer, M., Ed., Carpenter, B., Eckert, T., Ciavaglia,
              L., and J. Nobre, "A Reference Model for Autonomic
              Networking", RFC 8993, DOI 10.17487/RFC8993, May 2021,
              <https://www.rfc-editor.org/rfc/rfc8993>.

   [RFC8994]  Eckert, T., Ed., Behringer, M., Ed., and S. Bjarnason, "An
              Autonomic Control Plane (ACP)", RFC 8994,
              DOI 10.17487/RFC8994, May 2021,
              <https://www.rfc-editor.org/rfc/rfc8994>.

   [RFC8995]  Pritikin, M., Richardson, M., Eckert, T., Behringer, M.,
              and K. Watsen, "Bootstrapping Remote Secure Key
              Infrastructure (BRSKI)", RFC 8995, DOI 10.17487/RFC8995,
              May 2021, <https://www.rfc-editor.org/rfc/rfc8995>.

5.2.  Informative References









Eckert & Liu              Expires 23 April 2026                [Page 20]

Internet-Draft                ACP free aNI                  October 2025


   [I-D.eckert-anima-grasp-dnssd]
              Eckert, T. T., Boucadair, M., Jacquenet, C., and M. H.
              Behringer, "DNS-SD Compatible Service Discovery in GeneRic
              Autonomic Signaling Protocol (GRASP)", Work in Progress,
              Internet-Draft, draft-eckert-anima-grasp-dnssd-08, 7 July
              2025, <https://datatracker.ietf.org/doc/html/draft-eckert-
              anima-grasp-dnssd-08>.

Appendix A.  Changelog

A.1.  draft-eckert-anima-acp-free-ani-01

   refresh

A.2.  draft-eckert-anima-acp-free-ani-00

   Initial version

Authors' Addresses

   Toerless Eckert (editor)
   Futurewei Technologies USA
   United States of America
   Email: tte@cs.fau.de


   Bing Liu
   Huawei Technologies
   P.R. China
   Email: leo.liubing@huawei.com





















Eckert & Liu              Expires 23 April 2026                [Page 21]


name: draft-meunier-webbotauth-registry
rev: 01
title: Registry and Signature Agent card for Web bot auth
time: 2025-10-20T12:52:39Z
group_uri: /api/v1/group/group/1027/
expires: 2026-04-23T12:52:39Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Agent identity/auth", "Agent discovery/reg", "Data formats/interop"]
tags: []
fetched_at: 2026-02-27T22:56:05.127621+00:00
abstract:
This document describes a JSON based format for clients using
   [DIRECTORY] to advertise information about themselves.

   This document describes a JSON-based "Signature Agent Card" format
   for signature agent using [DIRECTORY] to advertise metadata about
   themselve.  This includes identity, purpose, rate expectations, and
   cryptographic keys.  It also establishes an IANA registry for
   Signature Agent Card parameters, enabling extensible and
   interoperable discovery of agent information.

full_text:
Web Bot Auth                                                M. Guerreiro
Internet-Draft                                                Cloudflare
Intended status: Informational                                U. Kirazci
Expires: 23 April 2026                                            Amazon
                                                              T. Meunier
                                                              Cloudflare
                                                         20 October 2025


           Registry and Signature Agent card for Web bot auth
                  draft-meunier-webbotauth-registry-01

Abstract

   This document describes a JSON based format for clients using
   [DIRECTORY] to advertise information about themselves.

   This document describes a JSON-based "Signature Agent Card" format
   for signature agent using [DIRECTORY] to advertise metadata about
   themselve.  This includes identity, purpose, rate expectations, and
   cryptographic keys.  It also establishes an IANA registry for
   Signature Agent Card parameters, enabling extensible and
   interoperable discovery of agent information.

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://thibmeu.github.io/http-message-signatures-directory/draft-
   meunier-webbotauth-registry.html.  Status information for this
   document may be found at https://datatracker.ietf.org/doc/draft-
   meunier-webbotauth-registry/.

   Discussion of this document takes place on the Web Bot Auth Working
   Group mailing list (mailto:web-bot-auth@ietf.org), which is archived
   at https://mailarchive.ietf.org/arch/browse/web-bot-auth/.  Subscribe
   at https://www.ietf.org/mailman/listinfo/web-bot-auth/.

   Source for this draft and an issue tracker can be found at
   https://github.com/thibmeu/http-message-signatures-directory.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.





Guerreiro, et al.         Expires 23 April 2026                 [Page 1]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   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 23 April 2026.

Copyright Notice

   Copyright (c) 2025 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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   3
   3.  Signature Agent Card  . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Client Name . . . . . . . . . . . . . . . . . . . . . . .   4
     3.2.  Client URI  . . . . . . . . . . . . . . . . . . . . . . .   5
     3.3.  Contacts  . . . . . . . . . . . . . . . . . . . . . . . .   5
     3.4.  Logo URI  . . . . . . . . . . . . . . . . . . . . . . . .   5
     3.5.  Expected user agent . . . . . . . . . . . . . . . . . . .   5
     3.6.  robots.txt product token  . . . . . . . . . . . . . . . .   6
     3.7.  robots.txt compliance . . . . . . . . . . . . . . . . . .   6
     3.8.  Trigger . . . . . . . . . . . . . . . . . . . . . . . . .   6
     3.9.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . .   6
     3.10. Targeted content  . . . . . . . . . . . . . . . . . . . .   6
     3.11. Rate control  . . . . . . . . . . . . . . . . . . . . . .   7
     3.12. Rate expectation  . . . . . . . . . . . . . . . . . . . .   7
     3.13. Known URLs  . . . . . . . . . . . . . . . . . . . . . . .   7
     3.14. Keys  . . . . . . . . . . . . . . . . . . . . . . . . . .   8
   4.  Discovery . . . . . . . . . . . . . . . . . . . . . . . . . .   8
     4.1.  Formal Syntax . . . . . . . . . . . . . . . . . . . . . .   9
     4.2.  Out-of-band communication between client and origin . . .   9



Guerreiro, et al.         Expires 23 April 2026                 [Page 2]

Internet-Draft  Registry and Signature Agent card for We    October 2025


     4.3.  Public list . . . . . . . . . . . . . . . . . . . . . . .   9
     4.4.  Signature-Agent header  . . . . . . . . . . . . . . . . .  10
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   6.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  10
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
     7.1.  Registration template . . . . . . . . . . . . . . . . . .  10
       7.1.1.  Initial Registry content  . . . . . . . . . . . . . .  11
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  14
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  14
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  16
   Appendix A.  Test Vectors . . . . . . . . . . . . . . . . . . . .  17
   Appendix B.  Implementations  . . . . . . . . . . . . . . . . . .  17
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  17
   Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . .  17
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  17

1.  Introduction

   Signature Agents are entities that originate or forward signed HTTP
   requests on behalf of users or services.  They include bots
   developers, platforms providers, and other intermediaries using
   [DIRECTORY].  These agents often need to identify themselves, and
   establish trust with origin servers.

   Today, the mechanisms for doing so are inconsistent: some rely on
   User-Agent strings (e.g. MyCompanyBot/1.0), others on IP address
   lists hosted on file servers (e.g. badbots.com), and still others on
   out-of-band definitions (e.g. documentation on docs.example.com/
   mybot).  This diversity makes it difficult for operators and origin
   servers to reliably discover and share a Signature Agent’s purpose,
   contact information, or rate expectations.  Existing discovery
   mechanisms, such as [OPENID-CONNECT-DISCOVERY], do not have the
   necessary granularity, and pursue different goals.

   This document introduces a JSON-based "Signature Agent Card" format
   for Signature Agents, to be published in registries and discovered by
   servers.  It also creates a new IANA registry of "Signature Agent
   Card Parameters" to ensure extensibility and consistency of future
   attributes.

2.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.




Guerreiro, et al.         Expires 23 April 2026                 [Page 3]

Internet-Draft  Registry and Signature Agent card for We    October 2025


3.  Signature Agent Card

   Signature-Agent header is defined in Section 4.1 of [DIRECTORY].
   This section describes Signature Agent Card, a JSON object containing
   parameters describing the Signature Agent.

{
  "client_name": "Example Bot",
  "client_uri": "https://example.com/bot/about.html",
  "logo_uri": "https://example.com/",
  "contacts": ["mailto:bot-support@example.com"],
  "expected-user-agent": "Mozilla/5.0 ExampleBot",
  "rfc9309-product-token": "ExampleBot",
  "rfc9309-compliance": ["User-Agent", "Allow", "Disallow", "Content-Usage"],
  "trigger": "fetcher",
  "purpose": "tdm",
  "targeted-content": "Cat pictures",
  "rate-control": "429",
  "rate-expectation": "avg=10rps;max=100rps",
  "known-urls": ["/", "/robots.txt", "*.png"],
  "keys": [{
    "kty": "OKP",
    "crv": "Ed25519",
    "kid": "NFcWBst6DXG-N35nHdzMrioWntdzNZghQSkjHNMMSjw",
    "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs",
    "use": "sig",
    "nbf": 1712793600,
    "exp": 1715385600
  }]
}

   Unless otherwise specified, all parameters in this document are
   OPTIONAL.  There MUST be at least one parameter set.

   Parameters for which the value is unknown MUST be ignored.  All
   string values are UTF-8.

3.1.  Client Name

   The client_name parameter provides a friendly identifier for the
   Signature Agent.

   Example

   *  ExampleBot

   *  My remote browser company




Guerreiro, et al.         Expires 23 April 2026                 [Page 4]

Internet-Draft  Registry and Signature Agent card for We    October 2025


3.2.  Client URI

   The client_uri parameter provides inline content or a web page
   describing the bot: e.g. what does it do, how it handles data it
   fetches.

   Only http, https or data:text/plain are allowed.

   Example

   *  https://example.com/bot/about.html

   *  data:text/plain,The Example bot is about providing an example.

3.3.  Contacts

   The contacts parameter provides reliable communication channels in
   URI forms.  Typically, this is an email address.

   Example

   *  ["mailto:bot-support@example.com"]

   *  ["https://example.com/contact"]

3.4.  Logo URI

   The logo_uri parameter provides an image reference for visual
   identification.

   TODO: Recommendation for size and format, if there is a clear
   consensus or reference we can point to.

   Example

   *  data:image/svg+xml;base64,deadbeef

   *  https://example.com/logo.png

3.5.  Expected user agent

   The expected-user-agent parameter specifies one or more User-Agent
   strings as defined in Section 10.1.5 of [HTTP] or prefix matches.
   Prefixes MAY use * as a wildcard.

   Example

   *  Mozilla/5.0 ExampleBot



Guerreiro, et al.         Expires 23 April 2026                 [Page 5]

Internet-Draft  Registry and Signature Agent card for We    October 2025


3.6.  robots.txt product token

   The rfc9309-product-token parameter specifies the product token used
   for robots.txt directives per Section 2.2.1 of [ROBOTSTXT].

   Example

   *  ExampleBot

3.7.  robots.txt compliance

   The rfc9309-compliance parameter lists directives from robots.txt
   that the agent implements.

   Example

   *  ["User-Agent", "Disallow"]

   *  ["User-Agent", "Disallow", "CrawlDelay"]

3.8.  Trigger

   The trigger parameter indicates the operational mode of the agent.

   Valid values:

   1.  fetcher - request initiated by the user

   2.  crawler - autonomous scanning

3.9.  Purpose

   The purpose parameter describes the intended use of collected data.
   Values SHOULD be drawn from a controlled vocabulary, such as
   [AIPREF-VOCAB].

   Example

   *  search

   *  tdm

3.10.  Targeted content

   The targeted-content parameter specifies the type of data the agent
   seeks.  Its format is arbitrary UTF-8 encoded string.

   Example



Guerreiro, et al.         Expires 23 April 2026                 [Page 6]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   *  SEO analysis

   *  Vulnerability scanning

   *  Ads verification

3.11.  Rate control

   The rate-control parameter indicates how origins can influence the
   agent’s request rate.

   TODO: specify a format

   Example

   *  CrawlDelay in robots.txt (non-standard)

   *  Custom tool

   *  429 + [RATELIMIT-HEADER]

3.12.  Rate expectation

   The rate-expectation parameter specifies anticipated request volume
   or burstiness.

   TODO: consider a format such as avg=10rps;max=100rps

   Example

   *  500 rps

   *  Spikes during reindexing

3.13.  Known URLs

   The known-urls parameter lists predictable endpoints accessed by the
   agent.

   These URLs may be absolute URLs like https://example.com/index.html.
   They could be relative path like /ads.txt.  Or they can use * as
   wildcard such as *.png.

   Example

   *  ["/"]

   *  ["/ads.txt"]



Guerreiro, et al.         Expires 23 April 2026                 [Page 7]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   *  ["/favicon.ico"]

   *  ["/index.html"]

3.14.  Keys

   The keys parameter contains a JWKS as defined in Section 5 of [JWK].

   If keys is present, it is RECOMMENDED that the card is signed using
   [HTTP-MESSAGE-SIGNATURES].  Content-Digest header MUST be included in
   the covered components.

   TODO: describe signature, CWS keys.

   Example

   *  https://example.com/.well-known/http-message-signatures-directory

   *  JWKS-directory

4.  Discovery

   A registry is a list of URLs, each refering to a signature agent
   card.

   The URI scheme MUST be one of:

   *  https (RECOMMENDED): Points to an HTTPS resource serving a
      signature agent card

   *  http: Points to an HTTP resource serving a signature agent card

   *  data: Contains an inline signature agent card

   Example

   # An example list of bots
   https://bot1.example.com/.well-known/signature-agent-card
   https://crawler2.example.com/.well-known/signature-agent-card

   # Now the list of platforms
   https://zerotrust-gateway.example.com/.well-known/signature-agent-card

   # Below is an inlined card with the data URL scheme
   data:application/json;,... # Invalid, not defined






Guerreiro, et al.         Expires 23 April 2026                 [Page 8]

Internet-Draft  Registry and Signature Agent card for We    October 2025


4.1.  Formal Syntax

   Below is an Augmented Backus-Naur Form (ABNF) description, as
   described in [ABNF].

   The below definition imports http-URI and https-URI from [HTTP], and
   dataurl from [DATAURL].

   registry = *(cardendpointline / emptyline)
   cardendpointline = (
       http-URI /       ; As defined in Section 4.2.1 of RFC 9110
       https-URI /      ; As defined in Section 4.2.2 of RFC 9110
       dataurl          ; As defined in Section 3 of RFC 2397
   ) EOL


   comment = "#" *(UTF8-char-noctl / WS / "#")
   emptyline = EOL
   EOL = *WS [comment] NL ; end-of-line may have
                          ; optional trailing comment
   NL = %x0D / %x0A / %x0D.0A
   WS = %x20 / %x09

   ; UTF8 derived from RFC 3629, but excluding control characters

   UTF8-char-noctl = UTF8-1-noctl / UTF8-2 / UTF8-3 / UTF8-4
   UTF8-1-noctl = %x21 / %x22 / %x24-7F ; excluding control, space, "#"
   UTF8-2 = %xC2-DF UTF8-tail
   UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
            %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
   UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
            %xF4 %x80-8F 2UTF8-tail

   UTF8-tail = %x80-BF

4.2.  Out-of-band communication between client and origin

   A signature agent MAY submit their signature agent card to an origin,
   or the origin MAY manually add them to their local registry.

4.3.  Public list

   A registry MAY be provided via a GitHub repository, a public file
   server, or a dedicated endpoint.

   The registry SHOULD be served over HTTPS.





Guerreiro, et al.         Expires 23 April 2026                 [Page 9]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   A client application SHOULD validate the directory format and reject
   malformed entries.

4.4.  Signature-Agent header

   Signature Agent Card format defined in Section 3 extends the format
   of Signature-Agent header as defined in Section 4.1 of [DIRECTORY].

   When used for HTTP Message Signatures, and hosted on a well-known
   URL, Signature Agent Card MAY be discovered via a Signature-Agent
   header.

5.  Security Considerations

   Malicious actors may put properties which are not theirs in the
   registry.  If signatures are present, clients MUST verify them.
   Clients SHOULD reject cards with invalid signatures.

6.  Privacy Considerations

   TODO

7.  IANA Considerations

7.1.  Registration template

   New registrations need to list the following attributes:

   *Parameter Name:*  The name requested (e.g. "useragent").  This name
      is case sensitive.  Names may not match other registered names in
      a case-insensitive manner unless the Designated Experts state that
      there is a compelling reason to allow an exception
   *Parameter Description:*  Brief description of the Header Parameter
   *Change Controller:*  For Standards Track RFCs, list the "IESG".  For
      others, give the name of the responsible party.  Other details
      (e.g., postal address, email address, home page URI) may also be
      included.
   *Reference:*  Where this parameter is defined
   *Notes:*  Any notes associated with the entry

   New entries in this registry are subject to the Specification
   Required registration policy ([RFC8126], Section 4.6).  Designated
   experts need to ensure that the token type is defined to be used for
   both token issuance and redemption.  Additionally, the experts can
   reject registrations on the basis that they do not meet the security
   and privacy requirements defined in TODO.





Guerreiro, et al.         Expires 23 April 2026                [Page 10]

Internet-Draft  Registry and Signature Agent card for We    October 2025


7.1.1.  Initial Registry content

   This section registers the Signature Agent Card Parameter names
   defined in Section 3 in this registry.

7.1.1.1.  Client Name Parameter

   *Parameter Name:*  client_name

   *Parameter Description:*  A friendly name for your signature agent.

   *Change Controller:*  IETF

   *Reference:*  Section 3.1

   *Notes:*  N/A

7.1.1.2.  Client URI Parameter

   *Parameter Name:*  client_uri

   *Parameter Description:*  Describes what the bot does inline with
      data URI or with an HTTP link to an external resource

   *Change Controller:*  IETF

   *Reference:*  Section 3.2

   *Notes:*  N/A

7.1.1.3.  Logo URI Parameter

   *Parameter Name:*  logo_uri

   *Parameter Description:*  Image for a quick visual identification

   *Change Controller:*  IETF

   *Reference:*  Section 3.4

   *Notes:*  N/A

7.1.1.4.  Contacts Parameter

   *Parameter Name:*  contacts

   *Parameter Description:*  An array of URI with a reliable
      communication channel; typically email addresses



Guerreiro, et al.         Expires 23 April 2026                [Page 11]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   *Change Controller:*  IETF

   *Reference:*  Section 3.3

   *Notes:*  N/A

7.1.1.5.  Expected User Agent Parameter

   *Parameter Name:*  expected-user-agent

   *Parameter Description:*  String or fragment patterns

   *Change Controller:*  IETF

   *Reference:*  Section 3.5

   *Notes:*  N/A

7.1.1.6.  RFC9309 Product Token Parameter

   *Parameter Name:*  rfc9309-product-token

   *Parameter Description:*  Robots.txt product token your signature-
      agent satisfies.

   *Change Controller:*  IETF

   *Reference:*  Section 3.6

   *Notes:*  N/A

7.1.1.7.  RFC9309 Compliance Parameter

   *Parameter Name:*  rfc9309-compliance

   *Parameter Description:*  Does your signature-agent respect
      robots.txt.

   *Change Controller:*  IETF

   *Reference:*  Section 3.7

   *Notes:*  N/A

7.1.1.8.  Trigger Parameter

   *Parameter Name:*  trigger




Guerreiro, et al.         Expires 23 April 2026                [Page 12]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   *Parameter Description:*  Fetcher/Crawler

   *Change Controller:*  IETF

   *Reference:*  Section 3.8

   *Notes:*  N/A

7.1.1.9.  Purpose Parameter

   *Parameter Name:*  purpose

   *Parameter Description:*  Intended use for the collected data

   *Change Controller:*  IETF

   *Reference:*  Section 3.9

   *Notes:*  N/A

7.1.1.10.  Targeted Content Parameter

   *Parameter Name:*  targeted-content

   *Parameter Description:*  Type of data your agent seeks

   *Change Controller:*  IETF

   *Reference:*  Section 3.10

   *Notes:*  N/A

7.1.1.11.  Rate control Parameter

   *Parameter Name:*  rate-control

   *Parameter Description:*  How can an origin control your crawl rate

   *Change Controller:*  IETF

   *Reference:*  Section 3.11

   *Notes:*  N/A

7.1.1.12.  Rate expectation Parameter

   *Parameter Name:*  rate-expectation




Guerreiro, et al.         Expires 23 April 2026                [Page 13]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   *Parameter Description:*  Expected traffic and intensity

   *Change Controller:*  IETF

   *Reference:*  Section 3.12

   *Notes:*  N/A

7.1.1.13.  Known URLs Parameter

   *Parameter Name:*  known-urls

   *Parameter Description:*  Predictable endpoint accessed

   *Change Controller:*  IETF

   *Reference:*  Section 3.13

   *Notes:*  N/A

7.1.1.14.  Keys Parameter

   *Parameter Name:*  keys

   *Parameter Description:*  JWKS Endpoint

   *Change Controller:*  IETF

   *Reference:*  Section 3.14

   *Notes:*  N/A

8.  References

8.1.  Normative References

   [ABNF]     Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/rfc/rfc5234>.

   [AIPREF-VOCAB]
              Keller, P. and M. Thomson, "A Vocabulary For Expressing AI
              Usage Preferences", Work in Progress, Internet-Draft,
              draft-ietf-aipref-vocab-03, 4 September 2025,
              <https://datatracker.ietf.org/doc/html/draft-ietf-aipref-
              vocab-03>.




Guerreiro, et al.         Expires 23 April 2026                [Page 14]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   [DIRECTORY]
              Meunier, T., "HTTP Message Signatures Directory", Work in
              Progress, Internet-Draft, draft-meunier-http-message-
              signatures-directory-04, 20 October 2025,
              <https://datatracker.ietf.org/doc/html/draft-meunier-http-
              message-signatures-directory-04>.

   [HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9110>.

   [HTTP-CACHE]
              Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Caching", STD 98, RFC 9111,
              DOI 10.17487/RFC9111, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9111>.

   [HTTP-MESSAGE-SIGNATURES]
              Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
              Message Signatures", RFC 9421, DOI 10.17487/RFC9421,
              February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

   [HTTP-MORE-STATUS-CODE]
              Nottingham, M. and R. Fielding, "Additional HTTP Status
              Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
              <https://www.rfc-editor.org/rfc/rfc6585>.

   [JWK]      Jones, M., "JSON Web Key (JWK)", RFC 7517,
              DOI 10.17487/RFC7517, May 2015,
              <https://www.rfc-editor.org/rfc/rfc7517>.

   [JWK-OKP]  Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH)
              and Signatures in JSON Object Signing and Encryption
              (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017,
              <https://www.rfc-editor.org/rfc/rfc8037>.

   [JWK-THUMBPRINT]
              Jones, M. and N. Sakimura, "JSON Web Key (JWK)
              Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
              2015, <https://www.rfc-editor.org/rfc/rfc7638>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.





Guerreiro, et al.         Expires 23 April 2026                [Page 15]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/rfc/rfc8126>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

8.2.  Informative References

   [DATAURL]  Masinter, L., "The "data" URL scheme", RFC 2397,
              DOI 10.17487/RFC2397, August 1998,
              <https://www.rfc-editor.org/rfc/rfc2397>.

   [OAUTH-BEARER]
              Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012,
              <https://www.rfc-editor.org/rfc/rfc6750>.

   [OPENID-CONNECT-DISCOVERY]
              "OpenID Connect Discovery 1.0", n.d.,
              <https://openid.net/specs/openid-connect-discovery-
              1_0.html>.

   [RATELIMIT-HEADER]
              Polli, R., Ruiz, A. M., and D. Miller, "RateLimit header
              fields for HTTP", Work in Progress, Internet-Draft, draft-
              ietf-httpapi-ratelimit-headers-10, 27 September 2025,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-
              ratelimit-headers-10>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/rfc/rfc8446>.

   [ROBOTSTXT]
              Koster, M., Illyes, G., Zeller, H., and L. Sassman,
              "Robots Exclusion Protocol", RFC 9309,
              DOI 10.17487/RFC9309, September 2022,
              <https://www.rfc-editor.org/rfc/rfc9309>.

   [UTF8]     Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
              2003, <https://www.rfc-editor.org/rfc/rfc3629>.





Guerreiro, et al.         Expires 23 April 2026                [Page 16]

Internet-Draft  Registry and Signature Agent card for We    October 2025


Appendix A.  Test Vectors

   TODO

Appendix B.  Implementations

   TODO

Acknowledgments

   TODO

   The editor would also like to thank the following individuals (listed
   in alphabetical order) for feedback, insight, and implementation of
   this document -

Changelog

   v01

   *  Add contributors

   *  Aligning registry draft with oauth dynamic client registration
      iana registry

   *  Add an about-url field

   *  Add ABNF for discovery of signature-agent card (registry)

   *  Add precisions about known URLs

   *  Add placeholder for image size

   v00

   *  Initial draft

Authors' Addresses

   Maxime Guerreiro
   Cloudflare
   Email: maxime.guerreiro@gmail.com


   Ulas Kirazci
   Amazon
   Email: ulaskira@amazon.com




Guerreiro, et al.         Expires 23 April 2026                [Page 17]

Internet-Draft  Registry and Signature Agent card for We    October 2025


   Thibault Meunier
   Cloudflare
   Email: ot-ietf@thibault.uk
















































Guerreiro, et al.         Expires 23 April 2026                [Page 18]


