Add description for password protection of RelationshipTemplates and Tokens

_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.<br>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.                                                                                        |

_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": "<address that the RelationshipTemplate is intended for>"
+  "forIdentity": "<address of Identity designated for RelationshipTemplate>"
 }
 ```
 
 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": "<password of RelationshipTemplate>",
+    "passwordIsPin": <can be set to true if the password is a pin>
+  }
+}
+```
+
+To specialize 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.

_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.

_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`.

_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`.

_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`.