The PasswordHash CPF setting
During automated deployment of InterSystems IRIS on UNIX and Linux platforms, you can change the default password for one or more instances before they are first started using the configuration parameter file (CPF) PasswordHash setting in conjunction with the configuration merge featureOpens in a new tab.
Rather than recording the plain-text password for each account (a security risk), InterSystems IRIS stores only an irreversible cryptographic hash of that password; when the user logs in, the password value entered is hashed using the same algorithms, and the two versions are compared to authenticate the user. For more information about the stored password hash, see Instance AuthenticationOpens in a new tab.
You can set or change the stored password hash (and thus the password) for all of a newly-deployed instance’s predefined accounts (enabled user accounts that have at least one assigned role) using the PasswordHashOpens in a new tab setting, which is in the [Startup] section of the CPF. When included in a configuration merge fileOpens in a new tab at deployment (on UNIX® and Linux systems only), this setting customizes the default password of the predefined accounts on the instance (except CSPSystem, which does not have an assigned role), replacing SYS with the password of which the provided value is a hash.
Immediately after deployment, as noted above, you should individually change the passwords of the predefined accounts from the new default password set by PasswordHash. The PasswordHash parameter works just once for a given instance, and can therefore be left in an instance’s CPF without having any effect.
The arguments to the PasswordHash parameter are a hashed password and its salt, and optionally the hashing algorithm and work factor used to hash the password (the defaults for the latter are SHA512 and 10000, respectively). All of these arguments are shown in the following example:
[Startup]
PasswordHash=0fad6b1a565e04efb5fe9259da8457456883e0a3a42c1a34acec49cbbc1fb8c4c40f1846559ce180c103898db836,dd0874dc346d23679ed1b49dd9f48baae82b9062,10000,SHA512
A description of the algorithms used to convert a plain-text password to these values is contained in Instance AuthenticationOpens in a new tab, and tools for applying them are available in the %SYSTEM.EncryptionOpens in a new tab API. However, undertaking this conversion as a manual procedure is not recommended, as it is likely to be error-prone and time-consuming. For your convenience, the InterSystems Container Registry (described in Downloading the InterSystems IRIS Image) provides the image for a nanocontainer, passwordhash, that does this conversion for you and displays the result in the context of the PasswordHash parameter. You can optionally specify the workfactor and algorithm you want to use; if not, the default are used. The following is an example of using this container:
$ docker run --rm -it containers.intersystems.com/intersystems/passwordhash:1.1 -algorithm SHA512 -workfactor 10000
Enter password:
Enter password again:
PasswordHash=0fad6b1a565e04efb5fe9259da8457456883e0a3a42c1a34acec49cbbc1fb8c4c40f1846559ce180c103898db836,dd0874dc346d23679ed1b49dd9f48baae82b9062,10000,SHA512
You would then copy and paste the output and place it in the [Startup] section of your configuration merge file as shown above. After deployment, the default password for the predefined accounts (other than CSPSystem) is what you entered at the prompts.
Note:
You can display usage information using the iris-main --help option as shown:
$ docker run containers.intersystems.com/intersystems/passwordhash:1.1 --help
Usage of /passwordhash:
-algorithm string
Pseudorandom function to use (default "SHA512")
-workfactor int
PBKDF2 Work Factor (default 10000)
You can also provide the password to be hashed as input in the command, for example:
$ echo **** | docker run --rm -i containers.intersystems.com/intersystems/passwordhash:1.1
Important:
The PasswordHash property can be used just once on any given InterSystems IRIS instance, and only if the default password has not yet been changed for any of the predefined accounts. Because allowing the default password to remain unchanged following deployment is a serious security risk, the PasswordHash setting should be used in a configuration merge operation to change the default password during deployment and not later. (For information on how to change an individual user’s password, see Edit an Existing User Account.)
Note:
Blank passwords cannot be used with the PasswordHash setting.
The SYS.ContainerOpens in a new tab API
InterSystems IRIS is distributed with an API call, SYS.Container.ChangePassword()Opens in a new tab, that is also useful in scripts and other automation. SYS.Container.ChangePassword()Opens in a new tab changes the password of all of an instance’s enabled user accounts that have at least one assigned role to the contents of a user-provided file. (The option of specifying a read-only password file is provided for compatibility with Docker Secrets, Kubernetes Secrets, and similar technologies.) The change is made during the instance’s first startup, before login is possible, and is called by the changePassword.sh script and thus by the iris-main --password-file option. When using it, bear in mind the risks of committing the password to a file for any significant length of time.
The API also includes the SYS.Container.ChangeGatewayMgrPassword()Opens in a new tab call (also called by the script) which changes the password of the CSPSystem account on both the InterSystems IRIS instance and the local Web Gateway, if any.
For information about the SYS.Container API, see SYS.Container API.
