From d81ea3e634fd81c473a0ef258be5d6674934a7c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus-Peter=20H=C3=BCbner?= Date: Fri, 15 Jul 2022 02:31:38 +0200 Subject: [PATCH 1/3] update some chapters --- .../UC_Introduction_of_Gradido-ID.md | 286 +++++++++--------- 1 file changed, 146 insertions(+), 140 deletions(-) diff --git a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md index e3c0ac2d7..5da969eac 100644 --- a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md +++ b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md @@ -1,140 +1,146 @@ -# Introduction of Gradido-ID - -## Motivation - -To introduce the Gradido-ID base on the requirement to identify an user account per technical key instead of using an email-address. Such a technical key ensures an exact identification of an user account without giving detailed information for possible missusage. - -Additionally the Gradido-ID allows to administrade any user account data like changing the email address or define several email addresses without any side effects on the identification of the user account. - -## Definition - -The formalized definition of the Gradido-ID can be found in the document [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID). - -## Steps of Introduction - -To Introduce the Gradido-ID there are several steps necessary. The first step is to define a proper database schema with additional columns and tables followed by data migration steps to add or initialize the new columns and tables by keeping valid data at all. - -The second step is to decribe all concerning business logic processes, which have to be adapted by introducing the Gradido-ID. - -### Database-Schema - -#### Users-Table - -The entity users has to be changed by adding the following columns. - -| Column | Type | Description | -| ------------------------ | ------ | -------------------------------------------------------------------------------------- | -| gradidoID | String | technical unique key of the user as UUID (version 4) | -| alias | String | a business unique key of the user | -| passphraseEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | -| emailID | int | technical foreign key to the new entity Contact | - -##### Email vs emailID - -The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table. - -The preferred and proper solution will be to add a new column `Users.emailId `as foreign key to the `UsersContact `entry and delete the `Users.email` column after the migration of the email address in the `UsersContact `table. - -#### new UserContacts-Table - -A new entity `UserContacts `is introduced to store several contacts of different types like email, telephone or other kinds of contact addresses. - -| Column | Type | Description | -| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | int | the technical key of a contact entity | -| type | int | Defines the type of contact entry as enum: Email, Phone, etc | -| usersID | int | Defines the foreign key to the `Users` table | -| email | String | defines the address of a contact entry of type Email | -| phone | String | defines the address of a contact entry of type Phone | -| contactChannels | String | define the contact channel as comma separated list for which this entry is confirmed by the user e.g. main contact (default), infomail, contracting, advertisings, ... | - -### Database-Migration - -After the adaption of the database schema and to keep valid consistent data, there must be several steps of data migration to initialize the new and changed columns and tables. - -#### Initialize GradidoID - -In a one-time migration create for each entry of the `Users `tabel an unique UUID (version4). - -#### Primary Email Contact - -In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UsersContact `table, by initializing the contact-values with: - -* id = new technical key -* type = Enum-Email -* userID = `Users.id` -* email = `Users.email` -* phone = null -* usedChannel = Enum-"main contact" - -and update the `Users `entry with `Users.emailId = UsersContact.Id` and `Users.passphraseEncryptionType = 1` - -After this one-time migration the column `Users.email` can be deleted. - -### Adaption of BusinessLogic - -The following logic or business processes has to be adapted for introducing the Gradido-ID - -#### Read-Write Access of Users-Table especially Email - -The ORM mapping has to be adapted to the changed and new database schema. - -#### Registration Process - -The logic of the registration process has to be adapted by - -* initializing the `Users.userID` with a unique UUID -* creating a new `UsersContact `entry with the given email address and *maincontact* as `usedChannel ` -* set `emailID `in the `Users `table as foreign key to the new `UsersContact `entry -* set `Users.passphraseEncrpytionType = 2` and encrypt the passphrase with the `Users.userID` instead of the `UsersContact.email` - -#### Login Process - -The logic of the login process has to be adapted by - -* search the users data by reading the `Users `and the `UsersContact` table with the email (or alias as soon as the user can maintain his profil with an alias) as input -* depending on the `Users.passphraseEncryptionType` decrypt the stored password - * = 1 : with the email - * = 2 : with the userID - -#### Password En/Decryption - -The logic of the password en/decryption has to be adapted by encapsulate the logic to be controlled with an input parameter. The input parameter can be the email or the userID. - -#### Change Password Process - -The logic of change password has to be adapted by - -* if the `Users.passphraseEncryptionType` = 1, then - - * read the users email address from the `UsersContact `table - * give the email address as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption fo the new password - * change the `Users.passphraseEnrycptionType` to the new value =2 -* if the `Users.passphraseEncryptionType` = 2, then - - * give the `Users.userID` as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption fo the new password - -#### Search- and Access Logic - -A new logic has to be introduced to search the user identity per different input values. That means searching the user data must be possible by - -* searching per email (only with maincontact as contactchannel) -* searching per userID -* searching per alias - -#### Identity-Mapping - -A new mapping logic will be necessary to allow using unmigrated APIs like GDT-servers api. So it must be possible to give this identity-mapping logic the following input to get the respective output: - -* email -> userID -* email -> alias -* userID -> email -* userID -> alias -* alias -> email -* alias -> userID - -#### GDT-Access - -To use the GDT-servers api the used identifier for GDT has to be switch from email to userID. +# Introduction of Gradido-ID + +## Motivation + +The introduction of the Gradido-ID base on the requirement to identify an user account per technical key instead of using an email-address. Such a technical key ensures an exact identification of an user account without giving detailed information for possible missusage. + +Additionally the Gradido-ID allows to administrade any user account data like changing the email address or define several email addresses without any side effects on the identification of the user account. + +## Definition + +The formalized definition of the Gradido-ID can be found in the document [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID). + +## Steps of Introduction + +To Introduce the Gradido-ID there are several steps necessary. The first step is to define a proper database schema with additional columns and tables followed by data migration steps to add or initialize the new columns and tables by keeping valid data at all. + +The second step is to decribe all concerning business logic processes, which have to be adapted by introducing the Gradido-ID. + +### Database-Schema + +#### Users-Table + +The entity users has to be changed by adding the following columns. + +| Column | Type | Description | +| ------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | +| gradidoID | String | technical unique key of the user as UUID (version 4) | +| alias | String | a business unique key of the user | +| passphraseEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | +| emailID | int | technical foreign key to the entry with type Email and contactChannel=maincontact of the new entity UserContacts | + +##### Email vs emailID + +The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table. + +The preferred and proper solution will be to add a new column `Users.emailId `as foreign key to the `UsersContact `entry and delete the `Users.email` column after the migration of the email address in the `UsersContact `table. + +#### new UserContacts-Table + +A new entity `UserContacts `is introduced to store several contacts of different types like email, telephone or other kinds of contact addresses. + +| Column | Type | Description | +| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | int | the technical key of a contact entity | +| type | int | Defines the type of contact entry as enum: Email, Phone, etc | +| usersID | int | Defines the foreign key to the `Users` table | +| email | String | defines the address of a contact entry of type Email | +| phone | String | defines the address of a contact entry of type Phone | +| contactChannels | String | define the contact channel as comma separated list for which this entry is confirmed by the user e.g. main contact (default), infomail, contracting, advertisings, ... | + +### Database-Migration + +After the adaption of the database schema and to keep valid consistent data, there must be several steps of data migration to initialize the new and changed columns and tables. + +#### Initialize GradidoID + +In a one-time migration create for each entry of the `Users `tabel an unique UUID (version4). + +#### Primary Email Contact + +In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UsersContact `table, by initializing the contact-values with: + +* id = new technical key +* type = Enum-Email +* userID = `Users.id` +* email = `Users.email` +* phone = null +* usedChannel = Enum-"main contact" + +and update the `Users `entry with `Users.emailId = UsersContact.Id` and `Users.passphraseEncryptionType = 1` + +After this one-time migration the column `Users.email` can be deleted. + +### Adaption of BusinessLogic + +The following logic or business processes has to be adapted for introducing the Gradido-ID + +#### Read-Write Access of Users-Table especially Email + +The ORM mapping has to be adapted to the changed and new database schema. + +#### Registration Process + +The logic of the registration process has to be adapted by + +* initializing the `Users.userID` with a unique UUID +* creating a new `UsersContact `entry with the given email address and *maincontact* as `usedChannel ` +* set `emailID `in the `Users `table as foreign key to the new `UsersContact `entry +* set `Users.passphraseEncrpytionType = 2` and encrypt the passphrase with the `Users.userID` instead of the `UsersContact.email` + +#### Login Process + +The logic of the login process has to be adapted by + +* search the users data by reading the `Users `and the `UsersContact` table with the email (or alias as soon as the user can maintain his profil with an alias) as input +* depending on the `Users.passphraseEncryptionType` decrypt the stored password + * = 1 : with the email + * = 2 : with the userID + +#### Password En/Decryption + +The logic of the password en/decryption has to be adapted by encapsulate the logic to be controlled with an input parameter. The input parameter can be the email or the userID. + +#### Change Password Process + +The logic of change password has to be adapted by + +* if the `Users.passphraseEncryptionType` = 1, then + + * read the users email address from the `UsersContact `table + * give the email address as input for the password decryption of the existing password + * use the `Users.userID` as input for the password encryption for the new password + * change the `Users.passphraseEnrycptionType` to the new value =2 +* if the `Users.passphraseEncryptionType` = 2, then + + * give the `Users.userID` as input for the password decryption of the existing password + * use the `Users.userID` as input for the password encryption fo the new password + +#### Search- and Access Logic + +A new logic has to be introduced to search the user identity per different input values. That means searching the user data must be possible by + +* searching per email (only with maincontact as contactchannel) +* searching per userID +* searching per alias + +#### Identity-Mapping + +A new mapping logic will be necessary to allow using unmigrated APIs like GDT-servers api. So it must be possible to give this identity-mapping logic the following input to get the respective output: + +* email -> userID +* email -> gradidoID +* email -> alias +* userID -> gradidoID +* userID -> email +* userID -> alias +* alias -> gradidoID +* alias -> email +* alias -> userID +* gradidoID -> email +* gradidoID -> userID +* gradidoID -> alias + +#### GDT-Access + +To use the GDT-servers api the used identifier for GDT has to be switch from email to userID. From 56ed064c68ef573a60481ed6bef349719a67bdbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus-Peter=20H=C3=BCbner?= Date: Thu, 25 Aug 2022 00:14:35 +0200 Subject: [PATCH 2/3] add some details and ticket references --- .../UC_Introduction_of_Gradido-ID.md | 89 +++++++++++-------- 1 file changed, 51 insertions(+), 38 deletions(-) diff --git a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md index 5da969eac..adc3e9ca3 100644 --- a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md +++ b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md @@ -20,54 +20,61 @@ The second step is to decribe all concerning business logic processes, which hav #### Users-Table -The entity users has to be changed by adding the following columns. +The entity users has to be changed by adding the following columns. The column State gives a hint about the working state including the ticket number. -| Column | Type | Description | -| ------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | -| gradidoID | String | technical unique key of the user as UUID (version 4) | -| alias | String | a business unique key of the user | -| passphraseEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | -| emailID | int | technical foreign key to the entry with type Email and contactChannel=maincontact of the new entity UserContacts | +| State | Column | Type | Description | +| -------------- | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *done #2125* | gradidoID | String | technical unique key of the user as UUID (version 4) | +| *done #2125* | alias | String | a business unique key of the user | +| *open* | passwordEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | +| *open* | emailID | int | technical foreign key to the UserContacts-Table with the entry of type Email, which will be interpreted as the maincontact from the Users table point of view | ##### Email vs emailID -The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table. +The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. -The preferred and proper solution will be to add a new column `Users.emailId `as foreign key to the `UsersContact `entry and delete the `Users.email` column after the migration of the email address in the `UsersContact `table. +###### ToDo: + +It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table. + +The **preferred and proper solution** will be to add the new column `Users.emailId `as foreign key to the `UserContacts `entry and delete the `Users.email` column after the migration of the email address in the `UserContacts `table. #### new UserContacts-Table A new entity `UserContacts `is introduced to store several contacts of different types like email, telephone or other kinds of contact addresses. -| Column | Type | Description | -| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | int | the technical key of a contact entity | -| type | int | Defines the type of contact entry as enum: Email, Phone, etc | -| usersID | int | Defines the foreign key to the `Users` table | -| email | String | defines the address of a contact entry of type Email | -| phone | String | defines the address of a contact entry of type Phone | -| contactChannels | String | define the contact channel as comma separated list for which this entry is confirmed by the user e.g. main contact (default), infomail, contracting, advertisings, ... | +| Column | Type | Description | +| ------ | ------ | ------------------------------------------------------------ | +| id | int | the technical key of a contact entity | +| type | int | Defines the type of contact entry as enum: Email, Phone, etc | +| userID | int | Defines the foreign key to the `Users` table | +| email | String | defines the address of a contact entry of type Email | +| phone | String | defines the address of a contact entry of type Phone | + +##### ToDo: + +The UserContacts, expecially the email contacts, will for future be categorized to communication channels for example to allow the user to define which information he will get on which email-contact (aspects of administration, contract, advertising, etc.) ### Database-Migration After the adaption of the database schema and to keep valid consistent data, there must be several steps of data migration to initialize the new and changed columns and tables. -#### Initialize GradidoID +#### Initialize GradidoID (done #2125) In a one-time migration create for each entry of the `Users `tabel an unique UUID (version4). -#### Primary Email Contact +#### Primary Email Contact (ongoing #1798) -In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UsersContact `table, by initializing the contact-values with: +In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UserContacts `table, by initializing the contact-values with: * id = new technical key * type = Enum-Email -* userID = `Users.id` -* email = `Users.email` +* userID =`Users.id` +* email =`Users.email` * phone = null * usedChannel = Enum-"main contact" -and update the `Users `entry with `Users.emailId = UsersContact.Id` and `Users.passphraseEncryptionType = 1` +and update the `Users `entry with `Users.emailId = UserContacts.Id` and `Users.passwordEncryptionType = 1` After this one-time migration the column `Users.email` can be deleted. @@ -75,7 +82,13 @@ After this one-time migration the column `Users.email` can be deleted. The following logic or business processes has to be adapted for introducing the Gradido-ID -#### Read-Write Access of Users-Table especially Email +#### Capturing of alias + +To avoid using the email as primary identifier it is necessary to introduce a capturing of the alias. It is not a good solution to create for existing users an individual alias by a migration. So each user should capture his own alias during registration- and/or login-process. + +These requirements are described in the concept document [../BusinessRequirements/UC_Set_UserAlias.md]() **(done #2144)** and the implementation of these requirements will be the prerequisite for changing the login-process from single email-identifier to the future identifiers alias / gradidoID / email. + +#### Read-Write Access of Users-Table especially Email (ongoing #1798) The ORM mapping has to be adapted to the changed and new database schema. @@ -83,19 +96,19 @@ The ORM mapping has to be adapted to the changed and new database schema. The logic of the registration process has to be adapted by -* initializing the `Users.userID` with a unique UUID -* creating a new `UsersContact `entry with the given email address and *maincontact* as `usedChannel ` -* set `emailID `in the `Users `table as foreign key to the new `UsersContact `entry -* set `Users.passphraseEncrpytionType = 2` and encrypt the passphrase with the `Users.userID` instead of the `UsersContact.email` +* creating a new User including with a unique UUID-V4 **(done #2125)** +* creating a new `UserContacts `entry with the given email address **(ongoing #2165)** +* set `emailID `in the `Users `table as foreign key to the new `UserContacts `entry **(ongoing #2165)** +* set `Users.passwordEncrpytionType = 2` and encrypt the password with the `Users.gradidoID` instead of the `UserContacts.email` #### Login Process The logic of the login process has to be adapted by -* search the users data by reading the `Users `and the `UsersContact` table with the email (or alias as soon as the user can maintain his profil with an alias) as input -* depending on the `Users.passphraseEncryptionType` decrypt the stored password - * = 1 : with the email - * = 2 : with the userID +* search the users data by reading the `Users `and the `UsersContact` table with the `email` as input **(ongoing #2165)** +* depending on the `Users.passwordEncryptionType` decrypt the stored password + * = 1 : with the email and the existing cryptographical logic (asymetric encryption) + * = 2 : with the gradidoID and the new cryptographical logic (hashing) #### Password En/Decryption @@ -105,16 +118,16 @@ The logic of the password en/decryption has to be adapted by encapsulate the log The logic of change password has to be adapted by -* if the `Users.passphraseEncryptionType` = 1, then +* if the `Users.passwordEncryptionType` = 1, then * read the users email address from the `UsersContact `table * give the email address as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption for the new password - * change the `Users.passphraseEnrycptionType` to the new value =2 -* if the `Users.passphraseEncryptionType` = 2, then + * use the `Users.gradidoID` as input for the password hashing, which will be stored in `Users.password` + * change the `Users.passwordEnrycptionType` to the new value =2 +* if the `Users.passwordEncryptionType` = 2, then - * give the `Users.userID` as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption fo the new password + * give the `Users.gradidoID` as input for the password hashing anddecryption of the existing password + * use the `Users.gradidoID` as input for the password encryption fo the new password #### Search- and Access Logic From c263a1ee6cbf7a0d3b418648baf4495b2fa1dcce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus-Peter=20H=C3=BCbner?= Date: Thu, 6 Oct 2022 20:40:12 +0200 Subject: [PATCH 3/3] finish description of stage-2 --- .../UC_Introduction_of_Gradido-ID.md | 81 ++++++++++++------- 1 file changed, 54 insertions(+), 27 deletions(-) diff --git a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md index 7685ab74d..a6ca83bfc 100644 --- a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md +++ b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md @@ -22,12 +22,11 @@ The second step is to decribe all concerning business logic processes, which hav The entity users has to be changed by adding the following columns. The column State gives a hint about the working state including the ticket number. -| State | Column | Type | Description | -| -------------- | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| *done #2125* | gradidoID | String | technical unique key of the user as UUID (version 4) | -| *done #2125* | alias | String | a business unique key of the user | -| *open* | passwordEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | -| *done #2165* | emailID | int | technical foreign key to the UserContacts-Table with the entry of type Email, which will be interpreted as the maincontact from the Users table point of view | +| State | Column | Type | Description | +| -------------- | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *done #2125* | gradidoID | String | technical unique key of the user as UUID (version 4) | +| *done #2125* | alias | String | a business unique key of the user | +| *done #2165* | emailID | int | technical foreign key to the UserContacts-Table with the entry of type Email, which will be interpreted as the maincontact from the Users table point of view | ##### Email vs emailID @@ -126,7 +125,7 @@ The logic of all password processes has to be adapted by ## 2nd Stage -In the 2nd stage of this topic the password handling during registration and login process will be changed. These change must keep the current active password handling where the email is part of the encryption as long as all users are shifted to the new logic of password handling where the gradidoID will part of the encryption. This means there must be a kind of versioning which type of password encryption is currently used, because in the future there could be the requirement to change the password handling to newer and safer algorithms. +In the 2nd stage of this topic the password handling during registration and login process will be changed. These change must keep the current active password handling where the email is part of the encryption as long as all users are shifted to the new logic of password handling where the gradidoID will part of the encryption. This means there must be a kind of versioning which type of password encryption is used. Because some users will not login for a long time, which causes to use the old password encryption at their login process or in the future there could be the requirement to change the password handling to newer and safer algorithms. ### Database-Schema @@ -146,19 +145,21 @@ The entity *users* has to be changed by #### Password En/Decryption -The logic of the existing password en/decryption has to be shifted out of the `UserResolver.js` file in separated file(s). This separated file will be placed in the package-directory `backend/src/password` and named `emailEncryptor.js`. As the name express the password encryption uses the `email `attribute. +The logic of the existing password en/decryption has to be shifted out of the ***UserResolver.js*** file in separated file(s). This separated file will be placed in the package-directory `backend/src/password` and named ***emailEncryptor.js***. As the name express the password encryption uses the `email `attribute. -For the new password encryption logic a new file named `gradidoIDEncryptor.js` has to be created in the package-directory `backend/src/password`. For possible future requirements of newer and safer encryption logic additional files can be placed in the same directory with expressiv file names. +For the new password encryption logic a new file named ***gradidoIDEncryptor.js*** has to be created in the package-directory `backend/src/password`, which uses the *gradidoID* instead of the *email* for the password encryption. As soon as a user is changed to this encryption type with the *gradidoID*, it will be possible for him to change his *email* in his gradido-profile without any effect on his password encryption. + +For possible future requirements of newer and safer encryption logic additional files can be placed in the same directory with an expressiv file name for the new encryption type. All these `xxxEncryptor `files has to implement the following API, but with possibly different parameter types, depending on the encryption requirements: -| API | emailEncryptor | gradidoIDEncryptor | return | description | -| -------------------- | ---------------- | ------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| API | emailEncryptor | gradidoIDEncryptor | return | description | +| ------------------------- | ---------------- | ------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **encryptPassword** | dbUser, password | dbUser, password | encrypted password | process the encryption with
the encryptor specific attributs
out of the dbUser and the original 
password entered by the user | | **verifyPassword** | dbUser, password | dbUser, password | boolean | process the decryption with
the encryptor specific attributs
out of the dbUser and the original
password entrered by the user | | **isPassword** | password | password | boolean | verifiy the formal rules of the original
password entered by the user | -Which of the *xxxEncryptor* implementations will be used, depends on the value of the attribute `user.passwordEncryptionType`, which has to be interpreted before. +Which of the *xxxEncryptor* implementations will be used, depends on the value of the attribute `user.passwordEncryptionType`, which has to be interpreted before. To encapsulate this logic from the general business logic the ***Encryptor.js*** will be created with the same API as the specific *encryptor* classes, but it will interpret the attribute `dbUser.passwordEncryptionType` to select and invoke the correct *encryptor* implementation and to decide if an upgrade to a newer *encryptor* class should be done. The new Enum `PasswordEncryptionType `with the increasing values: @@ -166,26 +167,52 @@ The new Enum `PasswordEncryptionType `with the increasing values: * 2 = gradidoIDEncryptor * ... = ? -will be used to define the order which encryptor implementation is the oldest and the newest. That means if a user is still not using the newest encryptor for his password encryption the business logic will implicit start a change to the newest encryptor. This has to be inserted in all business processes, where the user enters his password, because without the original entered password from the user no encryptor upgrade can be done. +will be used to define the order, which encryptor implementation is the oldest and the newest. That means if a user is still not using the newest *encryptor* for his password encryption the logic will implicit start a change to the newest *encryptor*. In all business processes, where the user enters his password the invokation of the ***Encryptor.js*** has to be introduced, because without the original entered password from the user no *encryptor* upgrade can be done. #### Registration Process -The logic of the registration process has to be adapted +The backend logic of the registration process has to be adapted -* the general business logic of the ***createUser*** process will not be changed -* during the user creation set the attribut `Users.passwordEncrpytionType = 2` -* on activating the email-confirmation link the **queryOptIn** methode of the `UserResolver `is called -* because of the `users.passwordEncryptionType = 2` the `gradidoIDEncryptor `has to be used for encrypting and setting the password -* the `gradidoIDEncryptor` - * encrypts the password with the `Users.gradidoID` instead of the `UserContacts.email` - * it will creates a password-hash by using the gradidoID -* +* the ***UserResolver.createUser*** logic has to be changed by setting for a new user the attribut `Users.passwordEncrpytionType = 2` +* As soon as the user activates the email-confirmation link `https://gradido.net/checkEmail/` the application frontend invokes + + * at first the ***UserResolver.queryOptIn*** method, which will not be necessary, because the same checks about the given *emailOptIn*-code will be done a 2nd time in the invocation of *UserResolver.setPassword* + * at second the ***UserResolver.setPassword*** method, which has to be changed + * to use the new ***Encryptor.isPassword*** to validate the formal rules of the given password + * to remove all cryptographic logic like passphrase and key pair generation and password hashing to the new ***emailEncryptor.js*** + * to introduce the invocation of the new ***Encryptor.encryptPassword*** in the existing logic flow #### Login Process -The logic of the login process has to be adapted by +The logic of the login process has to be adapted in frontend and backend -* search the users data by reading the `Users `and the `UsersContact` table with the `email` as input **(ongoing #2165)** -* depending on the `Users.passwordEncryptionType` decrypt the stored password - * = 1 : with the email and the existing cryptographical logic (asymetric encryption) - * = 2 : with the gradidoID and the new cryptographical logic (hashing)#### Change Password Process +* Frontend + * The login dialog has to be changed at the email input component + * the new label contains "Email / Alias / GradidoID" + * the validation of the input field has to be changed to accept the input of one of these three possible values + * in case of failed validation an expressiv error message for the specific given input has to be shown (for more details about the rules for alias and gradidoID see the concepts [UC_SetUserAlias.md](../BusinessRequirements/UC_SetUserAlias.md) and [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID)). + * The signature of the backend invocation ***UserResolver.login*** has to be changed to accept all three variants of identifiers + * depending on the implemented backend solution the frontend has to detect and initialize the correct parameter settings +* Backend + * The signature of the backend invocation ***UserResolver.login*** has to be changed to accept all three variants of identifiers + * solution-A: the first parameter *email* is renamed to *identifier* and the backend has to detect which type of identifier is given + * solution-B: two additional parameters *alias* and *gradidoID* are inserted in the type ***UnsecureLoginArgs*** and the frontend has to decide, which type of identifier is given and initialize the correct parameter + * **TODO**: solution-A is preferred? + * The logic of ***UserResolver.login*** has to be changed by + * in case of solution-A for the signature, the given identifier has to be detected for the correct user searching + * the user to be searched by the given identifier (email / alias / gradidoID) + * if a user could be found all the existing checks will be done as is, except the public and private key check, which will be removed + * for the password check the new ***Encryptor.isPassword*** and ***Encryptor.verifyPassword*** has to be invoked; all existing cryptographic logic has to be deleted + +#### Change Password Process + +There are two ways to change a user password. + +The first one is the *Forget-Password process*, which will use the same backend invocation with activating the email link like the *Registration Process* to set the password; for details see description above. + +The second one is the *Update-Userinfo process*, which invokes the ***UserResolver.updateUserInfos***. This method has to be changed in the *password check block* by + +* removing all the cryptographic logic and +* invoke the new ***Encryptor.isPassword*** for the given *newPassword* and if valid then +* invoke the new ***Encryptor.verifyPassword*** for the given *oldPassword* and if valid then +* invoke the new ***Encryptor.encryptPassword*** for the given *newPassword*