From c26fb8e83b6d62ecf9ab0c63b78d7d5c603de566 Mon Sep 17 00:00:00 2001 From: Frederic Reisenhauer Date: Thu, 24 Oct 2024 17:13:38 +0200 Subject: [PATCH 1/2] document meta property in secret rotated lifecycle webhooks for extension --- docs/contribution/5-reference/4-webhooks.mdx | 54 +++++++++++------ .../contribution/5-reference/4-webhooks.mdx | 60 +++++++++++++------ 2 files changed, 77 insertions(+), 37 deletions(-) diff --git a/docs/contribution/5-reference/4-webhooks.mdx b/docs/contribution/5-reference/4-webhooks.mdx index 26e7e7d5..e43c9844 100644 --- a/docs/contribution/5-reference/4-webhooks.mdx +++ b/docs/contribution/5-reference/4-webhooks.mdx @@ -91,10 +91,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -212,10 +209,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -271,7 +265,15 @@ You may use the following placeholders: format="yaml" schema={{ type: "object", - required: ["apiVersion", "context", "kind", "id", "secret", "request"], + required: [ + "apiVersion", + "context", + "kind", + "id", + "meta", + "secret", + "request", + ], properties: { apiVersion: { type: "string", @@ -300,6 +302,22 @@ You may use the following placeholders: }, }, }, + meta: { + type: "object", + required: ["extensionId", "contributorId"], + properties: { + extensionId: { + type: "string", + format: "uuid", + example: "c593348d-f594-492a-8185-2b89848a4160", + }, + contributorId: { + type: "string", + format: "uuid", + example: "680ba069-7465-4932-8b23-e73914b2e051", + }, + }, + }, secret: { type: "string", example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr", @@ -404,10 +422,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -515,9 +530,12 @@ In that case, domain actions of that extension instance are not accepted. ### meta -Meta information about the extension instance. -Currently, the mStudio only sends the creation date of the extension instance. -This should not be confused with the request meta information which describes the webhook call. +Meta information about the extension (instance). +This includes the extensionID and the contributorID. + +These information should be used to ensure that the webhook not only originates from mittwald, but is also intended for the own extension. +This prevents forward replay attacks. +This should not be confused with the request meta information which describes the webhook call itself. ### secret @@ -659,8 +677,8 @@ If the values are not set, the mStudio derives them from the extension or genera }, secret: { type: "string", - example: "<>" - } + example: "<>", + }, }, }} /> diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx index 9be53653..75bb1e04 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx @@ -91,10 +91,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -212,10 +209,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -271,7 +265,15 @@ Folgende Platzhalter können verwendet werden: format="yaml" schema={{ type: "object", - required: ["apiVersion", "context", "kind", "id", "secret", "request"], + required: [ + "apiVersion", + "context", + "kind", + "id", + "meta", + "secret", + "request", + ], properties: { apiVersion: { type: "string", @@ -300,6 +302,22 @@ Folgende Platzhalter können verwendet werden: }, }, }, + meta: { + type: "object", + required: ["extensionId", "contributorId"], + properties: { + extensionId: { + type: "string", + format: "uuid", + example: "c593348d-f594-492a-8185-2b89848a4160", + }, + contributorId: { + type: "string", + format: "uuid", + example: "680ba069-7465-4932-8b23-e73914b2e051", + }, + }, + }, secret: { type: "string", example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr", @@ -404,10 +422,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -516,7 +531,12 @@ Somit würden auch Domain Actions für eine deaktivierte Extension Instance nich ### meta -Meta-Informationen über die Extension Instance. Derzeit wird lediglich der Erstellungszeitpunkt der Extension Instance übermittelt. +Meta-Informationen über die Extension (Instance). +Diese beinhalten die IDs der Extension und des Contributors. + +Diese Informationen sollten bspw. verwendet werden, um sicherzustellen, dass der Webhook nicht nur ursprünglich von mittwald stammt, +sondern auch für die eigene Extension bestimmt ist. +Dies beugt Forward-Replay-Attacken vor. Dies ist nicht zu verwechseln mit den Request Meta Informationen, die Aufschluss über den Webhook an sich geben. ### secret @@ -574,9 +594,10 @@ if err != nil { } if !ed25519.Verify(publicKey, bodyBytes, signature) { - panic("invalid signature") +panic("invalid signature") } -``` + +```` ```php @@ -593,7 +614,8 @@ $valid = sodium_crypto_sign_verify_detached( if (!$valid) { throw new \Exception('invalid request signature'); } -``` +```` + @@ -649,8 +671,8 @@ Sind diese Werte nicht gesetzt, werden sie aus der Extension abgeleitet oder zuf }, secret: { type: "string", - example: "<>" - } + example: "<>", + }, }, }} /> From 46f484716b10bb19755c62fc3a9773e21150dac8 Mon Sep 17 00:00:00 2001 From: freisenhauer Date: Fri, 25 Oct 2024 09:07:34 +0200 Subject: [PATCH 2/2] Update i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx Co-authored-by: tdellmann Signed-off-by: freisenhauer --- .../current/contribution/5-reference/4-webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx index 75bb1e04..31ab7b0a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx @@ -594,7 +594,7 @@ if err != nil { } if !ed25519.Verify(publicKey, bodyBytes, signature) { -panic("invalid signature") + panic("invalid signature") } ````