Frequently Asked Questions (FAQ)

If you have a comment or question then please address it to Alan Moran.

How should I protect my keys ?

You should take all reasonable measures to ensure that others do not gain access to your keys. This includes:

  1. Your keys should be readable only by those who need to access them i.e., the sender and recipient processes. For example on UNIX/Linux systems you should issue a command like: chown myuser.mygroup /path/to/urlsigner.jks
    chmod 400 /path/to/urlsigner.jks
  2. You should employ cryptographically secure passphrases for your keystore and private key e.g., considering generating long passphrases (e.g., 64 characters) using randomly distributed characters. Note that your keystore passphrase provides container level security only and is not used for key generation. If working progammatically with the URL Signer then ensure that all such passphrases are handled as character arrays since it is comparatively simple to extract strings from bytecode thereby revealing your passphrases. The URL signer API will refuse to accept string passphrase arguments for this reason.
  3. You should NOT store your keys on a shared network device (e.g., an NFS volume or a Samba share) as accessing them over a network exposes their contents to eavesdroppers. Equally it is worth adding that your keys should not be transmitted insecurely over a network (e.g., via email.)
  4. You should consider peridocially regenerating your keys and distributing them safely amongst your senders/recipients (e.g., using SSH.) This is merely being prudent.

The default aging policy of 5 minutes is not good for me, what can I do ?

If using the programmatic API then you can create a signature cache by passing the appropriate aging policy (in seconds) to the SignatureCache.getInstance() method. When you do this you force a reassessment of the cache content (e.g., if you reduce the time then the cache contents will be purged of entries that would not be considered expired under the new setting.) Ideally you should set the aging policy before the first verification operation but if you do not then the first verification operation will initiate the creation of a default cache (which you can of course reconfigure yourself at a later point in time.) The longer the aging policy the larger the cache. In heavily loaded environments it may be advisable to monitor the cache (which you can monitor using either toString or size methods of SignatureCache) e.g., using a JMX bean.

When using a proxy the signature is no longer valid

URL Signer will use the base URL (along with the nonce and timestamp) to create a digital signature. If your recipient is fronted by a proxy that tampers with the URL or its parameters in any manner (e.g., re-ordering, removing or adding parameters) then the verification process will fail (as indeed it should!) as it is unable to recreate the original input parameters into the signing operation.

Why do unit tests sometimes take a long time to complete ?

Owing to the manner in which SecureRandom gathers entropy from the underlying system (e.g., using /dev/random on some UNIX/Linux systems) this can take time. Entropy is a crucial aspect of ensuring cryptographic security on deterministic systems (it is used to seed the pseudo random number generator used by SecureRandom) A long running system or some systems (e.g., OpenBSD) often have sufficient inherent entropy for this not to be a problem.

I am getting "HasBeenInstrumented" errors when I try to run URL Signer ?

Most likely you have run the test suite during which Cobertura (an open source test coverage tool) has injected the classes with instrumentation necessary to assess test coverage. To resolve simply issue

ant clean jar