com.entrust.toolkit.roaming

Class RoamingUser

java.lang.Object

com.entrust.toolkit.roaming.RoamingUser

public final class RoamingUser
extends java.lang.Object

The RoamingUser class provides utility APIs for communication with an Entrust Authority Roaming Server to retrieve a roaming profile, to create/recover a roaming user, update a roaming profile, and deregister a roaming profile.

Note

Only the login and version query operations are supported for versions of Entrust Authority Roaming Server earlier than Release 6.0.

The RoamingCredentialReader and RoamingCredentialWriter objects can be used with a User object to perform almost all functions performed by this class.

See Also:

RoamingCredentialReader, RoamingCredentialWriter, User

Constructor Summary

Constructors

Constructor and Description
RoamingUser(java.lang.String iniFileName) Creates an instance of RoamingUser

Method Summary

Methods

Modifier and Type	Method and Description
void	changePassword(SecureStringBuffer oldPassword, SecureStringBuffer newPassword) Deprecated. As of 7.0, use User.changePassword() with a RoamingCredentialWriter object set to perform this task.
void	create(java.lang.String userId, SecureStringBuffer password, CredentialCreator creator) Deprecated. As of 7.0, use a CredentialCreator with a RoamingCredentialWriter object to perform this task.
void	deregister() Deprecated. as of 7.0, the method RoamingCredentialReader.deregister() should be used to perform this function.
void	enableSSLLog(boolean enable) Enables SSL log.
boolean	encryptionKeyUpdateRequired() Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object for key management tasks.
byte[]	getProfile() Returns the user's profile as a byte array.
EntrustFiles	getRequestedFiles() Returns an EntrustFiles object from Roaming Server during the login operation.
byte[]	getServerVersion(java.lang.String userid) Retrieves the latest version of Roaming supported by the Roaming Server.
boolean	isLoggedIn() Determines whether or not the user is logged in.
int	login(java.lang.String userid, SecureStringBuffer password) Deprecated. as of 7.0, RoamingCredentialReader and RoamingCredentialWriter should be used with a User object to perform this function.
void	logout() Logs out the user and deletes all user-specific information.
void	recover(java.lang.String userId, SecureStringBuffer password, CredentialRecoverer recoverer) Deprecated. As of 7.0, use a CredentialRecoverer with a RoamingCredentialWriter object to perform this task.
void	register(java.lang.String profilePath, java.lang.String roamingUserID, SecureStringBuffer password) Registers a user.
boolean	signingKeyUpdateRequired() Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object for key management tasks.
boolean	sslLogEnabled() Returns the SSL log mode.
void	update(EntrustFiles files) Updates the user's files in the Directory, or places them in the Directory if they do not already exist.
void	updateAnother(java.lang.String subjectDN, EntrustFiles files) Updates another User's files in the Directory, or places them in the Directory if they do not already exist.
boolean	updateEncryptionKeys() Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object, and let the User perform key management automtically.
boolean	updateSigningKeys() Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object, and let the User perform key management automtically.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RoamingUser

public RoamingUser(java.lang.String iniFileName)
            throws RoamingException,
                   java.io.FileNotFoundException,
                   UserFatalException

Creates an instance of RoamingUser

Parameters:

iniFileName - the location of the entrust.ini file

Throws:

java.io.FileNotFoundException - if iniFileName is not found

UserFatalException - if connections to the PKI or directory failed

RoamingException - if any required settings are missing from the entrust.ini file.

Method Detail

getServerVersion

public byte[] getServerVersion(java.lang.String userid)
                        throws RoamingException,
                               java.io.IOException

Retrieves the latest version of Roaming supported by the Roaming Server.

The login method does not have to be called before calling this method.

Note

The Toolkit supports Entrust Authority Roaming Server Release 6.0 only.

Parameters:

userid - the Roaming ID of the user performing the request.

Returns:

the roaming version as a byte array

• 0x0100 for 5.0 Roaming Server
• 0x0000 for 5.1 Roaming Server
• 0x0002 for 6.0 Roaming Server

Throws:

java.io.IOException - if the query failed due to any communication problem

RoamingException - if the query operation failed for any other reason.

login

public int login(java.lang.String userid,
        SecureStringBuffer password)
          throws RoamingException,
                 java.io.IOException,
                 java.security.cert.CertificateException,
                 UserBadPasswordException,
                 UserFatalException,
                 UserCertificateRevokedException

Deprecated. as of 7.0, RoamingCredentialReader and RoamingCredentialWriter should be used with a User object to perform this function.

Performs Roaming login.

The method performs the following steps:

1. Retrieves the user profile from either the Directory or Roaming Server
2. Decrypts the profile key
3. Decrypts the profile

Parameters:

userid - the user's login ID

password - the user's password

Returns:

