Zot6

Encryption

Standorte geben in ihrem Site-Discovery-Dokument ein Array an, das 0 oder mehr Verschlüsselungsalgorithmen enthält, die sie in der Reihenfolge ihrer Präferenz akzeptieren. Standorte, die verschlüsselte Dokumente versenden, MÜSSEN diese Liste verwenden, um den für beide Seiten am besten geeigneten Algorithmus zu ermitteln. Kann kein geeigneter Algorithmus ausgehandelt werden, DARF die Website auf Klartext (unverschlüsselte Daten) zurückgreifen; ist der Kommunikationskanal jedoch nicht mit SSL gesichert, DARF die sendende Website KEINEN Klartext verwenden, und eine empfangende Website DARF die Kommunikation ignorieren oder ablehnen, wenn sie private oder sensible Informationen enthält.

Unterstützt die empfangende Website den bereitgestellten Algorithmus nicht, MUSS sie den Fehler 400 zurückgeben.

Verschlüsselte Informationen werden in ein JSON-Array/Objekt mit den folgenden Komponenten gekapselt:

'encrypted' => true
'key'       => The encryption key, base64urlencoded
'iv'        => The encryption initialisation vector, base64urlencoded
'alg'       => The encryption algorithm used
'data'      => The encrypted payload, base64urlencoded

Das boolesche Flag „encrypted“ gibt an, dass es sich um eine kryptografische Struktur handelt, die entschlüsselt werden muss, um die Informationen zu extrahieren. „alg“ ist erforderlich. Andere Elemente können bei Bedarf angepasst werden, um verschiedene Mechanismen/Algorithmen zu unterstützen. Beispielsweise benötigen manche Mechanismen möglicherweise ein „hmac“-Feld. Die aufgeführten Elemente unterstützen eine Vielzahl von Standard-Verschlüsselungsalgorithmen.

Der Schlüssel und der IV sind pseudozufällige Byte-Sequenzen, die vor der Base64-URL-Kodierung mit dem öffentlichen RSA-Schlüssel des Empfängers verschlüsselt werden. Der in den meisten Fällen (standardmäßig) verwendete Empfängerschlüssel ist der öffentliche Schlüssel der Remote-Site. Unter bestimmten Umständen (sofern angegeben) ist der öffentliche RSA-Schlüssel der des Zielkanals oder des Empfängers.

Sowohl „key“ als auch „iv“ KÖNNEN auf 255 Zeichen aufgefüllt werden. Der Umfang der erforderlichen Auffüllung hängt vom Verschlüsselungsalgorithmus ab. Die empfangende Seite MUSS zusätzliche Auffüllung bei beiden Parametern entfernen, um die vom gewählten Algorithmus unterstützte maximale Länge einzuhalten. Der Algorithmus „aes256cbc“ (nicht empfohlen) verwendet beispielsweise eine Schlüssellänge von 32 Byte und einen IV von 16 Byte.

Die Bezeichnungen für gängige Algorithmen entsprechen den von der OpenSSL-Bibliothek verwendeten Algorithmusnamen in Kleinbuchstaben ohne Satzzeichen. Der OpenSSL-Algorithmus „aes-256-ctr“ wird beispielsweise als „aes256ctr“ bezeichnet.

Ungewöhnliche Algorithmen, die von OpenSSL nicht unterstützt werden, dürfen verwendet werden, doch die genauen Algorithmusnamen sind in diesem Dokument nicht definiert.

Signatures

Die Herkunftsnachweis der Identität erfolgt mithilfe von HTTP-Signaturen (derzeit gilt die Spezifikation „draft-cavage-http-signatures-10“ als maßgeblich). Bei Verwendung eines verschlüsselten Transports KANN die HTTP-Signatur mit demselben ausgehandelten Algorithmus verschlüsselt werden, der auch in der Nachricht zum Schutz des Umschlags verwendet wird. Siehe HTTP-Signaturen. Wenn eine Website die im vorangegangenen Abschnitt beschriebene ausgehandelte Verschlüsselung verwendet, MUSS sie in der Lage sein, die HTTP-Signaturen zu entschlüsseln.

An mehreren Stellen in den Kommunikationsprotokollen, an denen die Verifizierung mit einem Dritten erfolgt, der nicht der Absender des betreffenden HTTP-Pakets ist, werden signierte Daten/Objekte festgelegt bzw. vorgeschrieben. Je nachdem, ob es sich bei den signierten Daten um einen Einzelwert oder ein JSON-Objekt handelt, können zwei Signaturverfahren zum Einsatz kommen. Das für Einzelwerte verwendete Verfahren wird hier als „SimpleSignatures“ bezeichnet. Das für Objekte verwendete Signaturverfahren ist traditionell als „Salmon Magic Signatures“ bekannt und nutzt die JSON-Serialisierung.

Simple Signatures

Ein Datenwert wird mit einer geeigneten RSA-Methode und einem Hash-Algorithmus signiert; beispielsweise „sha256“, was eine Signatur mit einem RSA-Schlüsselpaar unter Verwendung des dafür vorgesehenen privaten RSA-Schlüssels und des Hash-Algorithmus „sha256“ bezeichnet. Das Ergebnis wird Base64URL-kodiert, mit dem Algorithmusnamen und einem Punkt (0x2e) vorangestellt und, sofern angegeben, als zusätzliches Datenelement gesendet.

