Masking Passwords

By default all passwords in Apache ActiveMQ Artemis server’s configuration files are in plain text form. This usually poses no security issues as those files should be well protected from unauthorized accessing. However, in some circumstances a user doesn’t want to expose its passwords to more eyes than necessary.

Apache ActiveMQ Artemis can be configured to use ‘masked’ passwords in its configuration files. A masked password is an obscure string representation of a real password. To mask a password a user will use an ‘codec’. The codec takes in the real password and outputs the masked version. A user can then replace the real password in the configuration files with the new masked password. When Apache ActiveMQ Artemis loads a masked password it uses the codec to decode it back into the real password.

Apache ActiveMQ Artemis provides a default codec. Optionally users can use or implement their own codec for masking the passwords.

In general, a masked password can be identified using one of two ways. The first one is the ENC() syntax, i.e. any string value wrapped in ENC() is to be treated as a masked password. For example

ENC(xyz)

The above indicates that the password is masked and the masked value is xyz.

The ENC() syntax is the preferred way of masking a password and is universally supported in every password configuration in Artemis.

The other, legacy way is to use a mask-password attribute to tell that a password in a configuration file should be treated as ‘masked’. For example:

  1. <mask-password>true</mask-password>
  2. <cluster-password>xyz</cluster-password>

This method is now deprecated and exists only to maintain backward-compatibility. Newer configurations may not support it.

Generating a Masked Password

To get a mask for a password using the broker’s default codec run the mask command from your Artemis instance. This command will not work from the Artemis home:

  1. ./artemis mask <plaintextPassword>

You’ll get something like

  1. result: 32c6f67dae6cd61b0a7ad1702033aa81e6b2a760123f4360

Just copy 32c6f67dae6cd61b0a7ad1702033aa81e6b2a760123f4360 and replace your plaintext password with it using the ENC() syntax, e.g. ENC(32c6f67dae6cd61b0a7ad1702033aa81e6b2a760123f4360).

This process works for passwords in:

  • broker.xml
  • login.config
  • bootstrap.xml
  • management.xml

This process does not work for passwords in:

  • artemis-users.properties

Masked passwords for artemis-users.properties can be generated using the mask command using the --hash command-line option. However, this is also possible using the set of tools provided by the user command described below.

Masking Configuration

Besides supporting the ENC() syntax, the server configuration file (i.e. broker.xml) has a property that defines the default masking behaviors over the entire file scope.

mask-password: this boolean type property indicates if a password should be masked or not. Set it to “true” if you want your passwords masked. The default value is “false”. As noted above, this configuration parameter is deprecated.

password-codec: this string type property identifies the name of the class which will be used to decode the masked password within the broker. If not specified then the default org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec will be used.

artemis-users.properties

Apache ActiveMQ Artemis’s built-in security manager uses plain properties files where the user passwords are specified in a hashed form by default. Note, the passwords are technically hashed rather than masked in this context. The default PropertiesLoginModule will not decode the passwords in artemis-users.properties but will instead hash the input and compare the two hashed values for password verification.

Use the following command from the CLI of the Artemis instance you wish to add the user/password to. This command will not work from the Artemis home used to create the instance, and it will also not work unless the broker has been started. For example:

  1. ./artemis user add --user-command-user guest --user-command-password guest --role admin

This will use the default codec to perform a “one-way” hash of the password and alter both the artemis-users.properties and artemis-roles.properties files with the specified values.

Passwords in artemis-users.properties are automatically detected as hashed or not by looking for the syntax ENC(<hash>). The mask-password parameter does not need to be true to use hashed passwords here.

Warning

Management and CLI operations to manipulate user & role data are only available when using the PropertiesLoginModule.

In general, using properties files and broker-centric user management for anything other than very basic use-cases is not recommended. The broker is designed to deal with messages. It’s not in the business of managing users, although that functionality is provided at a limited level for convenience. LDAP is recommended for enterprise level production use-cases.

cluster-password

If it is specified in ENC() syntax it will be treated as masked, or if mask-password is true the cluster-password will be treated as masked.

Connectors & Acceptors

In broker.xml connector and acceptor configurations sometimes needs to specify passwords. For example, if a user wants to use an acceptor with sslEnabled=true it can specify keyStorePassword and trustStorePassword. Because Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.

