com.pkware.smartcrypt.metaclient

Class NativeMetaClient

java.lang.Object

com.pkware.smartcrypt.metaclient.NativeMetaClient

All Implemented Interfaces:

MetaClient

public final class NativeMetaClient
extends Object
implements MetaClient

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NativeMetaClient.Builder

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.
protected void	finalize()
String	getArchiveDecryptionPassword(String jsonOrUrn) Given asset information as described below, extracts a decryption password.
EncryptionInfo	getArchiveEncryptionInfo(String jsonOrUrn, String password) Deprecated.
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 MetaClient.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.

Methods inherited from class java.lang.Object

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

Method Detail

restoreAll

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

Specified by:

restoreAll in interface MetaClient

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
public Map<String,String> serializeAll()
                                         throws MetaClientException

Description copied from interface: MetaClient

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

Specified by:

serializeAll in interface MetaClient

Returns:

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

Throws:

MetaClientException

changesWereNotSaved

public void changesWereNotSaved()

Description copied from interface: MetaClient

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

Specified by:

changesWereNotSaved in interface MetaClient

requestEmailVerification

public void requestEmailVerification()

Specified by:

requestEmailVerification in interface MetaClient

sync

public void sync()
          throws MetaClientException

Specified by:

sync in interface MetaClient

Throws:

MetaClientException

askForAsset

public void askForAsset(String jsonOrUrn)
                 throws MetaClientException

Description copied from interface: MetaClient

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.

Specified by:

askForAsset in interface MetaClient

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
public String getArchiveDecryptionPassword(String jsonOrUrn)
                                             throws MetaClientException

Description copied from interface: MetaClient

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

Specified by:

getArchiveDecryptionPassword in interface MetaClient

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

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

Deprecated.

Description copied from interface: MetaClient

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

Specified by:

getArchiveEncryptionInfo in interface MetaClient

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
public List<KnownUser> getXPIDs()

Specified by:

getXPIDs in interface MetaClient

Returns:

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

lookupUsers

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

Description copied from interface: MetaClient

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

Specified by:

lookupUsers in interface MetaClient

Throws:

MetaClientException

isDeviceAllowed

public boolean isDeviceAllowed()

Specified by:

isDeviceAllowed in interface MetaClient

isLicensed

public boolean isLicensed()
                   throws MetaClientException

Description copied from interface: MetaClient

This will perform a network call.

Specified by:

isLicensed in interface MetaClient

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

public boolean isSatellite()

Description copied from interface: MetaClient

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.

Specified by:

isSatellite in interface MetaClient

Returns:

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

switchToDomain

public boolean switchToDomain(String domainOrEmail)
                       throws MetaClientException

Description copied from interface: MetaClient

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

Specified by:

switchToDomain in interface MetaClient

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

public boolean isAccountManaged(String email)
                         throws MetaClientException

Description copied from interface: MetaClient

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

Specified by:

isAccountManaged in interface MetaClient

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

public void switchToCentral(String prefix)

Specified by:

switchToCentral in interface MetaClient

Parameters:

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

isLoggedIn

public boolean isLoggedIn()

Specified by:

isLoggedIn in interface MetaClient

getSyncInterval

public int getSyncInterval()

Specified by:

getSyncInterval in interface MetaClient

Returns:

the sync interval in seconds

getEntitlement

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

Specified by:

getEntitlement in interface MetaClient

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

public void changeEmail(String newEmail)
                 throws MetaClientException

Specified by:

changeEmail in interface MetaClient

Throws:

MetaClientException

changeName

public void changeName(String newName)
                throws MetaClientException

Specified by:

changeName in interface MetaClient

Throws:

MetaClientException

changePassword

public void changePassword(String oldPassword,
                           String newPassword)
                    throws MetaClientException

Specified by:

changePassword in interface MetaClient

Throws:

MetaClientException

respondToNotification

public void respondToNotification(String urn,
                                  String action)
                           throws MetaClientException

Specified by:

respondToNotification in interface MetaClient

Throws:

MetaClientException

getNotifications

@Nonnull
public Set<Notification> getNotifications()

Specified by:

getNotifications in interface MetaClient

canCreateKey

public boolean canCreateKey(String kind)

Specified by:

canCreateKey in interface MetaClient

getManagedAesKeys

@Nonnull
public List<SingleAssetManager> getManagedAesKeys()

Specified by:

getManagedAesKeys in interface MetaClient

Returns:

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

getManagedAesKey

@Nonnull
public ManagedAesKey getManagedAesKey(String serialized)
                                        throws MetaClientException

Specified by:

getManagedAesKey in interface MetaClient

Throws:

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

logout

public void logout()

Specified by:

logout in interface MetaClient

login

public void login(String emailWithHost,
                  String password)
           throws MetaClientException

Specified by:

login in interface MetaClient

Throws:

MetaClientException

loginManagedAccount

public void loginManagedAccount(String emailWithHost,
                                String password)
                         throws MetaClientException

Specified by:

loginManagedAccount in interface MetaClient

Throws:

MetaClientException

loginImplicitAccount

public void loginImplicitAccount()

Description copied from interface: MetaClient

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, MetaClient.login(String, String) and MetaClient.loginManagedAccount(String, String) must not be used. Additionally, a custom server URL must be provided using NativeMetaClient.Builder.server(String).

Specified by:

loginImplicitAccount in interface MetaClient

See Also:

MetaClient.loginManagedAccount(String, String), MetaClient.login(String, String)

migrate

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

Specified by:

migrate in interface MetaClient

accountPassword - typically from Active Directory

Throws:

MetaClientException

createAccount

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

Description copied from interface: MetaClient

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.

Specified by:

createAccount in interface MetaClient

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

Throws:

MetaClientException - if account creation fails

requestRecoveryEmail

public void requestRecoveryEmail(String email)
                          throws MetaClientException

Specified by:

requestRecoveryEmail in interface MetaClient

Throws:

MetaClientException

recoverPassword

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

Specified by:

recoverPassword in interface MetaClient

Throws:

MetaClientException

canRecoveryBePerformed

public boolean canRecoveryBePerformed()

Specified by:

canRecoveryBePerformed in interface MetaClient

requestAccess

public void requestAccess(String serialized)
                   throws MetaClientException

Specified by:

requestAccess in interface MetaClient

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
public Logger getLogger()

Specified by:

getLogger in interface MetaClient

wrapSessionKeyWithSmartkey

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

Description copied from interface: MetaClient

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

Specified by:

wrapSessionKeyWithSmartkey in interface MetaClient

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
public EncryptionInfo wrapSessionKeyWithSmartkey(String smartkeyUrn)

Description copied from interface: MetaClient

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

Specified by:

wrapSessionKeyWithSmartkey in interface MetaClient

Parameters:

smartkeyUrn - of a locally held key

Returns:

the session key and json document allowing key retrieval

finalize

protected void finalize()

Overrides:

finalize in class Object