com.sun.identity.sae.api
Class SecureAttrs

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

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_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

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.
static SecureAttrs	getInstance(String name) Returns an instance to perform crypto operations.
Map	getRawAttributesFromEncodedData(String str) 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.

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_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 -

Returns:

SecureAttrs instance.

init

public static void init(String name,
                        String type,
                        Properties properties)

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:

properties - : please see SAE_CONFIG_* constants for configurable values.

Throws:

Exception - rethrows underlying exception.

init

public static void init(Properties properties)

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)

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.

verifyEncodedString

public Map verifyEncodedString(String str,
                               String secret)

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.

getRawAttributesFromEncodedData

public Map getRawAttributesFromEncodedData(String str)

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.

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 -

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 -

x509certificate - instance.

getSignedString

public String getSignedString(Map attrs,
                              String secret)

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.

verifyAttrs

public boolean verifyAttrs(Map attrs,
                           String token,
                           String secret)

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.