CryptoToken

java.lang.Object
- org.owasp.esapi.crypto.CryptoToken

```
public class CryptoToken
extends java.lang.Object
```
Compute a cryptographically secure, encrypted token containing optional name/value pairs. The cryptographic token is computed like this:
```
     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.)
expiration_time is time (in milliseconds) after which the encrypted token is considered invalid (i.e., expired). The time is stored as milliseconds since midnight, January 1, 1970 UTC, and optional attributes
<attr1>;<attr2>;...<attrN>;
are optional semicolon (';') separated name/value pairs, where each name/value pair has the form:
```
         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.)
Since:

2.0

Field Summary

Fields
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 Summary

Constructors
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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ANONYMOUS_USER
```
public static final java.lang.String ANONYMOUS_USER
```
    Represents an anonymous user.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_EXP_TIME
```
private static final long DEFAULT_EXP_TIME
```
    See Also:
    
    Constant Field Values
  - DELIM
```
private static final java.lang.String DELIM
```
    See Also:
    
    Constant Field Values
  - DELIM_CHAR
```
private static final char DELIM_CHAR
```
    See Also:
    
    Constant Field Values
  - QUOTE_CHAR
```
private static final char QUOTE_CHAR
```
    See Also:
    
    Constant Field Values
  - ATTR_NAME_REGEX
```
private static final java.lang.String ATTR_NAME_REGEX
```
    See Also:
    
    Constant Field Values
  - USERNAME_REGEX
```
private static final java.lang.String USERNAME_REGEX
```
    See Also:
    
    Constant Field Values
  - logger
```
private static Logger logger
```
  - username
```
private java.lang.String username
```
  - expirationTime
```
private long expirationTime
```
  - attributes
```
private java.util.TreeMap<java.lang.String,java.lang.String> attributes
```
  - secretKey
```
private transient javax.crypto.SecretKey secretKey
```
  - attrNameRegex
```
private java.util.regex.Pattern attrNameRegex
```
  - userNameRegex
```
private java.util.regex.Pattern userNameRegex
```
- Constructor Detail
  - CryptoToken
```
public CryptoToken()
```
    Create a cryptographic token using default secret key from the ESAPI.properties property Encryptor.MasterKey.
  - CryptoToken
```
public CryptoToken(javax.crypto.SecretKey skey)
```
    Create a cryptographic token using specified SecretKey.
    
    Parameters:
    
    skey - The specified SecretKey to use to encrypt the token.
  - CryptoToken
```
public CryptoToken(java.lang.String token)
            throws EncryptionException
```
    Create using previously encrypted token encrypted with default secret key from ESAPI.properties.
    
    Parameters:
    
    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.
    
    Throws:
    
    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.
  - CryptoToken
```
public CryptoToken(javax.crypto.SecretKey skey,
                   java.lang.String token)
            throws EncryptionException
```
    Create cryptographic token using previously encrypted token that was encrypted with specified secret key.
    
    Parameters:
    
    token - A previously encrypted token returned by one of the getToken() or updateToken() methods.
    
    Throws:
    
    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.
- Method Detail
  - getUserAccountName
```
public java.lang.String getUserAccountName()
```
    Retrieve the user account name associated with this CryptoToken object.
    
    Returns:
    
    The user account name. The string represented by ANONYMOUS_USER is returned if setUserAccountName(String) was never called.
  - setUserAccountName
```
public void setUserAccountName(java.lang.String userAccountName)
                        throws ValidationException
```
    Set the user account name associated with this cryptographic token object. The user account name is converted to lower case.
    
    Parameters:
    
    userAccountName - The user account name.
    
    Throws:
    
    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.)
  - isExpired
```
public boolean isExpired()
```
    Check if token has expired yet.
    
    Returns:
    
    True if token has expired; false otherwise.
  - setExpiration
```
public void setExpiration(int intervalSecs)
                   throws java.lang.IllegalArgumentException
```
    Set expiration time to expire in 'interval' seconds (NOT milliseconds).
    
    Parameters:
    
    intervalSecs - Number of seconds in the future from current date/time to set expiration. Must be positive.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - setExpiration
```
public void setExpiration(java.util.Date expirationDate)
                   throws java.lang.IllegalArgumentException
```
    Set expiration time for a specific date/time.
    
    Parameters:
    
    expirationDate - The date/time at which the token will fail. Must be after the current date/time.
    
    Throws:
    
    java.lang.IllegalArgumentException - Thrown if the parameter is null.
  - getExpiration
```
public long getExpiration()
```
    Return the expiration time in milliseconds since epoch time (midnight, January 1, 1970 UTC).
    
    Returns:
    
    The current expiration time.
  - getExpirationDate
