Package com.sun.identity.sae.api

Class SecureAttrs

java.lang.Object
com.sun.identity.sae.api.SecureAttrs
@Supported 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 Details

    • SAE_PARAM_DATA

      @Supported 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:

    • SAE_PARAM_CMD

      @Supported 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:

    • SAE_PARAM_USERID

      @Supported 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:

    • SAE_PARAM_AUTHLEVEL

      @Supported 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:

    • SAE_PARAM_SPAPPURL

      @Supported 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:

    • SAE_PARAM_IDPAPPURL

      @Supported 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:

    • SAE_PARAM_TS

      @Supported public static final String SAE_PARAM_TS
      SAE Parameter internally used by FM for storing token timestamp.
      See Also:

    • SAE_PARAM_SIGN

      @Supported public static final String SAE_PARAM_SIGN
      SAE Parameter internally used by FM for storing signature data.
      See Also:

    • SAE_PARAM_ERROR

      @Supported public static final String SAE_PARAM_ERROR
      SAE Parameter used to comunicate errors.
      See Also:

    • SAE_PARAM_APPSLORETURNURL

      @Supported 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:

    • SAE_PARAM_APPRETURN

      @Supported 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:

    • SAE_CMD_LOGOUT

      @Supported public static final String SAE_CMD_LOGOUT
      SAE command SAE_PARAM_CMD
      See Also:

    • SAE_CRYPTO_TYPE

      @Supported public static final String SAE_CRYPTO_TYPE
      Crypto types supported.
      See Also:

    • SAE_CRYPTO_TYPE_ASYM

      @Supported public static final String SAE_CRYPTO_TYPE_ASYM
      Crypto type : Symmetric : shared secret based trust between parties.
      See Also:

    • SAE_CRYPTO_TYPE_SYM

      @Supported public static final String SAE_CRYPTO_TYPE_SYM
      Crypto type : Asymmetric : PKI based trust.
      See Also:

    • SAE_CONFIG_KEYSTORE_FILE

      @Supported public static final String SAE_CONFIG_KEYSTORE_FILE
      SAE Config : Location of the keystore to access keys from for asymmetric crypto.
      See Also:

    • SAE_CONFIG_KEYSTORE_TYPE

      @Supported public static final String SAE_CONFIG_KEYSTORE_TYPE
      SAE Config : keystore type. Default : JKS
      See Also:

    • SAE_CONFIG_KEYSTORE_PASS

      @Supported public static final String SAE_CONFIG_KEYSTORE_PASS
      SAE Config : Password to open the keystrore.
      See Also:

    • SAE_CONFIG_PRIVATE_KEY_ALIAS

      @Supported 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:

    • SAE_CONFIG_PUBLIC_KEY_ALIAS

      @Supported 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:

    • SAE_CONFIG_PRIVATE_KEY

      @Supported public static final String SAE_CONFIG_PRIVATE_KEY
      SAE Config : Private key for asymmetric signing.
      See Also:

    • SAE_CONFIG_PRIVATE_KEY_PASS

      @Supported public static final String SAE_CONFIG_PRIVATE_KEY_PASS
      SAE Config : Password to access the private key.
      See Also:

    • SAE_CONFIG_CACHE_KEYS

      @Supported 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:

    • SAE_CONFIG_SHARED_SECRET

      @Supported public static final String SAE_CONFIG_SHARED_SECRET
      SAE Config : shared secret constant - used internally in FM.
      See Also:

    • SAE_CONFIG_DATA_ENCRYPTION_ALG

      @Supported public static final String SAE_CONFIG_DATA_ENCRYPTION_ALG
      SAE Config : data encryption algorithm.
      See Also:

    • SAE_CONFIG_ENCRYPTION_KEY_STRENGTH

      @Supported public static final String SAE_CONFIG_ENCRYPTION_KEY_STRENGTH
      SAE Config : data encryption key strength.
      See Also:

    • SAE_CONFIG_SIG_VALIDITY_DURATION

      @Supported public static final String SAE_CONFIG_SIG_VALIDITY_DURATION
      SAE Config : Signature validity : since timetamp on signature.
      See Also:

  • Method Details

    • getInstance

      @Supported 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

      @Supported 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

      @Supported public static void init(Properties properties) throws Exception
      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

      @Supported public String getEncodedString(Map<String,String> 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

      @Supported public String getEncodedString(Map<String,String> 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)
      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

      @Supported public Map<String,String> 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

      @Supported public Map<String,String> 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

      @Supported public Map<String,String> 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.

    • getRawAttributesFromEncodedData

      @Supported public Map<String,String> 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

      @Supported 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

      @Supported 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

      @Supported public String getSignedString(Map<String,String> 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

      @Supported public boolean verifyAttrs(Map<String,String> 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