diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 1b69d5356..59337e007 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -51,17 +51,30 @@ Tokens can be used to save arbitrary structured data on the Backbone, which is e A Token has the following properties: -| Name | Type | Description | Remarks | -| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | -| createdBy | `string` | {% include descr_createdBy class="Token" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | -| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | -| createdAt | `string` | {% include descr_createdAt class="Token" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | -| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | -| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | -| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | +| Name | Type | Description | Remarks | +| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | +| createdBy | `string` | {% include descr_createdBy class="Token" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | +| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | +| createdAt | `string` | {% include descr_createdAt class="Token" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | +| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | +| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | | +| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | +| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | + +### PasswordProtection + +A [Token](#token) or [RelationshipTemplate can be protected by a password]({% link _docs_integrate/establish-relationships.md %}#password-protection-of-a-relationshiptemplate) to ensure that it is protected from unauthorized access. +In order for a peer to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to the creator of a password protected [RelationshipTemplate](#relationshiptemplate), it must enter the correct password when [loading the RelationshipTemplate]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}). +Similarly, in order for an Identity to [load a Token]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) that is password protected, it must enter the correct password. +Information about the password protection of a Token or a RelationshipTemplate is recorded within its optional `passwordProtection` property. + +| Name | Type | Description | Remarks | +| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| password | `string` | The password of the Token or the RelationshipTemplate. | | +| passwordIsPin | `true` \| `undefined` | If the password consists of 4 to 16 digits, the value of the `passwordIsPin` property can be set to `true`. In this case, the password is interpreted as a pin and a corresponding input field is displayed in the UI of the App when the pin needs to be entered. However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether the password could also be interpreted as a pin. | | ## RelationshipTemplate @@ -80,7 +93,8 @@ A RelationshipTemplate serves two purposes: | content | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| [`ArbitraryRelationshipTemplateContent`](#arbitraryrelationshiptemplatecontent) | The content of the RelationshipTemplate. If it is intended for a User of the enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise, an `ArbitraryRelationshipTemplateContent` can also be used, which can be filled with anything and serves as a fallback if the `RelationshipTemplateContent` is not sufficient. | | | expiresAt | `string` | {% include descr_expiresAt class="RelationshipTemplate" %} | will be encrypted before sent to the Backbone | | maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | | -| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | | +| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | | +| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the RelationshipTemplate is protected by a password or pin. | | | truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally | ## Relationship diff --git a/_docs_integrate/error-codes.md b/_docs_integrate/error-codes.md index db7000f7e..e7718cbb2 100644 --- a/_docs_integrate/error-codes.md +++ b/_docs_integrate/error-codes.md @@ -131,6 +131,8 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.runtime.relationshipTemplates.cannotCreateTokenForPeerTemplate" %} | You cannot [create a Token for a RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md %}) of a peer. | | {% include anchor a="error.runtime.relationshipTemplates.cannotCreateQRCodeForPeerTemplate" %} | You cannot [create a QR code for a RelationshipTemplate]({% link _docs_use-cases/use-case-transport-get-relationshiptemplate.md %}) of a peer. | | {% include anchor a="error.runtime.relationshipTemplates.invalidReference" %} | The given `truncatedReference` is not valid. The `truncatedReference` for a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) must start with 'UkxU'. | +| {% include anchor a="error.runtime.relationshipTemplates.personalizationMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is personalized, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same personalization. | +| {% include anchor a="error.runtime.relationshipTemplates.passwordProtectionMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has password protection, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same password protection. | | {% include anchor a="error.runtime.requestDeserialization" %} | There was an error during the request deserialization. | | {% include anchor a="error.runtime.servalError" %} | A serialization / validation error occurred. | | {% include anchor a="error.runtime.startup.noActiveAccount" %} | No AccountController could be found. You might have to login first. | @@ -159,6 +161,7 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.transport.messages.plaintextMismatch" %} | The own `address` was not named as a `recipient` within the signed MessagePlaintext. For example this can be caused by a replay attack. | | {% include anchor a="error.transport.messages.signatureListMismatch" %} | The `signature` list didn't contain an entry for a given `address`. | | {% include anchor a="error.transport.messages.signatureNotValid" %} | The digital signature on a [Message]({% link _docs_integrate/data-model-overview.md %}#message) for a peer `key` is invalid. An impersonation attack might be the cause of this. | +| {% include anchor a="error.transport.noPasswordProvided" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) has password protection, a password must be provided to load it. | | {% include anchor a="error.transport.notSupported" %} | The requested method is not yet supported. | | {% include anchor a="error.transport.recordNotFound" %} | The requested record was not found. | | {% include anchor a="error.transport.relationships.
activeIdentityDeletionProcessOfOwnerOfRelationshipTemplate" %} | The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is currently in the process of deleting itself. Thus, it is not possible to establish a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to it. | diff --git a/_docs_integrate/establish-relationships.md b/_docs_integrate/establish-relationships.md index e9f8dd5d9..73f9d4179 100644 --- a/_docs_integrate/establish-relationships.md +++ b/_docs_integrate/establish-relationships.md @@ -75,22 +75,49 @@ How to send a Request via a RelationshipTemplate is explained in detail in the [ If the RelationshipTemplate is intended to establish a Relationship between the templator and another Connector, an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) can be used instead of a RelationshipTemplateContent as the value of the [RelationshipTemplate's]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) `content`. An ArbitraryRelationshipTemplateContent has a single `value` property with no type restriction and is appropriate if the standard way is insufficient. -### Personalize the RelationshipTemplate +#### Personalization of a RelationshipTemplate -If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), you can set that Identity's `address` in the RelationshipTemplate: +The optional property `forIdentity` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) can be added to the [input for creating a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#input-for-creating-a-relationshiptemplate) in order to personalize it. +If the RelationshipTemplate is only for creating a Relationship with a single known [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), you can set that Identity's `address` in the RelationshipTemplate: ```jsonc { // ... "content": { - // ... + // RelationshipTemplateContent or ArbitraryRelationshipTemplateContent + ... }, - "forIdentity": "
" + "forIdentity": "
" } ``` Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access. +#### Password Protection of a RelationshipTemplate + +The optional property `passwordProtection` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) can be added to the [input for creating a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#input-for-creating-a-relationshiptemplate) to provide password protection. +This allows the RelationshipTemplate to be protected from unauthorized access. +Only the Identities that know the password of the RelationshipTemplate will be able to continue with establishing a Relationship. +If the RelationshipTemplate is to be protected by a password, the corresponding password must be specified within its `passwordProtection.password` property. + +```jsonc +{ + // ... + "content": { + // RelationshipTemplateContent or ArbitraryRelationshipTemplateContent + ... + }, + "passwordProtection": { + "password": "", + "passwordIsPin": + } +} +``` + +To configure the input field for password entry in the UI of the App, the value of the optional field `passwordProtection.passwordIsPin` can be set to `true` if the password consists of 4 to 16 digits. +In this case, the password is interpreted as a pin and a corresponding input field is displayed when the pin needs to be entered. +However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether it could also be interpreted as a pin. + ### Successfully Created RelationshipTemplate If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context. 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..d6c9530d0 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. +- 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 for another [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-device-onboarding-token.md b/_docs_use-cases/use-case-transport-create-device-onboarding-token.md index 6edbe8251..0ea824687 100644 --- a/_docs_use-cases/use-case-transport-create-device-onboarding-token.md +++ b/_docs_use-cases/use-case-transport-create-device-onboarding-token.md @@ -41,13 +41,13 @@ required_by: {% include properties_list.html %} -This use case retrieves the [Token]({% link _docs_integrate/data-model-overview.md %}#token) -of a so far not-onboarded Device that corresponds to the given Device `id` in order to onboard the Device to the Identity. +This use case retrieves the [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a not yet onboarded Device that corresponds to the given Device `id` in order to onboard the Device to the Identity. ## Parameters - `id` of the Device. - `expiresAt` is the ISODateTime the Token expires at. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure the UI of the App in case the password is a pin. ## On Success @@ -56,3 +56,4 @@ of a so far not-onboarded Device that corresponds to the given Device `id` in or ## On Failure - The Device was already onboarded. +- 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-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md index c9efd4481..17922d955 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. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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..0a5c47ce6 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. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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..1ec6681ce 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 [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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..dbe3ecfc0 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. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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 does not have the same personalization via its `forIdentity` property. +- The RelationshipTemplate is password protected via its `passwordProtection` property and the Token does not have 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..d7c9c55f5 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 [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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..96875bb84 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. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a 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 configure 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 does not have the same personalization via its `forIdentity` property. +- The RelationshipTemplate is password protected via its `passwordProtection` property and the Token does not have 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..b660d8836 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. +- The `password` if the File is to be loaded from a `reference` to a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that is password protected via its `passwordProtection` property. ## On Success @@ -55,3 +56,5 @@ 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. +- The File is to be loaded from a `reference` to a Token that is personalized for a different [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via its `forIdentity` property. +- 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..573c9472f 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). @@ -65,4 +67,5 @@ There are two different options to use this use case, depending on the actual in - The RelationshipTemplate does not exist. - 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. +- The RelationshipTemplate is personalized for 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..50d70fca1 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 @@ -46,10 +46,11 @@ This use case intends to load a peer's [Token]({% link _docs_integrate/data-mode ## Parameters -You can execute this use case if you know the `truncatedReference` of the peer's Token +You can execute this use case if you know the `truncatedReference` of the peer's Token. - `reference` that identifies the Token. - `ephemeral` to indicate that the Token should be stored locally. +- The `password` if the Token is protected by a password via its `passwordProtection` property. ## On Success @@ -60,4 +61,5 @@ You can execute this use case if you know the `truncatedReference` of the peer's - The parameters are malformed. - 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. +- The Token is personalized for 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. diff --git a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md index 4f188b0cc..0832ff445 100644 --- a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md +++ b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md @@ -44,8 +44,7 @@ api_route_regex: ^GET /api/v2/RelationshipTemplates$ {% include properties_list.html %} -This use case queries [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) -of the Identity. +This use case queries [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) of the Identity. ## Parameters @@ -56,7 +55,9 @@ All parameters are optional. If no parameter is given, all RelationshipTemplates - `expiresAt` is the ISODateTime the RelationshipTemplate expires. - `createdBy` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that created the RelationshipTemplate. - `createdByDevice` is the `id` of the Device that created the RelationshipTemplate. -- `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. +- `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` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which the RelationshipTemplate is intended. +- `passwordProtection` is an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a RelationshipTemplate. ## On Success diff --git a/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md b/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md index 0e6f77d56..0aba7fd5a 100644 --- a/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md +++ b/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md @@ -49,6 +49,8 @@ This use case queries [Tokens]({% link _docs_integrate/data-model-overview.md %} - `createdBy` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that created the Token. - `createdByDevice` is the `id` of the Device that created the Token. - `expiresAt` is the ISODateTime the Token expires. +- `forIdentity` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which the Token is intended. +- `passwordProtection` is an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. ## On Success