SecureAttrs (OpenAM Server Only 6.5.5 Documentation)

java.lang.Object
- com.sun.identity.sae.api.SecureAttrs

```
public class SecureAttrs
extends Object
```
SecureAttrs class forms the core api of "Secure Attributes Exchange" (SAE) feature. The class uses off the shelf digital signing and encryption algorithms to generate tamperproof/nonrepudiable strings representing attribute maps and to verify these strings. Typical SAE usage is to securely send attributes (authentication & use profile data) from an asserting application (eg running on an IDP) to a relying application (eg running on an SP). In this scenario the asserting party uses the "signing" interfaces to generate secure data and the relying application uses "verification" interfaces to ascertain the authenticity of the data. Current implementation provides two mechanisms to secure attributes : Symmetric : uses simple shared secrets between the two ends. Asymmetric : uses PKI based signing using public-private keys. Freshness is provided by a varying seed generated from the current timestamp and a configurable expiry period within which the relying party must validate the token.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`SAE_CMD_LOGOUT` SAE command `SAE_PARAM_CMD`
`static String`	`SAE_CONFIG_CACHE_KEYS` SAE Config : Flag to indicate whether keys should be cached in memory once retrieved from the keystore.
`static String`	`SAE_CONFIG_DATA_ENCRYPTION_ALG` SAE Config : data encryption algorithm.
`static String`	`SAE_CONFIG_ENCRYPTION_KEY_STRENGTH` SAE Config : data encryption key strength.
`static String`	`SAE_CONFIG_KEYSTORE_FILE` SAE Config : Location of the keystore to access keys from for asymmetric crypto.
`static String`	`SAE_CONFIG_KEYSTORE_PASS` SAE Config : Password to open the keystrore.
`static String`	`SAE_CONFIG_KEYSTORE_TYPE` SAE Config : keystore type.
`static String`	`SAE_CONFIG_PRIVATE_KEY` SAE Config : Private key for asymmetric signing.
`static String`	`SAE_CONFIG_PRIVATE_KEY_ALIAS` SAE Config : Private key alias for asymmetric signing.
`static String`	`SAE_CONFIG_PRIVATE_KEY_PASS` SAE Config : Password to access the private key.
`static String`	`SAE_CONFIG_PUBLIC_KEY_ALIAS` SAE Config : Public key for asymmetric signature verification.
`static String`	`SAE_CONFIG_SHARED_SECRET` SAE Config : shared secret constant - used internally in FM.
`static String`	`SAE_CONFIG_SIG_VALIDITY_DURATION` SAE Config : Signature validity : since timetamp on signature.
`static String`	`SAE_CRYPTO_TYPE` Crypto types supported.
`static String`	`SAE_CRYPTO_TYPE_ASYM` Crypto type : Symmetric : shared secret based trust between parties.
`static String`	`SAE_CRYPTO_TYPE_SYM` Crypto type : Asymmetric : PKI based trust.
`static String`	`SAE_PARAM_APPID` SAE Parameter : Deprecated.
`static String`	`SAE_PARAM_APPRETURN` SAE Parameter used to comunicate to FM where to redirect after a global logout is completed.
`static String`	`SAE_PARAM_APPSLORETURNURL` SAE Parameter used to communicate to SP to return to specified url upon Logout completion.
`static String`	`SAE_PARAM_AUTHLEVEL` SAE Parameter representing the session's authentication level.
`static String`	`SAE_PARAM_CMD` SAE Parameter representing a command.
`static String`	`SAE_PARAM_DATA` HTTP parameter name used to send and receive secure attribute data.
`static String`	`SAE_PARAM_ERROR` SAE Parameter used to comunicate errors.
`static String`	`SAE_PARAM_IDPAPPURL` SAE Parameter used to identify the IDP app (Asserting party) IDP : populates this parameter to identify itself.
`static String`	`SAE_PARAM_SIGN` SAE Parameter internally used by FM for storing signature data.
`static String`	`SAE_PARAM_SPAPPURL` SAE Parameter representing the requested SP app to be invoked.
`static String`	`SAE_PARAM_TS` SAE Parameter internally used by FM for storing token timestamp.
`static String`	`SAE_PARAM_USERID` SAE Parameter representing the authenticated user.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addPublicKey(String pubkeyalias, X509Certificate x509certificate)` This interface allows to register a public key to be used for signature verification.
`String`	`getEncodedString(Map attrs, String secret)` Returns a Base64 encoded string comprising a signed set of attributes.
`String`	`getEncodedString(Map attrs, String secret, String encSecret)` Returns encrypted string for the given attributes.
`static SecureAttrs`	`getInstance(String name)` Returns an instance to perform crypto operations.
`Map`	`getRawAttributesFromEncodedData(String str)` Returns a decoded `Map` of attribute-value pairs.
`Map`	`getRawAttributesFromEncodedData(String str, String encSecret)` Returns a decoded `Map` of attribute-value pairs.
`String`	`getSignedString(Map attrs, String secret)` Returns a String representing data in the attrs argument.
`static void`	`init(Properties properties)` Deprecated. For backward compatability with older releases of this api. Replaced by `SecureAttrs.init(String,String,Properties)`
`static void`	`init(String name, String type, Properties properties)` Initializes a SecureAttrs instance specified by `name`.
`void`	`setPrivateKey(PrivateKey privatekey)` This interface allows to set the private to be used for signing as an alternative to passing down `SAE_CONFIG_PRIVATE_KEY_ALIAS` via `init`.
`boolean`	`verifyAttrs(Map attrs, String token, String secret)` Verifies the authenticity of data the attrs argument based on the token presented.
`Map`	`verifyEncodedString(String str, String secret)` Verifies a Base64 encoded string for authenticity based on the shared secret supplied.
`Map`	`verifyEncodedString(String str, String secret, String encSecret)` Verifies the encrypted data string using encryption secret and shared secret that was used for signing.

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

- Field Detail
  - SAE_PARAM_DATA
```
public static final String SAE_PARAM_DATA
```
    HTTP parameter name used to send and receive secure attribute data. IDP : sends secure attrs in this parameter. SP : receives secure attrs in this parameter.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_CMD
```
public static final String SAE_PARAM_CMD
```
    SAE Parameter representing a command. Currently only "logout" needs to be explicitly provided. SSO is implied. IDP : Uses this parameter to instruct FM to issue a global logout. SP : Receives this parameter from FM.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_USERID
```
public static final String SAE_PARAM_USERID
```
    SAE Parameter representing the authenticated user. IDP : Uses this parameter to send authenticated userid to FM. SP : Receives userid in this parameter.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_AUTHLEVEL
```
public static final String SAE_PARAM_AUTHLEVEL
```
    SAE Parameter representing the session's authentication level. IDP : Uses this parameter to send authentication level to FM. SP : Receives authentication level in this parameter.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_SPAPPURL
```
public static final String SAE_PARAM_SPAPPURL
```
    SAE Parameter representing the requested SP app to be invoked. IDP : populates this parameter with SP side app to be invoked. SP : Not Applicable.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_IDPAPPURL
```
public static final String SAE_PARAM_IDPAPPURL
```
    SAE Parameter used to identify the IDP app (Asserting party) IDP : populates this parameter to identify itself. SP : Not Applicable.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_APPID
```
public static final String SAE_PARAM_APPID
```
    SAE Parameter : Deprecated.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_TS
```
public static final String SAE_PARAM_TS
```
    SAE Parameter internally used by FM for storing token timestamp.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_SIGN
```
public static final String SAE_PARAM_SIGN
```
    SAE Parameter internally used by FM for storing signature data.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_ERROR
```
public static final String SAE_PARAM_ERROR
```
    SAE Parameter used to comunicate errors.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_APPSLORETURNURL
```
public static final String SAE_PARAM_APPSLORETURNURL
```
    SAE Parameter used to communicate to SP to return to specified url upon Logout completion. IDP : Not applicable SP : expected to redirect to the value upon processing logout req.
    
    See Also:
    
    Constant Field Values
  - SAE_PARAM_APPRETURN
```
public static final String SAE_PARAM_APPRETURN
```
    SAE Parameter used to comunicate to FM where to redirect after a global logout is completed. IDP : sends this param as part of logout command. SP : N/A.
    
    See Also:
    
    Constant Field Values
  - SAE_CMD_LOGOUT
```
public static final String SAE_CMD_LOGOUT
```
    SAE command SAE_PARAM_CMD
    
    See Also:
    
    Constant Field Values
  - SAE_CRYPTO_TYPE
```
public static final String SAE_CRYPTO_TYPE
```
    Crypto types supported.
    
    See Also:
    
    Constant Field Values
  - SAE_CRYPTO_TYPE_ASYM
```
public static final String SAE_CRYPTO_TYPE_ASYM
```
    Crypto type : Symmetric : shared secret based trust between parties.
    
    See Also:
    
    Constant Field Values
  - SAE_CRYPTO_TYPE_SYM
```
public static final String SAE_CRYPTO_TYPE_SYM
```
    Crypto type : Asymmetric : PKI based trust.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_KEYSTORE_FILE
```
public static final String SAE_CONFIG_KEYSTORE_FILE
```
    SAE Config : Location of the keystore to access keys from for asymmetric crypto.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_KEYSTORE_TYPE
```
public static final String SAE_CONFIG_KEYSTORE_TYPE
```
    SAE Config : keystore type. Default : JKS
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_KEYSTORE_PASS
```
public static final String SAE_CONFIG_KEYSTORE_PASS
```
    SAE Config : Password to open the keystrore.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_PRIVATE_KEY_ALIAS
```
public static final String SAE_CONFIG_PRIVATE_KEY_ALIAS
```
    SAE Config : Private key alias for asymmetric signing. Alias is used to retrive the key from the keystore.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_PUBLIC_KEY_ALIAS
```
public static final String SAE_CONFIG_PUBLIC_KEY_ALIAS
```
    SAE Config : Public key for asymmetric signature verification. Alias is used to retrive the key from the keystore.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_PRIVATE_KEY
```
public static final String SAE_CONFIG_PRIVATE_KEY
```
    SAE Config : Private key for asymmetric signing.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_PRIVATE_KEY_PASS
```
public static final String SAE_CONFIG_PRIVATE_KEY_PASS
```
    SAE Config : Password to access the private key.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_CACHE_KEYS
```
public static final String SAE_CONFIG_CACHE_KEYS
```
    SAE Config : Flag to indicate whether keys should be cached in memory once retrieved from the keystore.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_SHARED_SECRET
```
public static final String SAE_CONFIG_SHARED_SECRET
```
    SAE Config : shared secret constant - used internally in FM.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_DATA_ENCRYPTION_ALG
```
public static final String SAE_CONFIG_DATA_ENCRYPTION_ALG
```
    SAE Config : data encryption algorithm.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_ENCRYPTION_KEY_STRENGTH
```
public static final String SAE_CONFIG_ENCRYPTION_KEY_STRENGTH
```
    SAE Config : data encryption key strength.
    
    See Also:
    
    Constant Field Values
  - SAE_CONFIG_SIG_VALIDITY_DURATION
```
public static final String SAE_CONFIG_SIG_VALIDITY_DURATION
```
    SAE Config : Signature validity : since timetamp on signature.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getInstance
```
public static SecureAttrs getInstance(String name)
```
    Returns an instance to perform crypto operations.
    
    Parameters:
    
    name - The name of the instance to return.
    
    Returns:
    
    SecureAttrs instance.
  - init
```
public static void init(String name,
                        String type,
                        Properties properties)
                 throws Exception
