From cc52d7977f504fe8c7082d945bf29db94df2064c Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 18 Sep 2024 17:40:07 -0400 Subject: [PATCH] Move password hasher info from BAPI docs to Clerk docs --- docs/references/backend/user/create-user.mdx | 68 +++++++++++++++++++- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/docs/references/backend/user/create-user.mdx b/docs/references/backend/user/create-user.mdx index db9dee0b12..d509833c36 100644 --- a/docs/references/backend/user/create-user.mdx +++ b/docs/references/backend/user/create-user.mdx @@ -84,9 +84,71 @@ function createUser(params: CreateUserParams): Promise --- - `passwordHasher?` - - `'argon2i' | 'argon2id' | 'bcrypt' | 'bcrypt_sha256_django' | 'md5' | 'pbkdf2_sha256' | 'pbkdf2_sha256_django' | 'pbkdf2_sha1' | 'phpass' | 'scrypt_firebase' | 'scrypt_werkzeug' | 'sha256'` - - The hashing algorithm that was used to generate the password digest. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk Backend API reference](/docs/reference/backend-api/tag/Users#operation/CreateUser){{ target: '_blank' }} for more information. + - `'argon2i' | 'argon2id' | 'awscognito' | 'bcrypt' | 'bcrypt_sha256_django' | 'md5' | 'pbkdf2_sha256' | 'pbkdf2_sha256_django' | 'pbkdf2_sha1' | 'phpass' | 'scrypt_firebase' | 'scrypt_werkzeug' | 'sha256'` + + The hashing algorithm that was used to generate the password digest. + The algorithms we support at the moment are: + + > [!WARNING] + > For password hashers considered insecure (currently, `MD5` and `SHA256`), the corresponding user password hashes will be transparently migrated to `bcrypt` (a secure hasher) upon the user's first successful password sign in. + > Insecure schemes are marked with `(insecure)` in the list below. + + - `awscognito` + - When set, `password_digest` must be in the format of `awscognito###`. + - Upon a successful migration, `password_hasher` will be updated to `bcrypt`, and `password_digest` will be updated to a `bcrypt` hash. + - See our [migration guide](https://clerk.com/docs/deployments/migrate-from-cognito) for usage details. + - [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt) + - When set, `password_digest` must be in the format of `$$$` + - [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/) + - This is the Django-specific variant of Bcrypt, using SHA256 hashing function. When set, `password_digest` must be in the format of (as exported from Django): `bcrypt_sha256$$$$` + - [`bcrypt_peppered`](https://github.com/heartcombo/devise) + - As used in implementations such as Devise for Ruby on Rails applications. Identical to bcrypt except for the fact that a `pepper` string is appended to the input before hashing. When set, `password_digest` must be in the format of `$$$$` + - [`md5` (insecure)](https://en.wikipedia.org/wiki/MD5) + - When set, `password_digest` must be in the format of `5f4dcc3b5aa765d61d8327deb882cf99` + - [`pbkdf2_sha1`](https://en.wikipedia.org/wiki/PBKDF2) + - When set, `password_digest` must be in the format of `pbkdf2_sha1$$$` or `pbkdf2_sha1$$$$` + - Accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead. Accepts the hash as a hex-encoded string. Optionally accepts the key length as the last parameter (defaults to 32). + - [`pbkdf2_sha256`](https://en.wikipedia.org/wiki/PBKDF2) + - This is the PBKDF2 algorithm using the SHA256 hashing function. When set, `password_digest` must be in the format of `pbkdf2_sha256$$$` + - Both the salt and the hash are expected to be base64-encoded. + - [`pbkdf2_sha512`](https://en.wikipedia.org/wiki/PBKDF2) + - This is the PBKDF2 algorithm using the SHA512 hashing function. When set, `password_digest` must be in the format of `pbkdf2_sha512$$$` + - [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/) + - This is the Django-specific variant of PBKDF2. When set, `password_digest` must be in the format of (as exported from Django): `pbkdf2_sha256$$$` + - The salt is expected to be un-encoded, the hash is expected base64-encoded. + - [`phpass`](https://www.openwall.com/phpass/) + - Portable public domain password hashing framework for use in PHP applications. When set, `password_digest` must be in the format of `$P$` + - `$P$` is the prefix used to identify `phpass` hashes. + - _rounds_ is a single character encoding a 6-bit integer representing the number of rounds used. + - _salt_ is eight characters drawn from \[./0-9A-Za-z], providing a 48-bit salt. + - _checksum_ is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5. + - [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/) + - The Firebase-specific variant of scrypt. When set, `password_digest` must be in the format of `$$$$$` + - _hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase. + - _salt:_ The salt used to generate the above hash. Again, this is given when exporting the user from Firebase. + - _signer key:_ The base64 encoded signer key. + - _salt separator:_ The base64 encoded salt separator. + - _rounds:_ The number of rounds the algorithm needs to run. + - _memory cost:_ The cost of the algorithm run + - The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase. The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters. + - [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash) + - The Werkzeug-specific variant of scrypt. When set, `password_digest` must be in the format of `$$$` + - _algorithm args:_ The algorithm used to generate the hash. + - _salt:_ The salt used to generate the above hash. + - _hash:_ The actual Base64 hash. + - [`sha256` (insecure)](https://en.wikipedia.org/wiki/SHA-2) + - When set, `password_digest` must be a 64-length hex string. For example: `9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08` + - [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. + - Algorithms in the argon2 family generate digests that encode the following information: + - _version (v):_ The argon version, version 19 is assumed + - _memory (m):_ The memory used by the algorithm (in kibibytes) + - _iterations (t):_ The number of iterations to perform + - _parallelism (p):_ The number of threads to use + - Parts are demarcated by the `$` character, with the first part identifying the algorithm variant The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest. + - When set, `password_digest` must be in the format of `$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc` + - For the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`: `$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU` + + If you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support). ---