keystone
Version:
Web Application Framework and Admin GUI / Content Management System built on Express.js and Mongoose
88 lines (51 loc) • 3.73 kB
Markdown
# Password Field
Stores a `String` in the model.
Displayed as a password field in the Admin UI, with a 'change' button.
Passwords are automatically encrypted with `bcrypt`, and expose a method to compare a string to the encrypted hash.
> Note: The encryption happens with a **pre-save hook** added to the **schema**, so passwords set will not be encrypted until an item has been saved to the database.
## Example
```js
{ type: Types.Password }
```
## Options
`workFactor` `Number`
Supplied as the `bcrypt` cost parameter; controls the computational cost of generating and validating a hash.
Higher values are slower but, since they take longer to generate, more secure against brute force attacks.
Defaults to `10`.
At this level, a modern laptop (Late 2016 MacBook Pro, 3.3 GHz Intel Core i7) can produce around ~4 hashes/second.
The `bcrypt` algorithim applies this value as a power of two.
As such, passwords with a workfactor of `11` will take twice as long to store and validate as those with a workfactor of `10`.
Values lower than `4` are ignored by the underlying implementation (a value `10` is substituted).
`min` `Number`
Defines the minimum allowed password length in characters.
Defaults to `8` in accordance with the [NIST Digital Identity Guidelines](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf).
`max` `Number`
Defines the maximum allowed password length in characters.
The `bcrypt` algorithm, used by this field, operates on a 72 byte value.
Most implementation (including [the one we use](https://www.npmjs.com/package/bcrypt-nodejs)), silently truncate the string provided if it exceeds this limit.
The `max` length option defaults to 72 characters in an attempt to align with this limit.
> Note: If multi-byte (ie. non-ASCII) characters are allowed, it will be possible to exceed the 72 byte limit without triggering the 72 character validation limit.
Can be set to `false` to disable the max length check.
> Note: Disabling `max` or setting its value to >72 prevents validation errors but does not address the underlying algorithmic limitation.
`rejectCommon` `Boolean`
Controls whether values should be validated against a list of known-common passwords.
Defaults to `true` in accordance with the [NIST Digital Identity Guidelines](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf).
Implemented with the [`dumb-passwords` package](https://www.npmjs.com/package/dumb-passwords)
which validates against 10,000 common passwords complied by [security analyst Mark Burnett](https://xato.net/10-000-top-passwords-6d6380716fe0).
`complexity` `Object`
Allows to set complexity requirements:
* `digitChar` `Boolean` - when set to `true`, requires at least one digit
* `spChar` `Boolean` - when set to `true`, requires at least one from the following special characters: `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `+`
* `asciiChar` `Boolean` - when set to `true`, allows only ASCII characters (from range U+0020--U+007E)
* `lowChar` `Boolean` - when set to `true`, requires at least one lower case character
* `upperChar` `Boolean` - when set to `true`, requires at least one upper case character
Example:
```js
{ type: Types.Password, complexity: { digitChar: true, asciiChar: true } }
```
## Underscore methods
`compare(candidate, callback)` - encrypts the candidate and compares it against the encrypted hash
* `candidate` `String` to compare
* `callback(err, result)` - **result** is `true` if the candidate matches the stored password, or `false` if it doesn't
## Special paths
`{path}_compare` - when provided to the **updateHandler**, it will be checked against `{path}` and validation will fail if they don't match.