com.pkware.smartcrypt.metaclient

Interface MetaClient

All Known Implementing Classes:

NativeMetaClient

public interface MetaClient

Method Summary

Modifier and Type	Method and Description
void	askForAsset(String jsonOrUrn) Requests the specified asset from the Metadata Server.
boolean	canCreateKey(String kind)
boolean	canRecoveryBePerformed()
void	changeEmail(String newEmail)
void	changeName(String newName)
void	changePassword(String oldPassword, String newPassword)
void	changesWereNotSaved() If unable to save serials, this function must be called.
void	createAccount(String email, String name, String password) Does not pay attention to whether or not an account already exists.
String	getArchiveDecryptionPassword(String jsonOrUrn) Given asset information as described below, extracts a decryption password.
EncryptionInfo	getArchiveEncryptionInfo(String jsonOrUrn, String password) Deprecated. Use wrapSessionKeyWithSmartkey(String, String)
String	getEntitlement(String name, String defaultValue)
Logger	getLogger()
ManagedAesKey	getManagedAesKey(String serialized)
List<SingleAssetManager>	getManagedAesKeys()
Set<Notification>	getNotifications()
int	getSyncInterval()
List<KnownUser>	getXPIDs()
boolean	isAccountManaged(String email) Query server and find out if this email is a managed account.
boolean	isDeviceAllowed()
boolean	isLicensed() This will perform a network call.
boolean	isLoggedIn()
boolean	isSatellite() Is not valid until a previous call to PKMeta::checkDomain() in native code which happens during typical login flows or a restore from serialized state.
void	login(String emailWithHost, String password)
void	loginImplicitAccount() Performs a login using a system user.
void	loginManagedAccount(String emailWithHost, String password)
void	logout()
List<KnownUser>	lookupUsers(String... userEmails) Asks the server for user information for the provided email addresses.
void	migrate(String username, String password, String accountPassword, boolean mfaExpected)
String	recoverPassword(String code, boolean mfaExpected, String cipher)
void	requestAccess(String serialized)
void	requestEmailVerification()
void	requestRecoveryEmail(String email)
void	respondToNotification(String urn, String action)
void	restoreAll(Map<String,String> serials)
Map<String,String>	serializeAll() It is assumed that all data after this call are successfully transformed.
void	switchToCentral(String prefix)
boolean	switchToDomain(String domainOrEmail) May overwrite any previous information passed to switchToCentral(String).
void	sync()
EncryptionInfo	wrapSessionKeyWithSmartkey(String smartkeyUrn) Generates a new 256 bit session key and wraps it for secure storage and future retrieval.
EncryptionInfo	wrapSessionKeyWithSmartkey(String smartkeyUrn, String sessionKey) Expands the existing session key to 256 bits and wraps it for secure storage and future retrieval.

Method Detail

restoreAll

void restoreAll(Map<String,String> serials)
         throws MetaClientException

Throws:

MetaClientException - If the data being restored are invalid. Invalid means that there are a different number than expected or that any are different from when we last saw them.

serializeAll

@Nonnull
Map<String,String> serializeAll()
                                  throws MetaClientException

It is assumed that all data after this call are successfully transformed. If that is not the case, you must call changesWereNotSaved()

Returns:

The serials to save/delete. Deletion is indicated by a map value of null.

Throws:

MetaClientException

changesWereNotSaved

void changesWereNotSaved()

If unable to save serials, this function must be called. The localDirty flags will be reset to the state before the request to serialize.

requestEmailVerification

void requestEmailVerification()

sync

void sync()
   throws MetaClientException

Throws:

MetaClientException

askForAsset

void askForAsset(String jsonOrUrn)
          throws MetaClientException

Requests the specified asset from the Metadata Server. If the asset is already held, this is a no-op. If the asset is homed to a different server than the user, the asset will not be fetched, and this is a no-op. If not currently online, the request will be cached and processed in the future.

Parameters:

jsonOrUrn - Whenever possible, the full asset JSON should be provided. The JSON will include all information to correctly find an asset. If only the URN is provided, the asset may not be found.

Throws:

MetaClientException - with a MetaClientException.category of MetaClientException.CATEGORY_INTERNAL if the json provided is in an unrecognized format. Other variations of the exception may be thrown as well.

getArchiveDecryptionPassword

@Nonnull
String getArchiveDecryptionPassword(String jsonOrUrn)
                                      throws MetaClientException

Given asset information as described below, extracts a decryption password. May perform network I/O and will auto-request access if needed.

Parameters:

jsonOrUrn - Whenever possible, the full asset JSON should be provided. The JSON will include all information to correctly find an asset. If only the URN is provided, the asset may not be found.

Returns:

The password requested in UTF-8

Throws:

MetaClientException - with a MetaClientException.category of MetaClientException.CATEGORY_INTERNAL if the json provided is in an unrecognized format, or with MetaClientException.CATEGORY_NOT_FOUND if the password cannot be found. Other variations of the exception may be thrown as well.

getArchiveEncryptionInfo

@Deprecated
 @Nonnull
EncryptionInfo getArchiveEncryptionInfo(@Nullable
                                                              String jsonOrUrn,
                                                              @Nullable
                                                              String password)
                                                       throws MetaClientException

Deprecated. Use wrapSessionKeyWithSmartkey(String, String)

Handles all the work of applying contingency group and provides the ability to use an asset with a custom password.

Parameters:

jsonOrUrn - optional. Should be null if no asset is being used.

password - optional. Should be null if no password is being used.

Returns:

EncryptionInfo.json will be null if no asset is being used. EncryptionInfo.password will always be valid.

Throws:

MetaClientException

getXPIDs

@Nonnull
List<KnownUser> getXPIDs()

Returns:

all Smartcrypt users known to the user, excluding the representation of the current user

lookupUsers

@Nonnull
List<KnownUser> lookupUsers(String... userEmails)
                              throws MetaClientException

Asks the server for user information for the provided email addresses. Duplicates are collapsed.

Throws:

MetaClientException

isDeviceAllowed

boolean isDeviceAllowed()

isLicensed

boolean isLicensed()
            throws MetaClientException

This will perform a network call.

Returns:

true if the current user is able to acquire a license; otherwise, false

Throws:

MetaClientException - if there was any non-standard problem. Think network, signature, etc.

isSatellite

boolean isSatellite()

Is not valid until a previous call to PKMeta::checkDomain() in native code which happens during typical login flows or a restore from serialized state.

Returns:

true if this instance is known to be communicating with a SMDS rather than a CMDS, otherwise false

switchToDomain

boolean switchToDomain(String domainOrEmail)
                throws MetaClientException

May overwrite any previous information passed to switchToCentral(String). Performs network IO.

Parameters:

domainOrEmail - Domain name registered with CMDS or the email address of the current user, from which the domain will be deduced.

Returns:

true if now talking to a SMDS. Otherwise, false.

Throws:

MetaClientException - primarily for network reasons, but could be others as well. Best to display to the user.

isAccountManaged

boolean isAccountManaged(String email)
                  throws MetaClientException

Query server and find out if this email is a managed account.

Parameters:

email - of the current user

Returns:

true if the account is managed, otherwise, false.

Throws:

MetaClientException - primarily for network reasons, but could be others as well. Best to display to the user. With MetaClientException.CATEGORY_MIGRATION_REQUIRED if needing to migrate.

switchToCentral

void switchToCentral(String prefix)

Parameters:

prefix - The base URL of the central server. For example, https://vcs.pkware.com/mds.

isLoggedIn

boolean isLoggedIn()

getSyncInterval

int getSyncInterval()

Returns:

the sync interval in seconds

getEntitlement

@Nullable
String getEntitlement(String name,
                                @Nullable
                                String defaultValue)

Parameters:

name - of the entitlement

Returns:

The value for the entitlement of the given name, or the defaultValue if the entitlement is not found