The preferred way is simply to use the ENC() syntax.

If using the legacy mask-password and password-codec values then when a connector or acceptor is initialised, Apache ActiveMQ Artemis will add these values to the parameters using the keys activemq.usemaskedpassword and activemq.passwordcodec respectively. The Netty and InVM implementations will use these as needed and any other implementations will have access to these to use if they so wish.

Core Bridges

Core Bridges are configured in the server configuration file and so the masking of its password properties follows the same rules as that of cluster-password. It supports ENC() syntax.

For using mask-password property, the following table summarizes the relations among the above-mentioned properties

mask-passwordcluster-passwordacceptor/connector passwordsbridge password
absentplain textplain textplain text
falseplain textplain textplain text
truemaskedmaskedmasked

It is recommended that you use the ENC() syntax for new applications/deployments.

Examples

Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.

  • Unmasked

    1. <cluster-password>bbc</cluster-password>

    This indicates the cluster password is a plain text value bbc.

  • Masked 1

    1. <cluster-password>ENC(80cf731af62c290)</cluster-password>

    This indicates the cluster password is a masked value 80cf731af62c290.

  • Masked 2

    1. <mask-password>true</mask-password>
    2. <cluster-password>80cf731af62c290</cluster-password>

    This indicates the cluster password is a masked value and Apache ActiveMQ Artemis will use its built-in codec to decode it. All other passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.

bootstrap.xml

The broker embeds a web-server for hosting some web applications such as a management console. It is configured in bootstrap.xml as a web component. The web server can be secured using the https protocol, and it can be configured with a keystore password and/or truststore password which by default are specified in plain text forms.

To mask these passwords you need to use ENC() syntax. The mask-password boolean is not supported here.

You can also set the passwordCodec attribute if you want to use a password codec other than the default one. For example

  1. <web bind="https://localhost:8443" path="web" 
  2.      keyStorePassword="ENC(-5a2376c61c668aaf)"
  3.      trustStorePassword="ENC(3d617352d12839eb71208edf41d66b34)">
  4.     <app url="activemq-branding" war="activemq-branding.war"/>
  5. </web>

management.xml

The broker embeds a JMX connector which is used for management. The connector can be secured using SSL and it can be configured with a keystore password and/or truststore password which by default are specified in plain text forms.

To mask these passwords you need to use ENC() syntax. The mask-password boolean is not supported here.

You can also set the password-codec attribute if you want to use a password codec other than the default one. For example

  1. <connector
  2.       connector-port="1099"
  3.       connector-host="localhost"
  4.       secured="true"
  5.       key-store-path="myKeystore.jks"
  6.       key-store-password="ENC(3a34fd21b82bf2a822fa49a8d8fa115d"
  7.       trust-store-path="myTruststore.jks"
  8.       trust-store-password="ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"/>

With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.

login.config

Artemis supports LDAP login modules to be configured in JAAS configuration file (default name is login.config). When connecting to a LDAP server usually you need to supply a connection password in the config file. By default this password is in plain text form.

To mask it you need to configure the passwords in your login module using ENC() syntax. To specify a codec using the following property:

passwordCodec - the password codec class name. (the default codec will be used if it is absent)

For example:

  1. LDAPLoginExternalPasswordCodec {
  2.     org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
  3.         debug=true
  4.         initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
  5.         connectionURL="ldap://localhost:1024"
  6.         connectionUsername="uid=admin,ou=system"
  7.         connectionPassword="ENC(-170b9ef34d79ed12)"
  8.         passwordCodec="org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec;key=helloworld"
  9.         connectionProtocol=s
  10.         authentication=simple
  11.         userBase="ou=system"
  12.         userSearchMatching="(uid={0})"
  13.         userSearchSubtree=false
  14.         roleBase="ou=system"
  15.         roleName=dummyRoleName
  16.         roleSearchMatching="(uid={1})"
  17.         roleSearchSubtree=false
  18.         ;
  19. };

JCA Resource Adapter

Both ra.xml and MDB activation configuration have a password property that can be masked preferably using ENC() syntax.

Alternatively it can use an optional attribute in ra.xml to indicate that a password is masked:

