Encrypting Passwords in Your LYNX-APP Config File (Linux)

As part of your LYNX-APP installation, you may wish add an additional layer of protection to the passwords in your application.properties configuration file by encrypting the password text—rather than leaving them in plain text.

These steps are for configuration on a Linux server. For Windows instructions, see Encrypting Passwords in Your LYNX-APP Config File (Windows).

Encryption When Moving LYNX to a New Server

If you're moving your LYNX installation to a new server, remember that encryption is done on a per-server basis, so your old encryption will not transfer.


Create an Environment or Shell Variable

  • Choose an appropriate encryption password (consider your organization's guidelines if applicable).
  • For this example we will use an encryption password of RADIO_BLUE_LAPTOP.
  • Set a shell or environment variable called LYNX_ENCRYPT_PASSWORD with the desired value.
  • If you use a shell variable, you may need to use the EXPORT command to make it available to Lynx.

Environment variables may be set on session start, so the variable might not be available to the LYNX until the server is rebooted or the Linux admin logs out and in again.

Encrypt Your Passwords (LYNX-APP 1.2.3 and Newer)

  • Navigate to the installation directory of the LYNX-APP
  • Encrypt your two passwords (Lynx-WS password and SIS DB Lynx schema password) by running the lynx-app.jar with the following:
java -jar lynx-app.jar --input 'LYNX-WS or LYNX schema password' --algorithm 'PBEWITHHMACSHA512ANDAES_256' --passcode $LYNX_ENCRYPT_PASSWORD
  • After reviewing the encrypt script output, you might use copy-paste, a redirection operator, the tail command, etc to output the encrypted password into the config file.
  • Update the LYNX-APP configuration

Encrypt Your Passwords (LYNX-APP 1.2.2 and Older)

Review Jasypt Deployment

Your distribution may have included none, some, or all of the needed Jasypt files. To proceed with the next steps, you will need encrypt.sh and decrypt.sh scripts.

You may need to retrieve the Jasypt package through your package manager or download and install the Jasypt files manually. (See installation instructions below.)

Installing Jasypt

  • Download the Jasypt distribution zip file from jasypt.org.
  • Create a suitable installation target for this application.
  • The most suitable location may depend on best practices for your Linux/Unix Distribution. Example:

    • /usr/local/bin/jasypt/

  • Unzip files from the Jasypt distribution zip to the target directory.

Review Execution Permissions

  • Encryption and decryption of values may be performed through two scripts:
    • encrypt.sh
    • decrypt.sh
  • Consider if you will need to change permissions to allow these scripts to execute. Example:
    • chmod +x encrypt.sh
    • chmod +x decrypt.sh

Encrypt Values

  • Recall the encryption password chosen above.
  • Encrypt your two passwords (Lynx-WS password and SIS DB Lynx schema password) using the encrypt script. Example:
    • ./encrypt.sh input=My-Password-Here password=RADIO_BLUE_LAPTOP algorithm=PBEWITHSHA1ANDDESEDE

After reviewing the encrypt script output, you might use copy-paste, a redirection operator, the tail command, etc to output the encrypted password into the config file.

Update the LYNX-APP Configuration

  • Navigate to ~lynx-app/config
  • Open application.properties for editing
  • Uncomment this line (remove # sign):
    • # jasypt.encryptor.password=${LYNX_ENCRYPT_PASSWORD:}
  • Above that line, add ONE of the following algorithm lines based on your LYNX-APP version
    • Version 1.2.3 and newer:
      jasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256  
    • Version 1.2.2 and older:
      jasypt.encryptor.algorithm=PBEWITHSHA1ANDDESEDE
  • Enter your encoded passwords between the matching set of parentheses:
    • lynx-password=ENC(...)
    • db-password=ENC(...)
    • Example
      • lynx-password=ENC(bzNkV2fEFX7iBchaiq8yUlt7lEeCsO8A)
      • db-password=ENC(KPpYiS5v7EYe2TXz1IEtuvZYejPWOo+G)
  • Comment out the regular password assignment rows by adding a # sign (or remove them entirely)
    • # lynx-password=
    • # db-password=

Test the Encrypted Password

  • Restart the LYNX background process

    • Stop with stopBackground.sh first if necessary
    • Start with runBackground.sh
  • Verify the process is running with a suitable command. Example:
    • ps aux | grep lynx
    • This command might return a line for the grep, as well as a line indicating the application is running ( ...lynx-app.jar ):
user      2494  6.9  8.5 2584496 169848 pts/0  Sl   11:47   0:09 java -jar -Dmode=TEST lynx-app.jar
user      2584  0.0  0.0 119724  1052 pts/0    S+   11:50   0:00 grep --color=auto lynx
  • The LYNX-APP may start correctly, but stop itself if there is an error, such as a network connectivity error. Ensure the process is still running after a few moments.
  • If the LYNX-APP starts correctly and continues to run, verify the LYNX Dashboard web page indicates "APP OK" and no errors are presented. Example:
    • https://lynx.collegenet.com/INSTANCE-NAME
  • If LYNX does not start correctly, check the ~lynx-app/logs/ folder to investigate possible causes.
  • If LYNX is running properly, this process is complete.