"foo_sig": "sha256.EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe..."

Zur Überprüfung wird der Inhalt des Elements am ersten Punkt getrennt, um den Algorithmus und die Signatur zu extrahieren. Die Signatur wird mit „base64urldecode“ dekodiert und unter Verwendung der entsprechenden Methode und des entsprechenden Hash-Algorithmus sowie des dafür vorgesehenen öffentlichen RSA-Schlüssels (im Falle von RSA-Signaturen) überprüft. Der zu verwendende Schlüssel ist an anderer Stelle im Zot-Protokoll in Abhängigkeit vom Kontext der Signatur definiert.

Implementierungen MÜSSEN RSA-SHA256-Signaturen unterstützen. Sie KÖNNEN zusätzliche Signaturmethoden unterstützen.

Salmon “magic envelope” Signatures mit JSON-Serialisierung.

{
  "signed": true,
  "data": "PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGl...",
  "data_type": "application/x-zot+json",
  "encoding": "base64url",
  "alg": "RSA-SHA256",
  "sigs": [
    {
    "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe...",
    "key_id": "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI"
    }
  ]
}

Das boolesche Element „signed“ ist in der Spezifikation des Magic Envelope nicht definiert. Es handelt sich hierbei um ein boolesches Flag, das angibt, dass es sich bei dem aktuellen Element um ein vorzeichenbehaftetes Objekt handelt, das einer Überprüfung und Entpackung bedarf, um den tatsächlichen Inhalt des Elements abzurufen.

Die signierten Daten werden durch Entpacken der „data“-Komponente der Magic-Signatur abgerufen. Das Entpacken erfolgt durch Entfernen aller Leerzeichen (0x0d, 0x0a, 0x20 und 0x09) und anschließende Base64-„URL“-Dekodierung.

Die „key_id“ ist die Base64-URL-kodierte Kennung des Unterzeichners, die im Rahmen des Zot-„Discovery“-Prozesses zur Ermittlung des öffentlichen Schlüssels führt. Dabei handelt es sich in der Regel um die Basis-URL des Servers oder die „Home“-URL des Kanals. Webfinger-Kennungen (acct:user@domain) KÖNNEN ebenfalls verwendet werden, wenn das resultierende Webfinger-Dokument einen auffindbaren öffentlichen Schlüssel (Salmon-Public-Key oder WebID-Schlüssel) enthält.

Die Überprüfung erfolgt mithilfe der „Magic Envelope“-Verifizierungsmethode. Entfernen Sie zunächst alle Leerzeichen aus dem Wert „data“. Fügen Sie die folgenden Felder durch einen Punkt (0x2e) getrennt aneinander.

data . data_type . encoding . algorithm

Dies sind die „signierten Daten“. Die Überprüfung erfolgt mithilfe der RSA-Verifizierungsfunktion unter Verwendung der signierten Daten, des Base64-URL-dekodierten Werts „sigs.value“, des in „alg“ angegebenen Algorithmus und des öffentlichen Schlüssels, der durch Ausführen der Zot-Erkennung für die Base64-URL-dekodierte „sigs.key_id“ ermittelt wurde.

Bei der Durchführung einer Zot-Abfrage nach Schlüsseln ist es wichtig, zu überprüfen, ob der in der Abfrageantwort zurückgegebene Principal mit dem Principal in der „key_id“ übereinstimmt und ob die Abfrageantwort ebenfalls signiert und validiert ist.

Einige historische Varianten von „Magic Signatures“ geben eine Base64-URL-Kodierung mit oder ohne Auffüllung aus.

In dieser Spezifikation MUSS die Kodierung die Zeichenkette „base64url“ lauten, was die URL-sichere Base64-Kodierung gemäß RFC 4648 bezeichnet, ohne abschließende Auffüllung mit Gleichheitszeichen (=).

Die entpackten Daten (nach der Überprüfung) können einen einzelnen Wert oder ein zusammengesetztes Objekt enthalten. Enthalten sie einen einzelnen Wert, wird dieser zum Wert des übergeordneten Elements. Andernfalls werden sie wieder als zusammengesetztes Objekt zusammengeführt.

Beispiel: Quelldokument

{ 
    "guid": {
      "signed": true,
      "data": "PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGl...",
      "data_type": "application/x-zot+json",
      "encoding": "base64url",
      "alg": "RSA-SHA256",
      "sigs": [
        {
        "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe...",
        "key_id": "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI"
        }
      ]
    },
    "address": "foo@bar"
}

Die Dekodierung des Datenparameters (unter der Annahme einer erfolgreichen Signaturprüfung) ergibt

"abc12345"

Durch das Zusammenführen mit dem Originaldokument entsteht

{
    "guid": "abc12345",
    "address": "foo@bar"
}

Beispiel mit einem signierten Objekt, das mehrere Elemente enthält: Die Dekodierung des Datenparameters (unter der Annahme einer erfolgreichen Signaturprüfung) ergibt

{
    "guid": "abc12345",
    "name": "Barbara Jenkins"
}

Wenn man dies mit dem Originaldokument zusammenführt, ergibt sich

{
    "guid": {
        "guid": "abc12345",
        "name": "Barbara Jenkins"
    },
    "address": "foo@bar"
}