From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc9425.txt | 518 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 doc/rfc/rfc9425.txt (limited to 'doc/rfc/rfc9425.txt') diff --git a/doc/rfc/rfc9425.txt b/doc/rfc/rfc9425.txt new file mode 100644 index 0000000..0cf697d --- /dev/null +++ b/doc/rfc/rfc9425.txt @@ -0,0 +1,518 @@ + + + + +Internet Engineering Task Force (IETF) R. Cordier, Ed. +Request for Comments: 9425 Linagora Vietnam +Category: Standards Track June 2023 +ISSN: 2070-1721 + + + JSON Meta Application Protocol (JMAP) for Quotas + +Abstract + + This document specifies a data model for handling quotas on accounts + with a server using the JSON Meta Application Protocol (JMAP). + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9425. + +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. Notational Conventions + 1.2. Terminology + 2. Addition to the Capabilities Object + 2.1. urn:ietf:params:jmap:quota + 3. Sub-types of the Quota Data Type + 3.1. Scope + 3.2. ResourceType + 4. Quota + 4.1. Properties of the Quota Object + 4.2. Quota/get + 4.3. Quota/changes + 4.4. Quota/query + 4.5. Quota/queryChanges + 5. Examples + 5.1. Fetching Quotas + 5.2. Requesting Latest Quota Changes + 6. Push + 7. IANA Considerations + 7.1. JMAP Capability Registration for "quota" + 7.2. JMAP Data Type Registration for "Quota" + 8. Security Considerations + 9. Normative References + Acknowledgements + Author's Address + +1. Introduction + + The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic + protocol for synchronizing data, such as mails, calendars, or + contacts between a client and a server. It is optimized for mobile + and web environments and aims to provide a consistent interface to + different data types. + + This specification defines a data model for handling quotas over + JMAP, allowing a user to obtain details about a certain quota. + + This specification does not address quota administration, which + should be handled by other means. + +1.1. Notational Conventions + + 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. + + Type signatures, examples, and property descriptions in this document + follow the conventions established in Section 1.1 of [RFC8620]. Data + types defined in the core specification are also used in this + document. + +1.2. Terminology + + This document reuses the terminology from the core JMAP specification + established in Section 1.6 of [RFC8620]. + + The term "Quota" (when capitalized) is used to refer to the data type + defined in Section 4 and instance of that data type. + +2. Addition to the Capabilities Object + + The capabilities object is returned as part of the JMAP Session + object; see [RFC8620], Section 2. + + This document defines one additional capability URI. + +2.1. urn:ietf:params:jmap:quota + + This represents support for the Quota data type and associated API + methods. Servers supporting this specification MUST add a property + called "urn:ietf:params:jmap:quota" to the capabilities object. + + The value of this property is an empty object in both the JMAP + Session capabilities property and an account's accountCapabilities + property. + +3. Sub-types of the Quota Data Type + + There are two fields within the Quota data type, which have an + enumerated set of possible values. These are: + +3.1. Scope + + The Scope data type is used to represent the entities the quota + applies to. It is defined as a "String" with values from the + following set: + + * account: The quota information applies to just the client's + account. + + * domain: The quota information applies to all accounts sharing this + domain. + + * global: The quota information applies to all accounts belonging to + the server. + +3.2. ResourceType + + The ResourceType data type is used to act as a unit of measure for + the quota usage. It is defined as a "String" with values from the + following set: + + * count: The quota is measured in a number of data type objects. + For example, a quota can have a limit of 50 "Mail" objects. + + * octets: The quota is measured in size (in octets). For example, a + quota can have a limit of 25000 octets. + +4. Quota + + The Quota is an object that displays the limit set to an account + usage. It then shows as well the current usage in regard to that + limit. + +4.1. Properties of the Quota Object + + The Quota object MUST contain the following fields: + + * id: Id + + The unique identifier for this object. + + * resourceType: String + + The resource type of the quota as defined in Section 3.2. + + * used: UnsignedInt + + The current usage of the defined quota, using the "resourceType" + defined as unit of measure. Computation of this value is handled + by the server. + + * hardLimit: UnsignedInt + + The hard limit set by this quota, using the "resourceType" defined + as unit of measure. Objects in scope may not be created or + updated if this limit is reached. + + * scope: String + + The "Scope" of this quota as defined in Section 3.1. + + * name: String + + The name of the quota. Useful for managing quotas and using + queries for searching. + + * types: String[] + + A list of all the type names as defined in the "JMAP Types Names" + registry (e.g., Email, Calendar, etc.) to which this quota + applies. This allows the quotas to be assigned to distinct or + shared data types. + + The server MUST filter out any types for which the client did not + request the associated capability in the "using" section of the + request. Further, the server MUST NOT return Quota objects for + which there are no types recognized by the client. + + The Quota object MAY contain the following fields: + + * warnLimit: UnsignedInt|null + + The warn limit set by this quota, using the "resourceType" defined + as unit of measure. It can be used to send a warning to an entity + about to reach the hard limit soon, but with no action taken yet. + If set, it SHOULD be lower than the "softLimit" (if present and + different from null) and the "hardLimit". + + * softLimit: UnsignedInt|null + + The soft limit set by this quota, using the "resourceType" defined + as unit of measure. It can be used to still allow some operations + but refuse some others. What is allowed or not is up to the + server. For example, it could be used for blocking outgoing + events of an entity (sending emails, creating calendar events, + etc.) while still receiving incoming events (receiving emails, + receiving calendars events, etc.). If set, it SHOULD be higher + than the "warnLimit" (if present and different from null) but + lower than the "hardLimit". + + * description: String|null + + Arbitrary, free, human-readable description of this quota. It + might be used to explain where the different limits come from and + explain the entities and data types this quota applies to. The + description MUST be encoded in UTF-8 [RFC3629] as described in + [RFC8620], Section 1.5, and selected based on an Accept-Language + header in the request (as defined in [RFC9110], Section 12.5.4) or + out-of-band information about the user's language or locale. + + The following JMAP methods are supported. + +4.2. Quota/get + + Standard "/get" method as described in [RFC8620], Section 5.1. The + _id_'s argument may be "null" to fetch all quotas of the account at + once, as demonstrated in Section 5.1. + +4.3. Quota/changes + + Standard "/changes" method as described in [RFC8620], Section 5.2, + but with one extra argument in the response: + + * updatedProperties: String[]|null + + If only the "used" Quota property has changed since the old state, + this will be a list containing only that property. If the server + is unable to tell if only "used" has changed, it MUST be null. + + Since "used" frequently changes, but other properties are generally + only changed rarely, the server can help the client optimize data + transfer by keeping track of changes to quota usage separate from + other state changes. The updatedProperties array may be used + directly via a back-reference in a subsequent Quota/get call in the + same request, so only these properties are returned if nothing else + has changed. + + Servers MAY decide to add other properties to the list that they + judge to be changing frequently. + + This method's usage is demonstrated in Section 5.2. + +4.4. Quota/query + + This is a standard "/query" method as described in [RFC8620], + Section 5.5. + + A FilterCondition object has the following properties, any of which + may be included or omitted: + + * name: String + + The Quota _name_ property contains the given string. + + * scope: String + + The Quota _scope_ property must match the given value exactly. + + * resourceType: String + + The Quota _resourceType_ property must match the given value + exactly. + + * type: String + + The Quota _types_ property contains the given value. + + A Quota object matches the FilterCondition if, and only if, all the + given conditions match. If zero properties are specified, it is + automatically true for all objects. + + The following Quota properties MUST be supported for sorting: + + * name + + * used + +4.5. Quota/queryChanges + + This is a standard "/queryChanges" method as described in [RFC8620], + Section 5.6. + +5. Examples + +5.1. Fetching Quotas + + Request fetching all quotas related to an account: + + [[ "Quota/get", { + "accountId": "u33084183", + "ids": null + }, "0" ]] + + With response: + + [[ "Quota/get", { + "accountId": "u33084183", + "state": "78540", + "list": [{ + "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", + "resourceType": "count", + "used": 1056, + "warnLimit": 1600, + "softLimit": 1800, + "hardLimit": 2000, + "scope": "account", + "name": "bob@example.com", + "description": "Personal account usage. When the soft limit is + reached, the user is not allowed to send mails or + create contacts and calendar events anymore.", + "types" : [ "Mail", "Calendar", "Contact" ] + }, { + "id": "3b06df0e-3761-4s74-a92f-74dcc963501x", + "resourceType": "octets", + ... + }, ...], + "notFound": [] + }, "0" ]] + +5.2. Requesting Latest Quota Changes + + Request fetching the changes for a specific quota: + + [[ "Quota/changes", { + "accountId": "u33084183", + "sinceState": "78540", + "maxChanges": 20 + }, "0" ], + [ "Quota/get", { + "accountId": "u33084183", + "#ids": { + "resultOf": "0", + "name": "Quota/changes", + "path": "/updated" + }, + "#properties": { + "resultOf": "0", + "name": "Quota/changes", + "path": "/updatedProperties" + } + }, "1" ]] + + With response: + + [[ "Quota/changes", { + "accountId": "u33084183", + "oldState": "78540", + "newState": "78542", + "hasMoreChanges": false, + "updatedProperties": ["used"], + "created": [], + "updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"], + "destroyed": [] + }, "0" ], + [ "Quota/get", { + "accountId": "u33084183", + "state": "10826", + "list": [{ + "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", + "used": 1246 + }], + "notFound": [] + }, "1" ]] + +6. Push + + Servers MUST support the JMAP push mechanisms, as specified in + [RFC8620], Section 7, to allow clients to receive notifications when + the state changes for the Quota type defined in this specification. + +7. IANA Considerations + +7.1. JMAP Capability Registration for "quota" + + IANA has registered the "quota" JMAP Capability as follows: + + Capability Name: urn:ietf:params:jmap:quota + + Reference: RFC 9425 + + Intended Use: common + + Change Controller: IETF + + Security and Privacy Considerations: RFC 9425, Section 8 + +7.2. JMAP Data Type Registration for "Quota" + + IANA has registered the "Quota" Data Type as follows: + + Type Name: Quota + + Can Reference Blobs: No + + Can Use for State Change: Yes + + Capability: urn:ietf:params:jmap:quota + + Reference: RFC 9425 + +8. Security Considerations + + All security considerations of JMAP [RFC8620] apply to this + specification. + + Implementors should be careful to make sure the implementation of the + extension specified in this document does not violate the site's + security policy. The resource usage of other users is likely to be + considered confidential information and should not be divulged to + unauthorized persons. + + As for any resource shared across users (for example, a quota with + the "domain" or "global" scope), a user that can consume the resource + can affect the resources available to the other users. For example, + a user could spam themselves with events and make the shared resource + hit the limit and unusable for others (implementors could mitigate + that with some rate-limiting implementation on the server). + + Also, revealing domain and global quota counts to all users may cause + privacy leakage of other sensitive data, or at least the existence of + other sensitive data. For example, some users are part of a private + list belonging to the server, so they shouldn't know how many users + are in there. However, by comparing the quota count before and after + sending a message to the list, it could reveal the number of people + of the list, as the domain or global quota count would go up by the + number of people subscribed. In order to limit those attacks, quotas + with "domain" or "global" scope SHOULD only be visible to server + administrators and not to general users. + +9. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application + Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July + 2019, . + + [RFC9007] Ouazana, R., Ed., "Handling Message Disposition + Notification with the JSON Meta Application Protocol + (JMAP)", RFC 9007, DOI 10.17487/RFC9007, March 2021, + . + + [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, + Ed., "HTTP Semantics", STD 97, RFC 9110, + DOI 10.17487/RFC9110, June 2022, + . + +Acknowledgements + + Thank you to Michael Bailly, who co-wrote the first draft version of + this document, before deciding to turn to other matters. + + Thank you to Benoit Tellier for his constant help and support on + writing this document. + + Thank you to Raphael Ouazana for sharing his own experience on how to + write an RFC after finalizing his own document: [RFC9007]. + + Thank you to Bron Gondwana, Neil Jenkins, Alexey Melnikov, Joris + Baum, and the people from the IETF JMAP working group in general, who + helped with extensive discussions, reviews, and feedback. + + Thank you to the people in the IETF organization, who took the time + to read, understand, comment, and give great feedback in the last + rounds. + +Author's Address + + René Cordier (editor) + Linagora Vietnam + 5 Dien Bien Phu + Hanoi + 10000 + Vietnam + Email: rcordier@linagora.com + URI: https://linagora.vn -- cgit v1.2.3