returns the login status code. See User.login(com.entrust.toolkit.credentials.CredentialReader, com.entrust.toolkit.util.SecureStringBuffer) for details.

Throws:

java.io.IOException - if the communication with the Roaming Server failed;

java.security.cert.CertificateException - if the user has an invalid certifucate;

UserBadPasswordException - if the password is not correct;

UserFatalException - if the user failed to login;

UserCertificateRevokedException - if the user's certificate has been revoked;

RoamingException - if the operation failed to retrieve the user's profile from the Roaming Server.

getProfile

public byte[] getProfile()
                  throws UserNotLoggedInException

Returns the user's profile as a byte array.

Note

To obtain the profile as a String, use this construction:

    new String( roamingUser.getProfile() )

Returns:

The user Profile retrieved from the RoamingServer instance as a byte array.

Throws:

UserNotLoggedInException - if the use is not logged in.

logout

public void logout()
            throws UserNotLoggedInException

Logs out the user and deletes all user-specific information.

Throws:

UserNotLoggedInException - if the user is not logged in.

register

public void register(java.lang.String profilePath,
            java.lang.String roamingUserID,
            SecureStringBuffer password)
              throws UserCertificateRevokedException,
                     UserFatalException,
                     UserBadPasswordException,
                     RoamingException,
                     java.io.IOException

Registers a user.

The registration operation logs in the user before moving the user's supporting files to the Roaming Server. These files include ".epf", ".pab", ".erl", ".sla", ".ckl", ".eao", and ".cpb" files. It's application's responsibility to remove these files after the operation.

The method assumes that all the supporting files are located in the same directory as the user's profile.

Parameters:

profilePath - the path to the user's profile.

roamingUserID - the Roaming ID of the user to be registered.

password - the user's password.

Throws:

UserCertificateRevokedException - if the user's certificate has been revoked;

UserFatalException - if the user failed to login the profile;

UserBadPasswordException - if the password is not valid;

RoamingException - if the roaming registration failed;

java.io.IOException - if the operation failed due to the communication problem.

deregister

public void deregister()
                throws UserNotLoggedInException,
                       RoamingException,
                       java.io.IOException

Deprecated. as of 7.0, the method RoamingCredentialReader.deregister() should be used to perform this function.

Requests the Roaming Server remove all of the User's roaming files from the Directory.

Throws:

RoamingException - if removal of the user's roaming files failed.

java.io.IOException - if the operation failed due to any communication problem.

UserNotLoggedInException - if the user is not logged in.

See Also:

RoamingCredentialReader.deregister()

create

public void create(java.lang.String userId,
          SecureStringBuffer password,
          CredentialCreator creator)
            throws RoamingException,
                   java.io.IOException,
                   UserBadPasswordException,
                   UserFatalException,
                   UserCertificateRevokedException,
                   java.security.cert.CertificateException,
                   java.security.KeyException

Deprecated. As of 7.0, use a CredentialCreator with a RoamingCredentialWriter object to perform this task.

Creates and registers a Roaming user.

Parameters:

userId - the ID of the new Roaming user.

password - the password of the new Roaming user.

creator - the credential creator used to create the user.

Note

Use the RSA signing algorithm to instantiate the credential creator. The current Roaming Server SSL connection supports only the RSA signing algorithm.

Throws:

RoamingException - if the roaming protocol failed;

java.io.IOException - if the communication connection failed;

UserBadPasswordException - if the password is incorrect or invalid;

UserFatalException - if user creation failed;

UserCertificateRevokedException

java.security.cert.CertificateException

java.security.KeyException

See Also:

RoamingCredentialWriter

recover

public void recover(java.lang.String userId,
           SecureStringBuffer password,
           CredentialRecoverer recoverer)
             throws RoamingException,
                    java.io.IOException,
                    UserBadPasswordException,
                    UserFatalException,
                    UserCertificateRevokedException,
                    java.security.cert.CertificateException,
                    java.security.KeyException

Deprecated. As of 7.0, use a CredentialRecoverer with a RoamingCredentialWriter object to perform this task.

Recovers and updates a Roaming user.

Parameters:

userId - the ID of the Roaming user to be recovered.

password - the Roaming user's password.

recoverer - the credential recoverer used to recover the user.

Note

Use the RSA signing algorithm to instantiate the credential recoverer. The current Roaming Server SSL connection supports only the RSA signing algorithm.

Throws:

RoamingException - if roaming protocol failed;

java.io.IOException - if the communication connection failed;

UserBadPasswordException - if the password is invalid;

UserFatalException - if user recovery failed;

UserCertificateRevokedException

java.security.cert.CertificateException

java.security.KeyException

See Also:

RoamingCredentialWriter

update

public void update(EntrustFiles files)
            throws RoamingException,
                   java.io.IOException

Updates the user's files in the Directory, or places them in the Directory if they do not already exist. This method can only be called after login(java.lang.String, com.entrust.toolkit.util.SecureStringBuffer).

