From d5098638a0e49506760bfc1e894506619eea391d Mon Sep 17 00:00:00 2001 From: bitfl0wer Date: Thu, 9 Jan 2025 16:08:34 +0100 Subject: [PATCH] Refactor section 6.1.1.1, define FID part names --- .vscode/ltex.dictionary.en-US.txt | 1 + docs/Protocol Specifications/core.md | 89 +++++++++++++++------------- 2 files changed, 50 insertions(+), 40 deletions(-) diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt index 51b58bcf..2aa0f2dd 100644 --- a/.vscode/ltex.dictionary.en-US.txt +++ b/.vscode/ltex.dictionary.en-US.txt @@ -24,3 +24,4 @@ TypeSpec Protobuf gzipped RawR +OID diff --git a/docs/Protocol Specifications/core.md b/docs/Protocol Specifications/core.md index 888bb834..12e4ed64 100644 --- a/docs/Protocol Specifications/core.md +++ b/docs/Protocol Specifications/core.md @@ -28,7 +28,7 @@ of the specification document: **v0.1.0-alpha.1** - [6. Cryptography and ID-Certs](#6-cryptography-and-id-certs) - [6.1 Home server signed certificates for public client identity keys (ID-Cert)](#61-home-server-signed-certificates-for-public-client-identity-keys-id-cert) - [6.1.1 Structure of an ID-Cert](#611-structure-of-an-id-cert) - - [6.1.1.1 Identity Descriptors (IDDs)](#6111-identity-descriptors-idds) + - [6.1.1.1 polyproto Distinguished Name (`pDN`)](#6111-polyproto-distinguished-name-pdn) - [6.1.1.2 Extensions and constraints](#6112-extensions-and-constraints) - [6.1.1.3 Session IDs](#6113-session-ids) - [6.1.2 Necessity of ID-Certs](#612-necessity-of-id-certs) @@ -385,11 +385,19 @@ excluding the new session. The `NEW_SESSION` event's stored data can be accessed ## 5. Federation IDs (FIDs) Every client requires an associated actor identity. Actors are distinguished by a unique federation -ID (FID). FIDs consist of their identifier, which is unique per instance, and the instance's root domain. +ID (FID). FIDs consist of a local name, which is unique per instance, and the instance's root domain. This combination ensures global uniqueness. FIDs used in public contexts are formatted as `actor@optionalsubdomain.domain.tld`, and are case-insensitive. +FIDs consist of the following parts: + +| Part | Name | Description | +| ------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `actor` | "Local Name" or "Common Name" | Must be unique on each instance. | +| `@` | "Separator" | Separates local name from domain name | +| `optionalsubdomain.domain.tld` | "Domain Name" | Includes top-level domain, second-level domain and other subdomains. Address which the actors' home server can be reached at. | + The following regular expression can be used to validate actor IDs: `\b([a-z0-9._%+-]+)@([a-z0-9-]+(\.[a-z0-9-]+)*)`. !!! info @@ -429,8 +437,8 @@ client. An ID-CSR includes the following information, according to the X.509 standard: - The public identity key of the client. -- An identity descriptor (IDD), describing the actor the certificate is issued to. The IDD must be - formatted according to [Section 6.1.1.1](#6111-identity-descriptors-idds). +- A polyproto Distinguished Name (`pDN`), describing the actor the certificate is issued to. The `pDN` + must be formatted according to [Section 6.1.1.1](#6111-polyproto-distinguished-name-pdn). - The signature algorithm used to sign the certificate. - The signature of the certificate, generated by using the entities' private identity key. @@ -457,47 +465,48 @@ ID-Certs encompass a subset of the structure of an X.509 certificate. ID-Certs have the following structure: -| Field Description | Special requirements, if any | X.509 equivalent | -| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| Correctly formatted Name attribute, according to [#6.1.1.1](#6111-identity-descriptors-idds) | [Identity descriptor](#6111-identity-descriptors-idds) | Issuer Name | -| A unique identifier for the certificate, used by the CA to identify this certificate. | Must be unique across all certificates issued by a home server. | Serial Number | -| The algorithm used to sign the certificate. | | Certificate Signature Algorithm & Signature Algorithm ID | -| The signature of the certificate, generated by using the home servers' private identity key. | | Certificate Signature | -| The expiry date of the certificate. | Time must not be after expiry date of the home server's root certificate | Validity period: Not After | -| Certificate validity period starting date | Time must not be before the home server's root certificate was generated | Validity period: Not Before | -| X.509 Version Number (v3) | polyproto only uses Version 3 X.509 certificates. | Version Number | -| The public identity key of the client. | | Subject Public Key Info: Subject Public Key | -| The public key algorithm used to generate the client's public identity key. | | Subject Public Key Info: Public Key Algorithm | -| The session ID of the client. | No two valid certificates for one session ID can exist. Session IDs have to be unique per user. | Subject Unique Identifier | -| Extensions | [Extensions and Constraints](#6112-extensions-and-constraints) | Extensions | - -##### 6.1.1.1 Identity Descriptors (IDDs) - -polyproto Identity Descriptors are a subset of the X.509 certificate's distinguished name. [Distinguished -Names (`DNs`)](https://ldap.com/ldap-dns-and-rdns/), according to the LDAP Data Interchange Format (LDIF). +| Field Description | Special requirements, if any | X.509 equivalent | +| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| Correctly formatted Name attribute, according to [#6.1.1.1](#6111-polyproto-distinguished-name-pdn) | [polyproto Distinguished Name](#6111-polyproto-distinguished-name-pdn) | Issuer Name | +| A unique identifier for the certificate, used by the CA to identify this certificate. | Must be unique across all certificates issued by a home server. | Serial Number | +| The algorithm used to sign the certificate. | | Certificate Signature Algorithm & Signature Algorithm ID | +| The signature of the certificate, generated by using the home servers' private identity key. | | Certificate Signature | +| The expiry date of the certificate. | Time must not be after expiry date of the home server's root certificate | Validity period: Not After | +| Certificate validity period starting date | Time must not be before the home server's root certificate was generated | Validity period: Not Before | +| X.509 Version Number (v3) | polyproto only uses Version 3 X.509 certificates. | Version Number | +| The public identity key of the client. | | Subject Public Key Info: Subject Public Key | +| The public key algorithm used to generate the client's public identity key. | | Subject Public Key Info: Public Key Algorithm | +| The session ID of the client. | No two valid certificates for one session ID can exist. Session IDs have to be unique per user. | Subject Unique Identifier | +| Extensions | [Extensions and Constraints](#6112-extensions-and-constraints) | Extensions | + +##### 6.1.1.1 polyproto Distinguished Name (`pDN`) + +polyproto Distinguished Names (`pDNs`) are a subset of an X.509 certificate's [distinguished +Names (`DNs`)](https://ldap.com/ldap-dns-and-rdns/), defined by the LDAP Data Interchange Format (LDIF). The `DN` is a sequence of [relative distinguished names (`RDNs`)](https://ldap.com/ldap-dns-and-rdns/). -The identity descriptor must be unique for each certificate issued by a home server. The `DN` of an ID-Cert -must meet all of the following requirements: - -- Identity descriptor (IDD) must have "common name" attribute. If the ID-Cert is for an actor, the - common name must be the local name of the actor. In the case of an actor with an FID of - `xenia@example.com`, the "common name" would be `xenia`. If the ID-Cert is a self-signed home server - certificate, the "common name" attribute must not be present. -- Must have at least one domain component, specifying the home servers' FQDN - (fully qualified domain name). -- If the ID-Cert or ID-CSR is for an actor, the IDD must include the `UID` (OID 0.9.2342.19200300.100.1.1) - **and** `uniqueIdentifier` (OID 0.9.2342.19200300.100.1.44) fields. - - `UID` is the federation ID of the actor, e.g. `actor@fqdn-of-home server.example.com`. - - `uniqueIdentifier` is a Session ID. +The identity descriptor must be unique for each certificate issued by a home server. A `pDN` +must meet all the following requirements: + +- If the `pDN` describes an actor, it must have a "common name" attribute. The + common name must be the [local name](#5-federation-ids-fids) of the actor. In the case of an actor + with an FID of `xenia@example.com`, the local name would be `xenia`. If the `pDN` describes a + home server, the "common name" attribute must not be present. +- Must have at least one domain component `dc`, specifying the domain name under which the home + server can be reached. This includes the home servers' top- and second-level domain, as well as + all other subdomains, if present. If the home server does not have a sub- or top-level domain, the + `dc` fields for these components should be omitted. +- If the `pDN` describes an actor, the `pDN` must include the `UID` + ([OID](https://en.wikipedia.org/wiki/Object_identifier) 0.9.2342.19200300.100.1.1) **and** + `uniqueIdentifier` ([OID](https://en.wikipedia.org/wiki/Object_identifier) 0.9.2342.19200300.100.1.44) + fields. + - `UID` field must be equal to the federation ID of the actor, e.g. `actor@domainname-of-home server.example.com`. + - `uniqueIdentifier` field must be a [Session ID](#6113-session-ids). - Can have other attributes, if the additional attributes do not conflict with the above requirements. Additional attributes might be ignored by other home servers and other clients, unless - specified otherwise in a polyproto extension. Additional attributes, which are not part of a polyproto + specified otherwise in a polyproto extension. Additional attributes not part of a polyproto extension must be non-critical X.509 extensions. -If the home server does not have a subdomain or top level domain, the `dc` fields for these -components should be omitted. - ##### 6.1.1.2 Extensions and constraints The following constraints must be met by ID-Certs: @@ -1406,7 +1415,7 @@ archive (.tar.gz) named `export1234567890-user@subdomain.example.com`, where - `export[numbers]` is the word `export` with 20 random digits appended to it - `user` is the actors' name -- `subdomain.example.com` is the FQDN of the server the actor is registered on. +- `subdomain.example.com` is the domain name of the server the actor is registered on. This file archive contains a file `messages.p2mb` which is a JSON file containing [message batches](#721-message-batches) of all messages sent by the user. If the server where the data export was requested from has