From 5a82f2526ad063ef5fd8d61bfbc394aa4faad50b Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Tue, 17 Dec 2024 17:22:58 +0000 Subject: [PATCH] feat: add passwordProtection and password parameters to use cases --- ...ken-by-truncated-reference-without-having-an-account.md | 3 +++ .../use-case-transport-create-own-relationshiptemplate.md | 2 ++ _docs_use-cases/use-case-transport-create-own-token.md | 2 ++ .../use-case-transport-create-token-for-file.md | 2 ++ ...-transport-create-token-for-own-relationshiptemplate.md | 7 ++++++- .../use-case-transport-create-token-qr-code-for-file.md | 2 ++ ...rt-create-token-qr-code-for-own-relationshiptemplate.md | 7 ++++++- _docs_use-cases/use-case-transport-get-or-load-file.md | 4 +++- ...ransport-load-relationshiptemplate-created-by-others.md | 5 ++++- .../use-case-transport-load-token-created-by-others.md | 2 ++ 10 files changed, 32 insertions(+), 4 deletions(-) diff --git a/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md b/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md index 568d7b69f..91dbc4e61 100644 --- a/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md +++ b/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md @@ -49,6 +49,7 @@ This can be used to fetch `Tokens` for Device Onboarding or Recovery. ## Parameters - The `reference` that contains all information to load a Token. +- `password` to enter the password if the Token is protected by a password via its `passwordProtection` property. ## On Success @@ -57,3 +58,5 @@ This can be used to fetch `Tokens` for Device Onboarding or Recovery. ## On Failure - There is no `Token` that matches the `reference`. +- The Token is personalized to an [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the property `forIdentity` of the Token. +- No `password` or an incorrect `password` was entered in case of a password protected Token. diff --git a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md index c9efd4481..ff1c0b2a6 100644 --- a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md @@ -52,6 +52,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat - `content` describes the structure of the RelationshipTemplate. If an enmeshed App user shall receive this RelationshipTemplate, a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) is required as structure, otherwise an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) containing any data can be used. - `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error, if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it. - `forIdentity` can be set to an enmeshed address. If set, only the Identity with that `address` can access the RelationshipTemplate. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-relationshiptemplate). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the RelationshipTemplate can access it. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. ## On Success @@ -61,3 +62,4 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat - The `content` is malformed. - `expiresAt` lies in the past. +- In case of password protection of the RelationshipTemplate, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-own-token.md b/_docs_use-cases/use-case-transport-create-own-token.md index 1975da7f8..9056a54e1 100644 --- a/_docs_use-cases/use-case-transport-create-own-token.md +++ b/_docs_use-cases/use-case-transport-create-own-token.md @@ -50,6 +50,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. ## On Success @@ -59,3 +60,4 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that - The `content` is malformed. - `expiresAt` lies in the past. +- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-token-for-file.md b/_docs_use-cases/use-case-transport-create-token-for-file.md index 27a2a3d99..520316fea 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-for-file.md @@ -50,6 +50,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. - Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and don't need to be stored. - Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. ## On Success @@ -59,3 +60,4 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `fileId` does not resolve to a File. - `expiresAt` lies in the past. +- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md index 8093f1c9a..ff573369c 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md @@ -51,7 +51,8 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `templateId` is the `id` of the RelationshipTemplate the Token should be created for. - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. -- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. +- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. If the RelationshipTemplate is already personalized via its `forIdentity` property, the Token created from it must have the same personalization. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. ## On Success @@ -60,4 +61,8 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a ## On Failure - `templateId` does not resolve to a RelationshipTemplate. +- The RelationshipTemplate is owned by another Identity, which means that the value of its `isOwn` property is `false`. - `expiresAt` lies in the past. +- The RelationshipTemplate is personalized via its `forIdentity` property and the Token has not the same personalization via its `forIdentity` property. +- The RelationshipTemplate is password protected via its `passwordProtection` property and the Token has not the same password protection via its `passwordProtection` property. +- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md index 081fd3923..55e6eb4ee 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md @@ -49,6 +49,7 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `fileId` is the `id` of the File the Token and its QR code should be created for. - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. - Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. ## On Success @@ -58,3 +59,4 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `fileId` does not resolve to a File. - `expiresAt` lies in the past. +- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md index 253968394..0c67c7b0c 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md @@ -48,7 +48,8 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `templateId` is the `id` of the RelationshipTemplate the Token and its QR code should be created for. - `expiresAt` is the ISODateTime the Token expires at. -- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. +- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. If the RelationshipTemplate is already personalized via its `forIdentity` property, the Token created from it must have the same personalization. +- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to specialize the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. ## On Success @@ -57,4 +58,8 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % ## On Failure - `templateId` does not resolve to a RelationshipTemplate. +- The RelationshipTemplate is owned by another Identity, which means that the value of its `isOwn` property is `false`. - `expiresAt` lies in the past. +- The RelationshipTemplate is personalized via its `forIdentity` property and the Token has not the same personalization via its `forIdentity` property. +- The RelationshipTemplate is password protected via its `passwordProtection` property and the Token has not the same password protection via its `passwordProtection` property. +- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-get-or-load-file.md b/_docs_use-cases/use-case-transport-get-or-load-file.md index c0521ee8f..e4104b00c 100644 --- a/_docs_use-cases/use-case-transport-get-or-load-file.md +++ b/_docs_use-cases/use-case-transport-get-or-load-file.md @@ -44,9 +44,10 @@ api_route_regex: ^GET /api/v2/Files/{idOrReference}$ This use case retrieves a [File]({% link _docs_integrate/data-model-overview.md %}#file) by an `id` or the `reference`. This is usually the case, when a reference to a File was received by a peer (over a Message or by any side channel). -## Paramers +## Parameters - `id` or `reference` that identify the File. +- `password` to enter the password if the File is to be loaded from a `reference` to a via its `passwordProtection` property password protected [Token]({% link _docs_integrate/data-model-overview.md %}#token). ## On Success @@ -55,3 +56,4 @@ This use case retrieves a [File]({% link _docs_integrate/data-model-overview.md ## On Failure - The given `id` or `reference` does not resolve to a File. +- No `password` or an incorrect `password` was entered in case of a File that is to be loaded from a `reference` to a password protected Token. diff --git a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md index 5f660db40..c5eef48fc 100644 --- a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md @@ -52,9 +52,11 @@ There are two different options to use this use case, depending on the actual in - by knowing a `truncatedReference` of the peer's RelationshipTemplate (RelationshipTemplateReferenceTruncated) - `reference` as string -- by knowing a `truncatedReference` of the peer's Token, which references to the peer's RelationshipTemplate TokenReferenceTruncated +- by knowing a `truncatedReference` of the peer's [Token]({% link _docs_integrate/data-model-overview.md %}#token), which references to the peer's RelationshipTemplate (TokenReferenceTruncated) - `reference` as string +If the RelationshipTemplate or the Token, if there is one, is protected by a password via the `passwordProtection` property, it must be entered with the `password` parameter of this use case in order to be authorized to load the RelationshipTemplate. + ## On Success - Returns the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). @@ -66,3 +68,4 @@ There are two different options to use this use case, depending on the actual in - The RelationshipTemplate is expired. - The `maxNumberOfAllocations` of the RelationshipTemplate are depleted. - The RelationshipTemplate is personalized to a different [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the property `forIdentity` of the RelationshipTemplate. +- No `password` or an incorrect `password` was entered in case of a password protected RelationshipTemplate or a password protected Token, if there is one. diff --git a/_docs_use-cases/use-case-transport-load-token-created-by-others.md b/_docs_use-cases/use-case-transport-load-token-created-by-others.md index ae802aaab..e18c2e8b8 100644 --- a/_docs_use-cases/use-case-transport-load-token-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-token-created-by-others.md @@ -50,6 +50,7 @@ You can execute this use case if you know the `truncatedReference` of the peer's - `reference` that identifies the Token. - `ephemeral` to indicate that the Token should be stored locally. +- `password` to enter the password if the Token is protected by a password via its `passwordProtection` property. ## On Success @@ -61,3 +62,4 @@ You can execute this use case if you know the `truncatedReference` of the peer's - The Token does not exist. - The Token is expired. - The Token is personalized to a different [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the property `forIdentity` of the Token. +- No `password` or an incorrect `password` was entered in case of a password protected Token.