```
    Initializes a SecureAttrs instance specified by name. If the instance already exists, it replaces it with the new instance. Use SecureAttrs.getIstance(name) to obtain the instance.
    
    Parameters:
    
    name - Name of the SecureAttrs instance.
    
    type - Cryptographic key type. Possible values are SecureAttrs.SAE_CRYPTO_TYPE_SYM, and SecureAttrs.SAE_CRYPTO_TYPE_ASYM
    
    properties - : please see SAE_CONFIG_* constants for configurable values.
    
    Throws:
    
    Exception - rethrows underlying exception.
  - init
```
public static void init(Properties properties)
                 throws Exception
```
    Deprecated. For backward compatability with older releases of this api. Replaced by SecureAttrs.init(String,String,Properties)
    
    Creates two instances of SecureAttrs named "symmetric" and "asymmetric" representing the two suppported crytp types.
    
    Parameters:
    
    properties - : please see SAE_CONFIG_* constants for configurable values.
    
    Throws:
    
    Exception - rethrows underlying exception.
  - getEncodedString
```
public String getEncodedString(Map attrs,
                               String secret)
                        throws Exception
```
    Returns a Base64 encoded string comprising a signed set of attributes.
    
    Parameters:
    
    attrs - Attribute Value pairs to be processed.
    
    secret - Shared secret (symmetric) Private key alias (asymmetric)
    
    Returns:
    
    Base64 encoded token String to be passed to a relying party.
    
    Throws:
    
    Exception
  - getEncodedString
```
public String getEncodedString(Map attrs,
                               String secret,
                               String encSecret)
                        throws Exception
