net.degreedays.api

Class SecurityKey

java.lang.Object

net.degreedays.api.SecurityKey

public final class SecurityKey
extends java.lang.Object

The longer of the two access keys that are needed to use the Degree Days.net API.

Each API account has two access keys: an account key and a security key. The security key is a private key that should be kept secret. In this respect it is like a password. The only entities that should have access to the security key are: Degree Days.net (systems and staff), the API account holder(s), and any trusted software systems that the API account holder(s) are using to manage their interactions with the API.

Here's an example of a security key:

b79h-tmgg-dwv5-cgxq-j5k9-n34w-mvxv-b5be-kqp5-b6hb-3bey-h5gg-swwd

Like the example above, all security keys are made up of thirteen 4-character blocks separated by hyphens, with each non-hyphen character being one of the following:

abcdefghjkmnpqrstuvwxyz23456789

Security keys do not contain upper-case characters or any of the following easily-confused letters and digits: 'i', 'l', 'o', '0' and '1'. The same is true of account keys (the other type of access key). The intention is to make these keys easy for non-technical users to handle (e.g. if entering them into software that you've made for them).

A SecurityKey object is a wrapper around the characters that constitute a string security key. It is useful for validating security keys from user input, since the constructors will only allow a SecurityKey object to be created with a string of the correct format or a string that can be manipulated into the correct format without too much ambiguity.

See Also:

Access keys, AccountKey

Constructor Summary

Constructors

Constructor and Description
SecurityKey(char[] securityKeyChars) Constructs a SecurityKey object using the specified characters, or throws an IllegalArgumentException if the characters are clearly invalid.
SecurityKey(java.lang.String stringSecurityKey) Constructs a SecurityKey object using the specified string security key or throws an IllegalArgumentException if the string is clearly invalid.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears all information stored internally to reduce the chances of a representation of the underlying security key remaining in memory.
boolean	equals(java.lang.Object o) A SecurityKey object can only be equal to a SecurityKey object based around the same canonical security key.
byte[]	getBytes() Returns a new, non-null byte array containing the canonical security key's characters encoded into bytes using the UTF-8 character set.
int	hashCode() Overridden to ensure consistency with equals.
java.lang.String	toString() Returns a non-null, non-empty string indicating that this is a SecurityKey object, but not giving any indication as to what the security key actually is.
java.lang.String	toStringKey() Returns the non-null, non-empty, canonical string security key.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SecurityKey

public SecurityKey(java.lang.String stringSecurityKey)
            throws java.lang.IllegalArgumentException

Constructs a SecurityKey object using the specified string security key or throws an IllegalArgumentException if the string is clearly invalid.

This is somewhat tolerant of imperfect user input. It will try to intelligently handle upper-case letters, white space, and missing or non-hyphen block separators. If you're storing or displaying a string key that a user has entered, make sure to use the string returned by toStringKey(), as that will be the corrected key in its canonical form.

Parameters:

stringSecurityKey - a Degree Days.net API security key.

Throws:

java.lang.NullPointerException - if stringSecurityKey is null.

java.lang.IllegalArgumentException - if stringSecurityKey cannot reasonably be parsed as a Degree Days.net API security key (see these notes for a description of the correct format).

SecurityKey

public SecurityKey(char[] securityKeyChars)
            throws java.lang.IllegalArgumentException

Constructs a SecurityKey object using the specified characters, or throws an IllegalArgumentException if the characters are clearly invalid.

This is somewhat tolerant of imperfect user input. See the other constructor's documentation for more on that.

This constructor makes it possible to prevent the security key from existing in memory as a String. The Java Cryptography Architecture (JCA) Reference Guide for Java 6 states the following: "Objects of type String are immutable, i.e., there are no methods defined that allow you to change (overwrite) or zero out the contents of a String after usage. This feature makes String objects unsuitable for storing security sensitive information such as user passwords. You should always collect and store security sensitive information in a char array instead." Also see this blog post for a more detailed explanation.

Whether this guidance actually applies in modern JVMs is debatable but we included this constructor to give you the option of avoiding strings for the security key if you think it makes sense for your application. A SecurityKey object will not create or store a string unless you call the toStringKey() method.

To use this method of construction effectively, we suggest you do something like the following:

1. Pass your character array into this constructor to create a SecurityKey object. Note that doing like "xxxx-xxxx-x...".toCharArray() or alreadyCreatedString.toCharArray() defeats the purpose of using this constructor - if you're doing that you may as well use the simpler constructor that takes a String directly.
2. Pass the SecurityKey object into the constructor of DegreeDaysApi - that will retrieve all the security-key information it needs from a single call to getBytes() that it will make as part of its initialization process.
3. Clear your character array (e.g. java.util.Arrays.fill(chars, '0');).
4. Call clear() on the SecurityKey object.
5. Continue using the DegreeDaysApi object as usual.

Parameters:

securityKeyChars - the characters of a Degree Days.net API security key.

Throws:

java.lang.NullPointerException - if securityKeyChars is null.

java.lang.IllegalArgumentException - if securityKeyChars cannot reasonably be parsed as a Degree Days.net API security key (see these notes for a description of the correct format).

See Also:

SecurityKey(String)

Method Detail

getBytes

public byte[] getBytes()

Returns a new, non-null byte array containing the canonical security key's characters encoded into bytes using the UTF-8 character set.

Throws:

java.lang.IllegalStateException - if clear() has previously been called on this SecurityKey object.

toStringKey

public java.lang.String toStringKey()

Returns the non-null, non-empty, canonical string security key. Take care to ensure that the returned string doesn't accidentally appear in log files or error messages.

Throws:

java.lang.IllegalStateException - if clear() has previously been called on this SecurityKey object.

toString

public java.lang.String toString()

Returns a non-null, non-empty string indicating that this is a SecurityKey object, but not giving any indication as to what the security key actually is. This is to reduce the chances of the security key appearing accidentally in log files and the like.

If you do need to display the security key as a string, you can call toStringKey().

Overrides:

toString in class java.lang.Object

clear

public void clear()

Clears all information stored internally to reduce the chances of a representation of the underlying security key remaining in memory.

See Also:

SecurityKey(char[])

equals

public boolean equals(java.lang.Object o)

A SecurityKey object can only be equal to a SecurityKey object based around the same canonical security key. Equality is not affected by the choice of constructors used to create the SecurityKey objects - it's only the underlying canonical security keys that matter.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object