Wiki source code of Password Property
Last modified by Simon Urli on 2026/09/08 09:32
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The "Password" property (##PasswordClass##) stores a password value on an XClass. It has two storage types: "Clear" (stored as plain text) and "Hash" (stored as an irreversible hash). The "Encrypt" storage type that existed in older versions has been removed. | ||
| 2 | |||
| 3 | == Supported Hash Algorithms == | ||
| 4 | |||
| 5 | |=Algorithm|=Key|=Notes | ||
| 6 | |Argon2|##argon2##|{{version since="18.8.0RC1, 18.4.5"}}Default algorithm{{/version}}. | ||
| 7 | |BCrypt|##bcrypt##|Limited to 72 characters. | ||
| 8 | |SCrypt|##scrypt##| | ||
| 9 | |PBKDF2|##pbkdf2##| | ||
| 10 | |SHA-1|##SHA-1##|Deprecated, kept for legacy passwords only. | ||
| 11 | |SHA-256|##SHA-256##|Deprecated, kept for legacy passwords only. | ||
| 12 | |SHA-512|##SHA-512##|Deprecated, was the previous default algorithm. | ||
| 13 | |||
| 14 | The algorithm used for a given property is configured on the XClass and defaults to Argon2 when not set. | ||
| 15 | |||
| 16 | == Encoded Password Format == | ||
| 17 | |||
| 18 | A hashed password is stored as ##{algorithmKey}<hash>##, e.g. ##{argon2}$argon2id$...##. | ||
| 19 | |||
| 20 | Passwords stored by versions prior to {{version}}18.8.0RC1, 18.4.5{{/version}} use the legacy format ##hash:<algorithmName>:<salt>:<hash>##. This format is still read and matched correctly, but is reported as outdated in the logs. | ||
| 21 | |||
| 22 | == Checking and Setting a Password == | ||
| 23 | |||
| 24 | Use ##BaseCollection#isPasswordValueMatching## and ##BaseCollection#setPasswordValue## to check or set a password on an XObject without handling the property class directly: | ||
| 25 | |||
| 26 | {{code language="java"}} | ||
| 27 | boolean matches = xobject.isPasswordValueMatching("password", rawPassword); | ||
| 28 | xobject.setPasswordValue("password", newRawPassword); | ||
| 29 | {{/code}} | ||
| 30 | |||
| 31 | ##PasswordClass#arePasswordsMatching(String, String)## is available when working directly with a ##PasswordClass## instance. ##PasswordClass#getEquivalentPassword## is deprecated since in favor of ##arePasswordsMatching##. | ||
| 32 | |||
| 33 | == Migrating Existing Passwords == | ||
| 34 | |||
| 35 | {{version since="18.4.5, 18.8.0RC1"}} | ||
| 36 | On upgrade to ##18.8.0RC1##, ##18.4.5## or later, a data migration re-encodes every legacy (##hash:##-prefixed) password by wrapping it with Argon2, without needing the original raw password. Passwords already using a Spring Security algorithm are left untouched. A property still using a deprecated algorithm (or the legacy format) logs a warning until it is re-hashed, which happens automatically the next time the password is set (e.g. on password change). | ||
| 37 | {{/version}} |