```
    Returns encrypted string for the given attributes. The encrypted data is Base64 encoded string encrypted with supplied encryption secret and signs using shared secret.
    
    Parameters:
    
    attrs - Attribute Value pairs to be processed.
    
    secret - Shared secret (symmetric) Private key alias (asymmetric) * @param encSecret The encryption secret (symmetric) or Public Key alias (asymmetric)
    
    Returns:
    
    Base64 encoded token String to be passed to a relying party.
    
    Throws:
    
    Exception
  - verifyEncodedString
```
public Map verifyEncodedString(String str,
                               String secret)
                        throws Exception
```
    Verifies a Base64 encoded string for authenticity based on the shared secret supplied.
    
    Parameters:
    
    str - Base64 encoded string containing attribute
    
    secret - Shared secret (symmmetric) or Public Key (asymmetric)
    
    Returns:
    
    Decoded, verified and parsed attrbute name-valie pairs.
    
    Throws:
    
    Exception
  - verifyEncodedString
```
public Map verifyEncodedString(String str,
                               String secret,
                               String encSecret)
                        throws Exception
```
    Verifies the encrypted data string using encryption secret and shared secret that was used for signing.
    
    Parameters:
    
    str - Base64 encoded string containing attribute
    
    secret - Shared secret (symmmetric) or Public Key (asymmetric)
    
    encSecret - The encryption secret (symmetric) or Public Key alias (asymmetric)
    
    Returns:
    
    Decoded, verified and parsed attrbute name-valie pairs.
    
    Throws:
    
    Exception
  - getRawAttributesFromEncodedData
```
public Map getRawAttributesFromEncodedData(String str)
                                    throws Exception
