RoamingUser ("Entrust Authority Security Toolkit for the Java Platform")

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

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

Method Summary

All Methods Instance Methods Concrete Methods Deprecated 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.

Class RoamingUser

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RoamingUser

Method Detail

getServerVersion

login

getProfile

logout

register

deregister

create

recover

update

updateAnother

changePassword

updateSigningKeys

updateEncryptionKeys

signingKeyUpdateRequired

encryptionKeyUpdateRequired

isLoggedIn

sslLogEnabled

getRequestedFiles

enableSSLLog