Parameters:

files - the files to be updated.

Throws:

java.io.IOException - if the operation failed due to any communication problem;

RoamingException - if the operation failed due to any other reason.

updateAnother

public void updateAnother(java.lang.String subjectDN,
                 EntrustFiles files)
                   throws RoamingException,
                          java.io.IOException,
                          UserNotLoggedInException

Updates another User's files in the Directory, or places them in the Directory if they do not already exist. This method can only be called after login(java.lang.String, com.entrust.toolkit.util.SecureStringBuffer).

The user requesting this operation must have privileges set that allow the user to perform the operation.

Parameters:

subjectDN - the DN of the user whose roaming files are to be updated.

files - the files to be updated.

Throws:

RoamingException - if the roaming protocol failed;

java.io.IOException - if the communication connection failed;

UserNotLoggedInException - if the user is not logged in.

changePassword

public void changePassword(SecureStringBuffer oldPassword,
                  SecureStringBuffer newPassword)
                    throws RoamingException,
                           java.io.IOException,
                           UserBadPasswordException,
                           UserFatalException,
                           UserNotLoggedInException

Deprecated. As of 7.0, use User.changePassword() with a RoamingCredentialWriter object set to perform this task.

Changes the user's password and updates the Roaming user. This method can only be called after login(java.lang.String, com.entrust.toolkit.util.SecureStringBuffer).

Parameters:

oldPassword - the user's current password.

newPassword - the user's new password.

Throws:

RoamingException - if the roaming protocol failed;

java.io.IOException - if the communication connection failed;

UserBadPasswordException - if either old password is incorrect or the new password is invalid;

UserFatalException - if the password change failed;

UserNotLoggedInException - if the user is not logged in.

See Also:

RoamingCredentialWriter

updateSigningKeys

public boolean updateSigningKeys()
                          throws UserNotLoggedInException,
                                 UserFatalException,
                                 UserBadPasswordException,
                                 java.io.IOException,
                                 RoamingException

Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object, and let the User perform key management automtically.

Updates the user's signing keys and the Roaming Server for this user.

Note

To use the new key, call the getProfile method to obtain the updated profile.

Throws:

UserNotLoggedInException - if the user is not logged in;

UserFatalException - if the key update failed;

UserBadPasswordException - if the user password is invalid;

java.io.IOException - if the communication connection failed;

RoamingException - if the roaming protocol failed.

See Also:

RoamingCredentialReader, RoamingCredentialWriter

updateEncryptionKeys

public boolean updateEncryptionKeys()
                             throws UserNotLoggedInException,
                                    UserFatalException,
                                    UserBadPasswordException,
                                    java.io.IOException,
                                    RoamingException

Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object, and let the User perform key management automtically.

Updates the user's encryption keys the Roaming Server for this user.

Note

To use the new key, call getProfile() to obtain the updated profile.

Throws:

UserNotLoggedInException - if the user is not logged in;

UserFatalException - if the key update failed;

UserBadPasswordException - if the user password is invalid;

java.io.IOException - if the communication connection failed;

RoamingException - if the roaming protocol failed.

See Also:

RoamingCredentialReader, RoamingCredentialWriter

signingKeyUpdateRequired

public boolean signingKeyUpdateRequired()
                                 throws UserNotLoggedInException,
                                        UserBadPasswordException

Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object for key management tasks.

Returns:

whether signing key update is requred.

Throws:

UserNotLoggedInException - if the user is not logged in;

UserBadPasswordException - if the user password is invalid.

See Also:

RoamingCredentialReader, RoamingCredentialWriter

encryptionKeyUpdateRequired

public boolean encryptionKeyUpdateRequired()
                                    throws UserNotLoggedInException,
                                           UserBadPasswordException

Deprecated. As of 7.0, use a RoamingCredentialReader and RoamingCredentialWriter object with a User object for key management tasks.

Returns:

whether encryptionkey update is required.

Throws:

UserNotLoggedInException - if the user is not logged in;

UserBadPasswordException - if the user password is invalid.

See Also:

RoamingCredentialReader, RoamingCredentialWriter

isLoggedIn

public boolean isLoggedIn()

Determines whether or not the user is logged in.

Returns:

a boolean specifying the users logged in status

sslLogEnabled

public boolean sslLogEnabled()

Returns the SSL log mode.

Returns:

true if ssl log is written to 'ssl.log' file, false otherwise.

getRequestedFiles

public EntrustFiles getRequestedFiles()

Returns an EntrustFiles object from Roaming Server during the login operation.

Returns:

the requested EntrustFiles object.

enableSSLLog

public void enableSSLLog(boolean enable)

Enables SSL log. The history of SSL activities will be written to 'ssl.log' file.

Parameters:

enable - true to enable and false to disable. By default, it's false.