```
    Returns a decoded Map of attribute-value pairs. No verification is performed. Useful when retrieving data before verifying contents for authenticity.
    
    Parameters:
    
    str - Base64 encoded string containing attribute
    
    Returns:
    
    Decoded and parsed attrbute name-value pairs.
    
    Throws:
    
    Exception
  - getRawAttributesFromEncodedData
```
public Map getRawAttributesFromEncodedData(String str,
                                           String encSecret)
                                    throws Exception
```
    Returns a decoded Map of attribute-value pairs. No verification is performed. Useful when retrieving data before verifying contents for authenticity.
    
    Parameters:
    
    str - Base64 encoded string containing attribute
    
    encSecret - The encryption secret (symmetric) or Public Key alias (asymmetric)
    
    Returns:
    
    Decoded and parsed attrbute name-value pairs.
    
    Throws:
    
    Exception
  - setPrivateKey
```
public void setPrivateKey(PrivateKey privatekey)
```
    This interface allows to set the private to be used for signing as an alternative to passing down SAE_CONFIG_PRIVATE_KEY_ALIAS via init. Use this interface if you do not want SecureAttr to obtain the signing key from a configured keystore. To use this key during signing, specify secret as null.
    
    Parameters:
    
    privatekey - The private key.
  - addPublicKey
```
public void addPublicKey(String pubkeyalias,
                         X509Certificate x509certificate)
