gfxd encrypt-password

Generates an encrypted password string for use in the gemfirexd.properties file when configuring BUILTIN authentication, or when accessing an external data source with an AsyncEventListener implementation or DBsynchronizer configuration.

Syntax

gfxd encrypt-password
  [external]
  [-transformation=<name>]
  [-keysize=<size>]
  [-J-D<vmprop>=<prop-value>]  
  [-mcast-port=<port>]
  [-mcast-address=<address>]
  [-locators=<addresses>]
  [-bind-address=<addr>]
  [-<prop-name>=<prop-value>]*
The command prompts for a password and then displays the encrypted password (using options, if specified) on the console. If a console is not available, an exception is thrown. If the external option is included, the encrypted password is stored in the data dictionary for external use with DBSynchronizer or an AsyncEventListener implementation.
Note: When you execute the gfxd encrypt-password command, specify the same connection properties that GemFire XD members use to connect to the distributed system. For example, specify the same locator or multicast connection properties, as well as any authorization credentials that members require to join the distributed system.
Option Description
external Include the external option to encrypt and store a password within the GemFire XD distributed system, for use with external resources accessed by DBSynchronizer or a custom AsynchEventListener implementation. See Configuring DBSynchronizer or Implementing an AsyncEventListener for more information.

When you specify this option, you must supply additional options to connect to a running GemFire XD distributed system (either the -locators option or -mcast-port and -mcast-address). The distributed system generates a private key in the data dictionary to encrypt the password. You can use the AsyncEventHelper.decryptPassword method to decrypt the password in your AsyncEventListener implementation, in order to authenticate with an external data source.

This option can also be used in conjunction with the -transformation and -keysize options, described below.

Note: Each GemFire XD distributed system generates its own private key, and the encrypted value is specific to a particular distributed system. The key is regenerated if, for example, the data dictionary becomes corrrupted and a new data dictionary is created. In this case, you would need to generate new encrypted passwords using gfxd encrypt-password.
-transformation This option is only used in combination with the -external option. The transformation to use for symmetric key encryption (the encryption algorithm name). GemFire XD uses an AES encryption key factory by default. The following algorithm names are supported:
  • AES
  • ARCFOUR
  • DES
  • DESede
  • PBKDF2WithHmacSHA1
  • PBEWith<digest>And<encryption>
  • PBEWith<prf>And<encryption>

The last two algorithms define a factory to use for PKCS5 encryption. Specify an encryption algorithm name as well as a digest or PseudoRandom Function (PRF) to configure the factory (for example, PBEWithMD5AndDES).

See the Java Cryptography Architecture Sun Providers Documentation for more information about these algorithms.
-keysize This option is only used in combination with the -external option. The key size to use for the encryption key. The default is 128 bits.
-mcast-port

Multicast port used to communicate with other members of the distributed system. If zero, multicast is not used for member discovery (specify -locators instead).

Valid values are in the range 0–65535, with a default value of 10334.

-mcast-address

Multicast address used to discover other members of the distributed system. This value is used only if the -locators option is not specified.

The default multicast address is 239.192.81.1.

-locators

List of locators used to discover members of the distributed system. Supply all locators as comma-separated host:port values.

-bind-address The address to which this peer binds for receiving peer-to-peer messages. By default gfxd uses the hostname, or localhost if the hostname points to a local loopback address.
-<prop-name>=<prop-value>

Any other GemFire XD distributed system property.

Description

Example

When used without the external option, gfxd prompts for a password to encrypt, and then displays the encrypted password to the console.

The encrypted secret that is returned is specific to this particular GemFire XD distributed system, because the system uses a unique private key to generate the secret. An obfuscated version of the private key is stored in the persistent data dictionary. If you ever need to move the DBSynchronizer configuration to another GemFire XD system, or if the existing data dictionary is ever deleted and recreated, then you must generate and use a new encrypted secret for use with the new distributed system.

Note: To ensure the security of your system, protect any the AsyncEventListener/DBSynchronizer parameter files that contains the encrypted secret, as well as the persistent data dictionary files for the GemFire XD distributed system. Although the data dictionary obfuscates the private key that is used to generate the encrypted secret, you should consider any passwords to be compromised if either the a configuration file or the data dictionary are compromised.
gfxd encrypt-password -mcast-port=10334
Enter User Name: test_user
Enter password: test_encryption (not echoed to screen)
Re-enter password: test_encryption (not echoed to screen)
Encrypted to v23b60032c17ab973929e43d60acc597887a5f3d5658bd

You can then add the encrypted password to the specified BUILTIN user account in the gemfirexd.properties file, as described in Creating Users for BUILTIN Authentication.

See also Configuring DBSynchronizer for an example that uses the shared secret file in a DBSynchronizer parameter file.