diff --git a/content/application-service-api.md b/content/application-service-api.md index 582abf81..c3c54822 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -86,57 +86,18 @@ by POSIX extended regular expressions and look like: Application services may define the following namespaces (with none being explicitly required): -
Name | -Description | -
---|---|
users | -Events which are sent from certain users. | -
aliases | -Events which are sent in rooms with certain room aliases. | -
rooms | -Events which are sent in rooms with certain room IDs. | -
Name | -Description | -
---|---|
exclusive | -Required A true or false value stating whether this application service has exclusive access to events within this namespace. | -
regex | -Required A regular expression defining which values this namespace includes. | -
Name | -Description | -
---|---|
id | -Required. A unique, user-defined ID of the application service which will never change. | -
url | -Required. The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required. |
-
as_token | -Required. A unique token for application services to use to authenticate requests to Homeservers. | -
hs_token | -Required. A unique token for Homeservers to use to authenticate requests to application services. | -
sender_localpart | -Required. The localpart of the user associated with the application service. | -
namespaces | -Required. A list of users , aliases and rooms namespaces that the application service controls. |
-
rate_limited | -Whether requests from masqueraded users are rate-limited. The sender is excluded. | -
protocols | -The external protocols which the application service provides (e.g. IRC). | -
Key | -Type | -Description | -
---|---|---|
state_key | -string | -Required. A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. |
-
prev_content | -EventContent | -Optional. The previous content for this event. If there is no previous content, this key will be missing. |
-
Parameter | -Type | -Description | -
---|---|---|
key |
-string |
-Required. The unpadded Base64-encoded 32-byte Curve25519 public key. |
-
signatures |
-Signatures |
-Required. Signatures of the key object. -The signature is calculated using the process described at Signing JSON. |
-
Parameter | -Type | -Description | -
---|---|---|
url | -string | -Required. The URL to the file. | -
key | -JWK | -Required. A JSON Web Key object. | -
iv |
-string |
-Required. The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
-
hashes |
-{string: string} |
-Required. A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key |
-
v |
-string |
-Required. Version of the encrypted attachments protocol. Must be |
-
Parameter | -Type | -Description | -
---|---|---|
kty | -string | -Required. Key type. Must be oct . |
-
key_ops |
-[string] |
-Required. Key operations. Must at least contain |
-
alg | -string | -Required. Algorithm. Must be A256CTR . |
-
k | -string | -Required. The key, encoded as urlsafe unpadded base64. | -
ext |
-boolean |
-Required. Extractable. Must be |
-
Parameter | -Type | -Description | -
---|---|---|
public_key |
-string |
-Required. The curve25519 public key used to encrypt the backups, encoded in unpadded base64. |
-
signatures |
-Signatures |
-Optional. Signatures of the |
-
Parameter | -Type | -Description | -
---|---|---|
algorithm |
- string |
- Required. The end-to-end message encryption algorithm that the key is for. Must be |
-
forwarding_curve25519_key_chain |
- [string] |
- Required. Chain of Curve25519 keys through which this session was forwarded, via m.forwarded_room_key events. |
-
sender_key |
- string |
- Required. Unpadded base64-encoded device curve25519 key. |
-
sender_claimed_keys |
- {string: string} |
- Required. A map from algorithm name ( |
-
session_key |
- string |
- Required. Unpadded base64-encoded session key in session-sharing format. |
-
Size (bytes) | -Description | -
---|---|
1 | -Export format version, which must be 0x01 . |
-
16 | -The salt S. | -
16 | -The initialization vector IV. | -
4 | -The number of rounds N, as a big-endian unsigned 32-bit integer. | -
variable | -The encrypted JSON object. | -
32 |
- The HMAC-SHA-256 of all the above string concatenated together, using K' as the key. |
-
Parameter | -Type | -Description | -
---|---|---|
algorithm |
-string |
-Required. The encryption algorithm that the session uses. Must be |
-
forwarding_curve25519_key_chain |
-[string] |
-Required. Chain of Curve25519 keys through which this session was forwarded, via m.forwarded_room_key events. |
-
room_id |
-string |
-Required. The room where the session is used. |
-
sender_key |
-string |
-Required. The Curve25519 key of the device which initiated the session originally. |
-
sender_claimed_keys |
-{string: string} |
-Required. The Ed25519 key of the device which initiated the session originally. |
-
session_id | -string | -Required. The ID of the session. | -
session_key | -string | -Required. The key for the session. | -
Parameter | -Type | -Description | -
---|---|---|
device_lists |
-DeviceLists |
-Optional. Information on e2e device updates. Note: only present on an incremental sync. |
-
device_one_time_keys_count |
-{string: integer} |
-Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. |
-
Parameter | -Type | -Description | -
---|---|---|
changed |
-[string] |
-List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
-
left |
-[string] |
-List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |
-
Parameter | -Type | -Description | -
---|---|---|
name | -string | -Required. The name of the key. | -
algorithm |
-string |
-Required. The encryption algorithm to be used for this key. Currently, only |
-
passphrase |
-string |
-See deriving keys from passphrases section for a description of this property. |
-
Parameter | -Type | -Description | -
---|---|---|
encrypted |
-{string: object} |
-Required. Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of |
-
Parameter | -Type | -Description | -
---|---|---|
iv |
-string |
-Required. The 16-byte initialization vector, encoded as base64. |
-
ciphertext |
-string |
-Required. The AES-CTR-encrypted data, encoded as base64. |
-
mac | -string | -Required. The MAC, encoded as base64. | -
Parameter | -Type | -Description | -
---|---|---|
name | -string | -Required. The name of the key. | -
algorithm |
-string |
-Required. The encryption algorithm to be used for this key. Currently, only |
-
passphrase |
-object |
-See deriving keys from passphrases section for a description of this property. |
-
iv | -string | -The 16-byte initialization vector, encoded as base64. | -
mac |
-string |
-The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
-
Parameter | -Type | -Description | -
---|---|---|
algorithm | -string | -Required. Must be m.pbkdf2 |
-
salt | -string | -Required. The salt used in PBKDF2. | -
iterations | -integer | -Required. The number of iterations to use in PBKDF2. | -
bits |
-integer |
-Optional. The number of bits to generate for the key. Defaults to 256. |
-
Parameter | -Type | -Description | -
---|---|---|
name |
-string |
-Required if |
-
action | -enum | -Required. One of ["request", "request_cancellation"]. | -
requesting_device_id | -string | -Required. The ID of the device requesting the secret. | -
request_id |
-string |
-Required. A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request. |
-
Parameter | -Type | -Description | -
---|---|---|
request_id | -string | -Required. The ID of the request that this a response to. | -
secret | -string | -Required. The contents of the secret. | -
Parameter | -Type | -Description | -
---|---|---|
to_device |
-ToDevice |
-Optional. Information on the send-to-device messages for the client device. |
-
Parameter | -Type | -Description | -
---|---|---|
events | -[Event] | -List of send-to-device messages. | -
Parameter | -Type | -Description | -
---|---|---|
content |
-EventContent |
-The content of this event. The fields in this object will vary depending on the type of event. |
-
sender |
-string |
-The Matrix user ID of the user who sent this event. |
-
type | -string | -The type of event. | -
Name | -GitHub Label | -Description | -
---|---|---|
Proposal Drafting and Feedback | -N/A | -A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with [WIP] to make it easier for reviewers to skim their notifications list. |
-
Proposal In Review | -proposal-in-review | -A proposal document which is now ready and waiting for review by the Spec Core Team and community | -
Proposed Final Comment Period | -proposed-final-comment-period | -Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period | -
Final Comment Period | -final-comment-period | -A proposal document which has reached final comment period either for merge, closure or postponement | -
Final Comment Period Complete | -finished-final-comment-period | -The final comment period has been completed. Waiting for a demonstration implementation | -
Spec PR Missing | -spec-pr-missing | -The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec | -
Spec PR In Review | -spec-pr-in-review | -The spec PR has been written, and is currently under review | -
Spec PR Merged | -merged | -A proposal with a sufficient working implementation and whose Spec PR has been merged! | -
Postponed |
-proposal-postponed |
-A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future |
-
Closed | -proposal-closed | -A proposal which has been reviewed and deemed unsuitable for acceptance | -
Obsolete | -obsolete | -A proposal which has been made obsolete by another proposal or decision elsewhere. | -
Name | -GitHub Label | -Description | -
---|---|---|
Core | -kind:core | -Important for the protocol's success. | -
Feature | -kind:feature | -Nice to have additions to the spec. | -
Maintenance | -kind:maintenance | -Fixes or clarifies existing spec. | -