GreenArrow Email Software Documentation

Secret Constants

GreenArrow has internal secret constants, unique to each specific server, used to prevent tampering of click/open/unsubscribe links and some bounce messages. These constants are applied to both SimpleMH and GreenArrow Studio emails.

This is done by taking a cryptographic hash of the secret constants and the data we want to secure, which is then included with the secured data. When GreenArrow receives the data back (for example, when a link is clicked), it checks that the data received produces the same cryptographic hash.

These secret constants can be managed with greenarrow_config.

View the current secret constants

The secret constants may be reviewed with the following command.

$ greenarrow_config secret_constants --view
The secret constants are:
  Constant 1: 198b3e2d817809df2956df3b9893e92a
  Constant 2: 969f72759f8cab72f5de6e589e00d3ab

Generate new, random secret constants

New secret constants can be generated using the following command.

This procedure will re-generate the secret constants in GreenArrow. This will cause all existing click URLs, open URLs, and unsubscribe URLs to become INVALID!

$ greenarrow_config secret_constants --make-new-random
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
This procedure will re-generate the secret constants in GreenArrow.
This will cause all existing click URLs, open URLs, and unsubscribe
URLs to become INVALID!
This procedure should NOT be run on any existing installations,
unless you are ABSOLUTELY SURE what you are doing!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
waiting for 5 seconds to give you a chance to reconsider...
Are you sure you want to do this? Please type YES if you are sure: YES
The old secret constants were:
  Constant 1: 198b3e2d817809df2956df3b9893e92a
  Constant 2: 969f72759f8cab72f5de6e589e00d3ab
The secret constants have been updated to be:
  Constant 1: 8e2a1552ba5bdb19319d484de6955682
  Constant 2: 6cb336c0402ae6db6f21cc2c65154128

Apply specific secret constants, without confirmation

The --force command can be applied to skip the confirmation step required in the example above. In this case, we’re applying specific constants to this server.

If the secret constants are changed, this will cause all existing click URLs, open URLs, and unsubscribe URLs to become INVALID!

$ greenarrow_config secret_constants --constant1=66b9fb692db5cc4a1aa9313f7e9e9b6d --constant2=66b9fb692db5cc4a1aa9313f7e9e9b6d --force
make: Nothing to be done for `all'.
The old secret constants were:
  Constant 1: 8e2a1552ba5bdb19319d484de6955682
  Constant 2: 6cb336c0402ae6db6f21cc2c65154128
The secret constants have been updated to be:
  Constant 1: 66b9fb692db5cc4a1aa9313f7e9e9b6d
  Constant 2: 66b9fb692db5cc4a1aa9313f7e9e9b6d

Correct a mistake or see the old secret constants

When updating the secret constants, GreenArrow will write a log to /var/hvmail/var/secret_constants.log.

$ cat /var/hvmail/var/secret_constants.log
2018-11-05 13:43:35 Updating constants from [66b9fb692db5cc4a1aa9313f7e9e9b6d, 66b9fb692db5cc4a1aa9313f7e9e9b6d] to [38982624352666f2b5b35e7a595cc054, 00fcf1383d84473af2fecbcd929fb2be].
2018-11-05 13:43:36 Updating constants from [38982624352666f2b5b35e7a595cc054, 00fcf1383d84473af2fecbcd929fb2be] to [7a42101a18c167932283e36720e852f9, 7081f108ab0e78e0a9d2cca9fa2f32d2].
2018-11-05 13:43:38 Updating constants from [7a42101a18c167932283e36720e852f9, 7081f108ab0e78e0a9d2cca9fa2f32d2] to [bd839126972d1b3db78e155148a3097a, 168fa684cef070eb02913cf74d0ae6bb].
2018-11-05 13:43:47 Updating constants from [bd839126972d1b3db78e155148a3097a, 168fa684cef070eb02913cf74d0ae6bb] to [198b3e2d817809df2956df3b9893e92a, 969f72759f8cab72f5de6e589e00d3ab].
2018-11-05 13:50:57 Updating constants from [198b3e2d817809df2956df3b9893e92a, 969f72759f8cab72f5de6e589e00d3ab] to [8e2a1552ba5bdb19319d484de6955682, 6cb336c0402ae6db6f21cc2c65154128].
2018-11-05 13:51:48 Updating constants from [8e2a1552ba5bdb19319d484de6955682, 6cb336c0402ae6db6f21cc2c65154128] to [66b9fb692db5cc4a1aa9313f7e9e9b6d, 66b9fb692db5cc4a1aa9313f7e9e9b6d].

This provides a record of past secret constants in case a reversion is required.