```
    This interface allows to register a public key to be used for signature verification. Use this interface if you do not want SecureAttrs to obtain public keys from a configured keystore.
    
    Parameters:
    
    pubkeyalias - The public key alias.
    
    x509certificate - instance.
  - getSignedString
```
public String getSignedString(Map attrs,
                              String secret)
                       throws Exception
```
    Returns a String representing data in the attrs argument. The String generated can be one of the following depending on configuration : SHA1 digest based on a shared secret and current timestamp. or Digital signature based on a configured certificate key.
    
    Parameters:
    
    attrs - List of attribute Value pairs to be processed.
    
    secret - Shared secret (symmmetric) or Private Key (asymmetric)
    
    Returns:
    
    token String to be passed to a relying party.
    
    Throws:
    
    Exception
  - verifyAttrs
```
public boolean verifyAttrs(Map attrs,
                           String token,
                           String secret)
                    throws Exception
```
    Verifies the authenticity of data the attrs argument based on the token presented. Both attrs and token is sent by a asserting party.
    
    Parameters:
    
    attrs - List of attribute Value pairs to be processed.
    
    token - token represnting attrs provided by asserting party.
    
    secret - Shared secret (symmmetric) or Public Key (asymmetric)
    
    Returns:
    
    true if attrs and token verify okay, else returns false.
    
    Throws:
    
    Exception

Class SecureAttrs

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SAE_PARAM_DATA

SAE_PARAM_CMD

SAE_PARAM_USERID

SAE_PARAM_AUTHLEVEL

SAE_PARAM_SPAPPURL

SAE_PARAM_IDPAPPURL

SAE_PARAM_APPID

SAE_PARAM_TS

SAE_PARAM_SIGN

SAE_PARAM_ERROR

SAE_PARAM_APPSLORETURNURL

SAE_PARAM_APPRETURN

SAE_CMD_LOGOUT

SAE_CRYPTO_TYPE

SAE_CRYPTO_TYPE_ASYM

SAE_CRYPTO_TYPE_SYM

SAE_CONFIG_KEYSTORE_FILE

SAE_CONFIG_KEYSTORE_TYPE

SAE_CONFIG_KEYSTORE_PASS

SAE_CONFIG_PRIVATE_KEY_ALIAS

SAE_CONFIG_PUBLIC_KEY_ALIAS

SAE_CONFIG_PRIVATE_KEY

SAE_CONFIG_PRIVATE_KEY_PASS

SAE_CONFIG_CACHE_KEYS

SAE_CONFIG_SHARED_SECRET

SAE_CONFIG_DATA_ENCRYPTION_ALG

SAE_CONFIG_ENCRYPTION_KEY_STRENGTH

SAE_CONFIG_SIG_VALIDITY_DURATION

Method Detail

getInstance

init

init

getEncodedString

getEncodedString

verifyEncodedString

verifyEncodedString

getRawAttributesFromEncodedData

getRawAttributesFromEncodedData

setPrivateKey

addPublicKey

getSignedString

verifyAttrs