UseMaskedPassword — If setting to “true” the passwords are masked. Default is false.

There is another property in ra.xml that can specify a codec:

PasswordCodec — Class name and its parameters for the codec used to decode the masked password. Ignored if UseMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs. It is the same format as that for JMS Bridges. Example:

Example 1 Using the ENC() syntax:

  1. <config-property>
  2.   <config-property-name>password</config-property-name>
  3.   <config-property-type>String</config-property-type>
  4.   <config-property-value>ENC(80cf731af62c290)</config-property-value>
  5. </config-property>
  6. <config-property>
  7.   <config-property-name>PasswordCodec</config-property-name>
  8.   <config-property-type>java.lang.String</config-property-type>
  9.   <config-property-value>com.foo.ACodec;key=helloworld</config-property-value>
  10. </config-property>

Example 2 Using the “UseMaskedPassword” property:

  1. <config-property>
  2.   <config-property-name>UseMaskedPassword</config-property-name>
  3.   <config-property-type>boolean</config-property-type>
  4.   <config-property-value>true</config-property-value>
  5. </config-property>
  6. <config-property>
  7.   <config-property-name>password</config-property-name>
  8.   <config-property-type>String</config-property-type>
  9.   <config-property-value>80cf731af62c290</config-property-value>
  10. </config-property>
  11. <config-property>
  12.   <config-property-name>PasswordCodec</config-property-name>
  13.   <config-property-type>java.lang.String</config-property-type>
  14.   <config-property-value>com.foo.ACodec;key=helloworld</config-property-value>
  15. </config-property>

Choosing a codec for password masking

As described in the previous sections, all password masking requires a codec. A codec uses an algorithm to convert a masked password into its original clear text form in order to be used in various security operations. The algorithm used for decoding must match that for encoding. Otherwise the decoding may not be successful.

For user’s convenience Apache ActiveMQ Artemis provides a default codec. However a user can implement their own if they wish.

The Default Codec

Whenever no codec is specified in the configuration, the default codec is used. The class name for the default codec is org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec. It has hashing, encoding, and decoding capabilities. It uses java.crypto.Cipher utilities to hash or encode a plaintext password and also to decode a masked string using the same algorithm and key.

Using a custom codec

It is possible to use a custom codec rather than the built-in one. Simply make sure the codec is in Apache ActiveMQ Artemis’s classpath. The custom codec can also be service loaded rather than class loaded, if the codec’s service provider is installed in the classpath. Then configure the server to use it as follows:

  1. <password-codec>com.foo.SomeCodec;key1=value1;key2=value2</password-codec>

If your codec needs params passed to it you can do this via key/value pairs when configuring. For instance if your codec needs say a “key-location” parameter, you can define like so:

  1. <password-codec>com.foo.NewCodec;key-location=/some/url/to/keyfile</password-codec>

Then configure your cluster-password like this:

  1. <cluster-password>ENC(masked_password)</cluster-password>

When Apache ActiveMQ Artemis reads the cluster-password it will initialize the NewCodec and use it to decode “mask_password”. It also process all passwords using the new defined codec.

Implementing Custom Codecs

To use a different codec than the built-in one, you either pick one from existing libraries or you implement it yourself. All codecs must implement the org.apache.activemq.artemis.utils.SensitiveDataCodec<T> interface:

  1. public interface SensitiveDataCodec<T> {
  3.    T decode(Object mask) throws Exception;
  5.    T encode(Object secret) throws Exception;
  7.    default void init(Map<String, String> params) throws Exception {
  8.    };
  9. }

This is a generic type interface but normally for a password you just need String type. So a new codec would be defined like

  1. public class MyCodec implements SensitiveDataCodec<String> {
  2.    @Override
  3.    public String decode(Object mask) throws Exception {
  4.       // Decode the mask into clear text password.
  5.       return "the password";
  6.    }
  8.    @Override
  9.    public String encode(Object secret) throws Exception {
  10.       // Mask the clear text password.
  11.       return "the masked password"";
  12.    }
  14.    @Override
  15.    public void init(Map<String, String> params) {
  16.       // Initialization done here. It is called right after the codec has been created.
  17.    }
  18. }

Last but not least, once you get your own codec please add it to the classpath otherwise the broker will fail to load it!