fix pbkdf2_prf sha/sha1 handling

fix

Author: Jan Kopcsek

COUCH_MIGRATION.md

@@ -0,0 +1,78 @@
+# CouchDB Migration 3.3 -> 3.4+
+
+## Upgraded couch-auth, configured on old hashing
+
+### Preconditions
+
+- CouchDB running at 3.3
+- `couch-auth` at 0.21.2
+
+### Steps
+
+- Configure couch-auth session hashing to CouchDB 3.3 settings:
+
+  ```
+  sessionHashing: {
+    pbkdf2Prf: 'sha',
+    iterations: 10,
+  }
+  ```
+
+  This will use a 16 byte salt and 20 byte key. This does not influence hashing of the `sl-users` passwords.
+
+- Upgrade couch-auth to 0.23.0
+- Deploy
+
+### Expected result
+
+- Everything works as before, only that `_users` documents get additional fields for the `prf` and `iterations` used. These values are used by `couch-auth` and CouchDB when checking against the hash, thus ensuring that both systems are able to work with the hash.
+
+## Upgrade CouchDB
+
+### Preconditions
+
+- CouchDB running at 3.3
+- `couch-auth` at >0.23.0 configured on `sha` with 10 iterations
+
+### Steps (with auto upgrade)
+
+- Decide on how many iterations you want. CouchDB defaults to 600,000 but that takes some time and `couch-auth` doesn't have caching, but the passwords are synthetic and short-lived. Let's use 1000 in this example.
+- Configure CouchDB `chttpd_auth`:
+  - Set `upgrade_hash_on_auth` to true
+  - Set `iterations` to 1000
+
+At this point, `couch-auth` will generate `_users` with sha/10 and couch db will upgrade them to sha256/1000. As CouchDB will update the `iterations` and `pbkdf2_prf` fields, `couch-auth` will be able to work with those hashes as well.
+
+- Align configuration of `couch-auth`:
+  - Set `pbkdf2Prf` to `sha256`
+  - Set `iterations` to 1000
+
+At this point, there is no need for auto upgrading anymore as the `_users` are already generated with the correct values.
+
+### Steps (without auto upgrade)
+
+- Decide on how many iterations you want. CouchDB defaults to 600,000 but that takes some time and `couch-auth` doesn't have caching, but the passwords are synthetic and short-lived. Let's use 1000 in this example.
+- Configure CouchDB `chttpd_auth`:
+  - Set `upgrade_hash_on_auth` to false
+  - Set `iterations` to 1000
+
+At this point, `couch-auth` will generate `_users` with sha/10 and couch db will be able to work with them as well.
+
+- Upgrade security in `couch-auth`:
+  - Set `pbkdf2Prf` to `sha256`
+  - Set `iterations` to 1000
+
+At this point, any new `_users` are generated with the more secure hashes. Existing `_users` are still valid for both systems.
+
+### Expected result
+
+- As all `_users` are generated with `iterations` and `pbkdf2_prf` and both systems respect them when resolving the hash, no matter if you use auto upgrade or not and if both systems are configured to use the same iterations or not, the `_users` can be validated by both systems.
+
+## Tests
+
+| CouchDB     | couch-auth  | auto up | Works |
+| ----------- | ----------- | ------- | ----- |
+| CouchDB 3.3 | sha/10      | -       | Yep   |
+| CouchDB 3.5 | sha/10      | No      | Yep   |
+| CouchDB 3.5 | sha/10      | Yes     | Yep   |
+| CouchDB 3.5 | sha256/1000 |         | Yep   |

src/session-hashing.ts

@@ -9,19 +9,22 @@ export class SessionHashing {
 
   // Hasher for hashing _users passwords
   private pwdCouch: pwdModule;
+  private iterations: number;
+  private pbkdf2Prf: string;
+  private keyLength: number;
+  private saltLength: number;
 
   constructor(config: Partial<Config>) {
-    const iterations = config.security?.sessionHashing?.iterations || 1000;
-    const pbkdf2Prf = config.security?.sessionHashing?.pbkdf2Prf || 'sha256';
-    const keyLength = config.security?.sessionHashing?.keyLength || 32;
-    const saltLength = config.security?.sessionHashing?.saltLength || 16;
+    this.iterations = config.security?.sessionHashing?.iterations || 1000;
+    this.pbkdf2Prf = config.security?.sessionHashing?.pbkdf2Prf || 'sha256';
+    this.keyLength = config.security?.sessionHashing?.keyLength || (this.pbkdf2Prf === 'sha' ? 20 : 32);
+    this.saltLength = config.security?.sessionHashing?.saltLength || 16;
 
-    this.pwdCouch = new pwdModule(
-      iterations,
-      keyLength,
-      saltLength,
-      'hex',
-      pbkdf2Prf
+    this.pwdCouch = SessionHashing.createPwdModule(
+      this.iterations,
+      this.keyLength,
+      this.saltLength,
+      this.pbkdf2Prf
     );
   }
 
@@ -36,8 +39,8 @@ export class SessionHashing {
           salt: salt,
           derived_key: hash,
           password_scheme: 'pbkdf2',
-          pbkdf2_prf: this.pwdCouch.digest,
-          iterations: this.pwdCouch.iterations
+          pbkdf2_prf: this.pbkdf2Prf,
+          iterations: this.iterations
         });
       });
     });
@@ -46,9 +49,9 @@ export class SessionHashing {
   public verifySessionPassword(hashObj: HashResult, pw: string): Promise<boolean> {
     return new Promise((resolve, reject) => {
       const iterations = hashObj.iterations || 10;
-      const digest = hashObj.pbkdf2_prf || 'sha1';
-      const length = digest === 'sha1' ? 20 : 32;
-      const pwdCouch = new pwdModule(iterations, length, 16, 'hex', digest);
+      const digest = hashObj.pbkdf2_prf || 'sha';
+      const length = digest === 'sha' ? 20 : 32;
+      const pwdCouch = SessionHashing.createPwdModule(iterations, length, 16, digest);
 
       const salt = hashObj.salt;
       const derived_key = hashObj.derived_key;
@@ -63,4 +66,14 @@ export class SessionHashing {
       });
     });
   }
+
+  private static createPwdModule(iterations: number, keyLength: number, saltLength: number, digest: string): pwdModule {
+    return new pwdModule(
+      iterations,
+      keyLength,
+      saltLength,
+      'hex',
+      digest === 'sha' ? 'sha1' : 'sha256'
+    );
+  }
 }

src/types/config.ts

@@ -94,8 +94,8 @@ export interface SecurityConfig {
    */
   iterations?: [number, number][];
   sessionHashing?: {
-    /** Hashing algorithm for pbkdf2, either 'sha1' or 'sha256'. Default: 'sha256' */
-    pbkdf2Prf?: 'sha1' | 'sha256';
+    /** Hashing algorithm for pbkdf2, either 'sha' or 'sha256'. Default: 'sha256' */
+    pbkdf2Prf?: 'sha' | 'sha256';
     /** Number of iterations for pbkdf2 password hashing. Default: 1000 */
     iterations?: number;
     /** Length of the derived key. Default: 32 */

src/types/typings.ts

@@ -63,7 +63,7 @@ export interface HashResult {
    */
   password_scheme?: string;
   /**
-   * The pseudorandom function used for PBKDF2 hashing (e.g., 'sha1' or 'sha256')
+   * The pseudorandom function used for PBKDF2 hashing (e.g., 'sha' or 'sha256')
    */
   pbkdf2_prf?: string;