```
public java.util.Date getExpirationDate()
```
    Return the expiration time as a Date.
    
    Returns:
    
    The Date object representing the expiration time.
  - setAttribute
```
public void setAttribute(java.lang.String name,
                         java.lang.String value)
                  throws ValidationException
```
    Set a name/value pair as an attribute.
    
    Parameters:
    
    name - The attribute name
    
    value - The attribute value
    
    Throws:
    
    ValidationException - Thrown if the attribute name is not properly formed. That is, the attribute name does not match the regular expression "[A-Za-z0-9_.-]+".
  - addAttributes
```
public void addAttributes(java.util.Map<java.lang.String,java.lang.String> attrs)
                   throws ValidationException
```
    Add the specified collection of attributes to the current attributes. If there are duplicate attributes specified, they will replace any existing ones.
    
    Parameters:
    
    attrs - Name/value pairs of attributes to add or replace the existing attributes. Map must be non-null, but may be empty.
    
    Throws:
    
    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_.-]+".
    
    See Also:
    
    setAttribute(String, String)
  - getAttribute
```
public java.lang.String getAttribute(java.lang.String name)
```
    Retrieve the attribute with the specified name.
    
    Parameters:
    
    name - The attribute name.
    
    Returns:
    
    The value associated with the attribute name. If attribute is not set, then null is returned.
  - getAttributes
```
public java.util.Map<java.lang.String,java.lang.String> getAttributes()
```
    Retrieve a 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.
    
    Returns:
    
    A Map of all the attributes.
    
    See Also:
    
    getAttribute(String)
  - clearAttributes
```
public void clearAttributes()
```
    Removes all the attributes (if any) associated with this token. Note that this does not clear / reset the user account name or expiration time.
  - getToken
```
public java.lang.String getToken(javax.crypto.SecretKey skey)
                          throws EncryptionException
```
    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. 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...
              ...
          }
      }
      ...
 
```
    Parameters:
    
    skey - The specified key to (re)encrypt the token.
    
    Returns:
    
    The newly encrypted token.
    
    Throws:
    
    EncryptionException
  - updateToken
```
public java.lang.String updateToken(int additionalSecs)
                             throws EncryptionException,
                                    ValidationException
```
    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.
    
    Parameters:
    
    additionalSecs - The additional number of seconds to add to the current expiration time. This number must be >= 0 or otherwise an IllegalArgumentException is thrown.
    
    Returns:
    
    The re-encrypted token with the updated expiration time is returned.
    
    Throws:
    
    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.
  - getToken
```
public java.lang.String getToken()
                          throws EncryptionException
```
    Return the new encrypted token as a base64-encoded string, encrypted with the specified SecretKey with which this object was constructed.
    
    Returns:
    
    The newly encrypted token.
    
    Throws:
    
    EncryptionException
    
    See Also:
    
    getToken(SecretKey)
  - createEncryptedToken
```
private java.lang.String createEncryptedToken(javax.crypto.SecretKey skey)
                                       throws EncryptionException
```
    Throws:
    
    EncryptionException
  - getQuotedAttributes
```
private java.lang.String getQuotedAttributes()
```
  - quoteAttributeValue
```
private static java.lang.String quoteAttributeValue(java.lang.String value)
```
  - parseQuotedValue
```
private static java.lang.String parseQuotedValue(java.lang.String quotedValue)
```
  - decryptToken
```
private void decryptToken(javax.crypto.SecretKey skey,
                          java.lang.String b64token)
                   throws EncryptionException,
                          EncodingException
```
    Throws:
    
    EncryptionException
    
    EncodingException
  - getDefaultSecretKey
```
private javax.crypto.SecretKey getDefaultSecretKey(java.lang.String encryptAlgorithm)
```
  - preAdd
```
static final void preAdd(long leftLongValue,
                         int rightIntValue)
                  throws java.lang.ArithmeticException
```
    Throws:
    
    java.lang.ArithmeticException

Class CryptoToken

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ANONYMOUS_USER

DEFAULT_EXP_TIME

DELIM

DELIM_CHAR

QUOTE_CHAR

ATTR_NAME_REGEX

USERNAME_REGEX

logger

username

expirationTime

attributes

secretKey

attrNameRegex

userNameRegex

Constructor Detail

CryptoToken

CryptoToken

CryptoToken

CryptoToken

Method Detail

getUserAccountName

setUserAccountName

isExpired

setExpiration

setExpiration

getExpiration

getExpirationDate

setAttribute

addAttributes

getAttribute

getAttributes

clearAttributes

getToken

updateToken

getToken

createEncryptedToken

getQuotedAttributes

quoteAttributeValue

parseQuotedValue

decryptToken

getDefaultSecretKey

preAdd