public class CryptoToken
extends java.lang.Object
username;expiration_time;[<attr1>;<attr2>;...;<attrN>;]
where
username is a user account name. Defaults to <anonymous> if
not set and it is always converted to lower case as per the rules of the
default locale. (Note this lower case conversion is consistent with the
default reference implementation of ESAPI's User interface.)
name=[value] (value may be empty, but not null)
The attribute value may contain any value. However, values containing
either '=' or ';' will be quoted using '\'. Likewise, values containing '\'
will also be quoted using '\'. Hence if original name/value pair were
name=ab=xy\;
this would be represented as
name=ab\=xy\\\;
To ensure things are "safe" (from a security perspective), attribute
names must conform the the Java regular expression
[A-Za-z0-9_\.-]+
The attribute value on the other hand, may be any valid string. (That
is, the value is not checked, so beware!)
This entire semicolon-separated string is then encrypted via one of the
Encryptor.encrypt() methods and then base64-encoded, serialized
IV + ciphertext + MAC representation as determined by
CipherTextasPortableSerializedByteArray() is used as the
resulting cryptographic token.
The attributes are sorted by attribute name and the attribute names
must be unique. There are some restrictions on the attribute names.
(See the setAttribute(String, String) method for details.)
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
ANONYMOUS_USER
Represents an anonymous user.
|
private static java.lang.String |
ATTR_NAME_REGEX |
private java.util.TreeMap<java.lang.String,java.lang.String> |
attributes |
private java.util.regex.Pattern |
attrNameRegex |
private static long |
DEFAULT_EXP_TIME |
private static java.lang.String |
DELIM |
private static char |
DELIM_CHAR |
private long |
expirationTime |
private static Logger |
logger |
private static char |
QUOTE_CHAR |
private javax.crypto.SecretKey |
secretKey |
private java.lang.String |
username |
private static java.lang.String |
USERNAME_REGEX |
private java.util.regex.Pattern |
userNameRegex |
| Constructor and Description |
|---|
CryptoToken()
Create a cryptographic token using default secret key from the
ESAPI.properties property Encryptor.MasterKey.
|
CryptoToken(javax.crypto.SecretKey skey)
Create a cryptographic token using specified
SecretKey. |
CryptoToken(javax.crypto.SecretKey skey,
java.lang.String token)
Create cryptographic token using previously encrypted token that was
encrypted with specified secret key.
|
CryptoToken(java.lang.String token)
Create using previously encrypted token encrypted with default secret
key from ESAPI.properties.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addAttributes(java.util.Map<java.lang.String,java.lang.String> attrs)
Add the specified collection of attributes to the current attributes.
|
void |
clearAttributes()
Removes all the attributes (if any) associated with this token.
|
private java.lang.String |
createEncryptedToken(javax.crypto.SecretKey skey) |
private void |
decryptToken(javax.crypto.SecretKey skey,
java.lang.String b64token) |
java.lang.String |
getAttribute(java.lang.String name)
Retrieve the attribute with the specified name.
|
java.util.Map<java.lang.String,java.lang.String> |
getAttributes()
Retrieve a
Map that is a clone of all the attributes. |
private javax.crypto.SecretKey |
getDefaultSecretKey(java.lang.String encryptAlgorithm) |
long |
getExpiration()
Return the expiration time in milliseconds since epoch time (midnight,
January 1, 1970 UTC).
|
java.util.Date |
getExpirationDate()
Return the expiration time as a
Date. |
private java.lang.String |
getQuotedAttributes() |
java.lang.String |
getToken()
Return the new encrypted token as a base64-encoded string, encrypted with
the specified
SecretKey with which this object was constructed. |
java.lang.String |
getToken(javax.crypto.SecretKey skey)
Return the new encrypted token as a base64-encoded string, encrypted with
the specified
SecretKey which may be a different key than what the
token was originally encrypted with. |
java.lang.String |
getUserAccountName()
Retrieve the user account name associated with this
CryptoToken
object. |
boolean |
isExpired()
Check if token has expired yet.
|
private static java.lang.String |
parseQuotedValue(java.lang.String quotedValue) |
(package private) static void |
preAdd(long leftLongValue,
int rightIntValue) |
private static java.lang.String |
quoteAttributeValue(java.lang.String value) |
void |
setAttribute(java.lang.String name,
java.lang.String value)
Set a name/value pair as an attribute.
|
void |
setExpiration(java.util.Date expirationDate)
Set expiration time for a specific date/time.
|
void |
setExpiration(int intervalSecs)
Set expiration time to expire in 'interval' seconds (NOT milliseconds).
|
void |
setUserAccountName(java.lang.String userAccountName)
Set the user account name associated with this cryptographic token
object.
|
java.lang.String |
updateToken(int additionalSecs)
Update the (current) expiration time by adding the specified number of
seconds to it and then re-encrypting with the current
SecretKey
that was used to construct this object. |
public static final java.lang.String ANONYMOUS_USER
private static final long DEFAULT_EXP_TIME
private static final java.lang.String DELIM
private static final char DELIM_CHAR
private static final char QUOTE_CHAR
private static final java.lang.String ATTR_NAME_REGEX
private static final java.lang.String USERNAME_REGEX
private static Logger logger
private java.lang.String username
private long expirationTime
private java.util.TreeMap<java.lang.String,java.lang.String> attributes
private transient javax.crypto.SecretKey secretKey
private java.util.regex.Pattern attrNameRegex
private java.util.regex.Pattern userNameRegex
public CryptoToken()
public CryptoToken(javax.crypto.SecretKey skey)
SecretKey.skey - The specified SecretKey to use to encrypt the token.public CryptoToken(java.lang.String token)
throws EncryptionException
token - A previously encrypted token returned by one of the
getToken() or updateToken() methods. The
token must have been previously encrypted using the
using default secret key from the ESAPI.properties
property Encryptor.MasterKey.EncryptionException - Thrown if they are any problems while decrypting
the token using the default secret key from
ESAPI.properties or if the decrypted
token is not properly formatted.public CryptoToken(javax.crypto.SecretKey skey,
java.lang.String token)
throws EncryptionException
token - A previously encrypted token returned by one of the
getToken() or updateToken() methods.EncryptionException - Thrown if they are any problems while decrypting
the token using the default secret key from
ESAPI.properties or if the decrypted
token is not properly formatted.public java.lang.String getUserAccountName()
CryptoToken
object.ANONYMOUS_USER is returned if
setUserAccountName(String) was never called.public void setUserAccountName(java.lang.String userAccountName)
throws ValidationException
userAccountName - The user account name.ValidationException - Thrown if user account name is not valid, i.e.,
if it doesn't conform to the regular expression
given by "[a-z][a-z0-9_.@-]*". (Note that the
parameter userAccountName is first converted
to lower case before checked against the regular
expression.)public boolean isExpired()
public void setExpiration(int intervalSecs)
throws java.lang.IllegalArgumentException
intervalSecs - Number of seconds in the future from current date/time
to set expiration. Must be positive.java.lang.IllegalArgumentExceptionpublic void setExpiration(java.util.Date expirationDate)
throws java.lang.IllegalArgumentException
expirationDate - The date/time at which the token will fail. Must
be after the current date/time.java.lang.IllegalArgumentException - Thrown if the parameter is null.public long getExpiration()
public java.util.Date getExpirationDate()
Date.Date object representing the expiration time.public void setAttribute(java.lang.String name,
java.lang.String value)
throws ValidationException
name - The attribute namevalue - The attribute valueValidationException - Thrown if the attribute name is not properly
formed. That is, the attribute name does not
match the regular expression "[A-Za-z0-9_.-]+".public void addAttributes(java.util.Map<java.lang.String,java.lang.String> attrs)
throws ValidationException
attrs - Name/value pairs of attributes to add or replace the existing
attributes. Map must be non-null, but may be empty.ValidationException - Thrown if one of the keys in the specified
parameter attrs is not a valid name.
That is, all attribute names must match the regular
expression ""[A-Za-z0-9_.-]+".setAttribute(String, String)public java.lang.String getAttribute(java.lang.String name)
name - The attribute name.null is returned.public java.util.Map<java.lang.String,java.lang.String> getAttributes()
Map that is a clone of all the attributes. A copy
is returned so that the attributes in CrytpToken are unaffected
by alterations made the returned Map. (Otherwise, multi-threaded code
could get trick.Map of all the attributes.getAttribute(String)public void clearAttributes()
public java.lang.String getToken(javax.crypto.SecretKey skey)
throws EncryptionException
SecretKey which may be a different key than what the
token was originally encrypted with. E.g.,
Alice:
SecretKey aliceSecretKey = ...; // Shared with Bob
CryptoToken cryptoToken = new CryptoToken(skey1);
cryptoToken.setUserAccountName("kwwall");
cryptoToken.setAttribute("role", "admin");
cryptoToken.setAttribute("state", "Ohio");
String token = cryptoToken.getToken(); // Encrypted with skey1
// send token to Bob ...
--------------------------------------------------------------------
Bob:
...
SecretKey aliceSecretKey = ... // Shared with Alice
SecretKey bobSecretKey = ...; // Shared with Carol
CryptoToken cryptoToken = new CryptoToken(aliceSecretKey, tokenFromAlice);
// Re-encrypt for Carol using my (Bob's) key...
String tokenForCarol = cryptoToken.getToken(bobSecretKey);
// send tokenForCarol to Carol ...
// use token ourselves
--------------------------------------------------------------------
Carol:
...
SecretKey bobSecretKey = ...; // Shared with Bob.
CryptoToken cryptoToken = new CryptoToken(bobSecretKey, tokenFromBob);
if ( ! cryptoToken.isExpired() ) {
String userName = cryptoToken.getUserAccountName();
String roleName = cryptoToken.getAttribute("role");
if ( roleName != null && roleName.equalsIgnoreCase("admin") ) {
// grant admin access...
...
}
}
...
skey - The specified key to (re)encrypt the token.EncryptionExceptionpublic java.lang.String updateToken(int additionalSecs)
throws EncryptionException,
ValidationException
SecretKey
that was used to construct this object.additionalSecs - The additional number of seconds to add to the
current expiration time. This number must be
>= 0 or otherwise an IllegalArgumentException
is thrown.java.lang.IllegalArgumentException - Thrown if parameter additionalSecs
is less than 0.EncryptionException - Thrown if the encryption fails.ValidationException - Thrown if the token will have already expired
even after adding the specified number of
additional seconds.java.lang.ArithmeticException - If additional seconds is large enough such
that it would cause an arithmetic overflow
with a long (the current expiration time)
when added to the additionalSecs
parameter.public java.lang.String getToken()
throws EncryptionException
SecretKey with which this object was constructed.EncryptionExceptiongetToken(SecretKey)private java.lang.String createEncryptedToken(javax.crypto.SecretKey skey)
throws EncryptionException
EncryptionExceptionprivate java.lang.String getQuotedAttributes()
private static java.lang.String quoteAttributeValue(java.lang.String value)
private static java.lang.String parseQuotedValue(java.lang.String quotedValue)
private void decryptToken(javax.crypto.SecretKey skey,
java.lang.String b64token)
throws EncryptionException,
EncodingException
EncryptionExceptionEncodingExceptionprivate javax.crypto.SecretKey getDefaultSecretKey(java.lang.String encryptAlgorithm)
static final void preAdd(long leftLongValue,
int rightIntValue)
throws java.lang.ArithmeticException
java.lang.ArithmeticException