changeEmail

void changeEmail(String newEmail)
          throws MetaClientException

Throws:

MetaClientException

changeName

void changeName(String newName)
         throws MetaClientException

Throws:

MetaClientException

changePassword

void changePassword(String oldPassword,
                    String newPassword)
             throws MetaClientException

Throws:

MetaClientException

respondToNotification

void respondToNotification(String urn,
                           String action)
                    throws MetaClientException

Throws:

MetaClientException

getNotifications

@Nonnull
Set<Notification> getNotifications()

canCreateKey

boolean canCreateKey(String kind)

getManagedAesKeys

@Nonnull
List<SingleAssetManager> getManagedAesKeys()

Returns:

All managed keys. Each can be used for various purposes. Perform filtering before use.

getManagedAesKey

@Nonnull
ManagedAesKey getManagedAesKey(String serialized)
                                 throws MetaClientException

Throws:

MetaClientException - with MetaClientException.category of MetaClientException.CATEGORY_UPGRADE if the serialized content cannot be parsed. Also with other categories for other reasons.

logout

void logout()

login

void login(String emailWithHost,
           String password)
    throws MetaClientException

Throws:

MetaClientException

loginManagedAccount

void loginManagedAccount(String emailWithHost,
                         String password)
                  throws MetaClientException

Throws:

MetaClientException

loginImplicitAccount

void loginImplicitAccount()
                   throws MetaClientException

Performs a login using a system user. On Windows, the Windows user account owning this process is used. On Mac and Linux, the Kerberos user setup via kinit or a similar utility is used.

When this login method is used, login(String, String) and loginManagedAccount(String, String) must not be used. Additionally, a custom server URL must be provided using NativeMetaClient.Builder.server(String).

Throws:

MetaClientException - for all sorts of reasons.

See Also:

loginManagedAccount(String, String), login(String, String)

migrate

void migrate(String username,
             String password,
             String accountPassword,
             boolean mfaExpected)
      throws MetaClientException

Parameters:

accountPassword - typically from Active Directory

Throws:

MetaClientException

createAccount

void createAccount(String email,
                   @Nullable
                   String name,
                   String password)
            throws MetaClientException

Does not pay attention to whether or not an account already exists. All metadata will be replaced with new ones. ONLY CALL THIS IF YOU'VE ALREADY FAILED TO LOG IN. Does not sync and does not create keys.

Parameters:

name - Can be null in which case this user won't have a name

Throws:

MetaClientException - if account creation fails

requestRecoveryEmail

void requestRecoveryEmail(String email)
                   throws MetaClientException

Throws:

MetaClientException

recoverPassword

@Nonnull
String recoverPassword(String code,
                                boolean mfaExpected,
                                @Nullable
                                String cipher)
                         throws MetaClientException

Throws:

MetaClientException

canRecoveryBePerformed

boolean canRecoveryBePerformed()

requestAccess

void requestAccess(String serialized)
            throws MetaClientException

Throws:

MetaClientException - with MetaClientException.category of MetaClientException.CATEGORY_UPGRADE if the serialized content cannot be parsed. May also happen as a results of network problems and other reasons

getLogger

@Nonnull
Logger getLogger()

wrapSessionKeyWithSmartkey

@Nonnull
EncryptionInfo wrapSessionKeyWithSmartkey(String smartkeyUrn,
                                                   @Nullable
                                                   String sessionKey)

Expands the existing session key to 256 bits and wraps it for secure storage and future retrieval.

Parameters:

smartkeyUrn - of a locally held key

sessionKey - may be null or empty

Returns:

the session key and json document allowing key retrieval

wrapSessionKeyWithSmartkey

@Nonnull
EncryptionInfo wrapSessionKeyWithSmartkey(String smartkeyUrn)

Generates a new 256 bit session key and wraps it for secure storage and future retrieval.

Parameters:

smartkeyUrn - of a locally held key

Returns:

the session key and json document allowing key retrieval