Package com.sun.identity.sae.api

Class 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 Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • SAE_CONFIG_ENCRYPTION_KEY_STRENGTH

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

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

        @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