Interface IMetaClient

Namespace: PKWARE.Smartcrypt.MetaClient

Assembly: MetaClient.dll

Syntax

public interface IMetaClient

Properties

CryptoProvider

The ICryptoProvider that this MetaClient is using.

Declaration

[NotNull]
ICryptoProvider CryptoProvider { get; }

Property Value

Type	Description
ICryptoProvider

IsolatedMode

In isolated mode no network communication is allowed.

Declaration

bool IsolatedMode { get; set; }

Property Value

Type	Description
Boolean

Logger

Declaration

[NotNull]
Logger Logger { get; }

Property Value

Type	Description
Logger

Methods

ApplyContingencyGroup(String)

Data are being encrypted with a custom password. To ensure that the organization still has access to the data encrypt the password for the Contingency Association's RSA public key and store it in the JSON.

Declaration

[NotNull]
EncryptionInfo ApplyContingencyGroup([CanBeNull] string sessionKey = null)

Parameters

Type	Name	Description
String	sessionKey	If null, a new 256 bit session key is created. Must not be more than 214 bytes in length.

Returns

Type	Description
EncryptionInfo

Exceptions

Type	Condition
MetaClientException	With Category of CategoryUpgrade if the data are newer than understood by this software. With Category of CategoryInternal if the data are in an invalid format.

askForAsset(String)

Requests the specified asset from the Metadata Server.

Declaration

[Obsolete("Should only be used by internal PKWARE Archive clients")]
void askForAsset(string jsonOrUrn)

Parameters

Type	Name	Description
String	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.

Remarks

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.

Exceptions

Type	Condition
MetaClientException	With a Category of CategoryInternal if the json provided is in an unrecognized format. Other variations of the exception may be thrown as well.

canCreateKey(String)

Declaration

bool canCreateKey(string kind)

Parameters

Type	Name	Description
String	kind

Returns

Type	Description
Boolean

CanRecoveryBePerformed()

Declaration

bool CanRecoveryBePerformed()

Returns

Type	Description
Boolean

canUseUnmanagedAccount()

Declaration

bool canUseUnmanagedAccount()

Returns

Type	Description
Boolean

ChangeEmail(String)

Changes the email address of the current user. Performs network IO to immediately sync the change to the server.

Declaration

void ChangeEmail([NotNull] string value)

Parameters

Type	Name	Description
String	value	The new email address to use.

ChangeName(String)

Changes the name of the current user. Performs network IO to immediately sync the change to the server.

Declaration

void ChangeName([NotNull] string value)

Parameters

Type	Name	Description
String	value	The new name to use.

ChangePassword(String, String)

Changes the password of the current user.

Declaration

void ChangePassword([NotNull] string oldPassword, [NotNull] string newPassword)

Parameters

Type	Name	Description
String	oldPassword	The current password of the user.
String	newPassword	The new password for the user.

Remarks

When performing a password change using a managed user, the account is converted to be an unmanaged user. This causes the account password to detach from the Active Directory password. However, the account keeps associations with AD Groups used in Policies, Smartkeys, Assignments, and so forth. Prior to being able to change the password of a managed user, the server must be configured to allow that user to become an unmanaged user. See the SEM Documentation for guidance on how to accomplish this.

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.

Declaration

void changesWereNotSaved()

ChangeUrl(String)

Used exclusively for SMDS identities. Used to indicate the URL of the server hosting the identity. Performs network IO to immediately sync the change to the server.

Declaration

void ChangeUrl([NotNull] string value)

Parameters

Type	Name	Description
String	value	The new URL to use.

CreateAccount(String, String, String)

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.

Declaration

void CreateAccount([NotNull] string email, [CanBeNull] string name, [NotNull] string password)

Parameters

Type	Name	Description
String	email
String	name	Can be null in which case this user won't have a name.
String	password

Exceptions

Type	Condition
MetaClientException	If account creation fails.

See Also

CreateSatelliteServerAccount(String, String, String, String, String)

CreateSatelliteServerAccount(String, String, String, String, String)

Create a new satellite server account for a new Smartcrypt Enterprise Manager. The account will be created online unless in isolated mode.

Declaration

void CreateSatelliteServerAccount([NotNull] string email, [NotNull] string name, [NotNull] string url, [NotNull] string password, [CanBeNull] string licenseRequest = null)

Parameters

Type	Name	Description
String	email	Email address of the satellite account.
String	name	Name of the satellite account.
String	url	URL of the satellite account.
String	password	Password for the account.
String	licenseRequest	Optional JSON string with license request. Will only be used when creating an online account.

See Also

IsolatedMode

CreateAccount(String, String, String)

DecryptV2(String)

Performs V2 decryption using the RSA private key of the logged-in identity.

Declaration

[NotNull]
byte[] DecryptV2([NotNull] string data)

Parameters

Type	Name	Description
String	data	The data to decrypt.

Returns

Type	Description
Byte[]	The decrypted data.

Exceptions

Type	Condition
MetaClientException	With Category of CategoryUpgrade if the data are newer than understood by this software. With Category of CategoryInternal if the data are in an invalid format.

See Also

DecryptV2(ICryptoProvider, String, Byte[])

DecryptV3(String)

Performs V3 decryption using the AES key of the logged-in identity.

Declaration

[NotNull]
byte[] DecryptV3([NotNull] string data)

Parameters

Type	Name	Description
String	data	The data to decrypt.

Returns

Type	Description
Byte[]	The decrypted data.

Exceptions

Type	Condition
MetaClientException	With Category of CategoryUpgrade if the data are newer than understood by this software. With Category of CategoryInternal if the data are in an invalid format.

See Also

DecryptV3(ICryptoProvider, String, Byte[])

DeleteAppDatum(String, String)

Declaration

void DeleteAppDatum(string kind, string name)

Parameters

Type	Name	Description
String	kind
String	name

EncryptAccountPassword(String)

Declaration

[NotNull]
string EncryptAccountPassword([NotNull] string accountPassword)

Parameters

Type	Name	Description
String	accountPassword

Returns

Type	Description
String

GET(String)

Declaration

string GET(string suffix)

Parameters

Type	Name	Description
String	suffix

Returns

Type	Description
String

GetApplicationStatus(String, String, String)

Returns an ApplicationStatus through which ApplicationCompliance can be reported. A new ApplicationStatus will be created if one does not already exist for the given parameters.

Declaration

[NotNull]
ApplicationStatus GetApplicationStatus([NotNull] string kind, [CanBeNull] string version = null, [NotNull] string referenceUrn = "")

Parameters

Type	Name	Description
String	kind	The name of the component for which this entry is being reported. For example, Smartpoint.
String	version	An optional string of the version of the component for which this entry is being reported.
String	referenceUrn	A unique identifier, used to differentiate statuses when multiple exist for the same app + kind combo. For example, a single app may have multiple Smartpoints, so the Smartpoint URN is provided. Must be provided, but may be empty.

Returns

Type	Description
ApplicationStatus	An application status object which can be updated with ApplicationCompliance objects.

Remarks

Application status is useful for reporting to Smartcrypt Enterprise Manager the state of various subsystems of your application. For example, PKWARE's PDE application uses application status to report whether or not all files in a Smartpoint are encrypted according to the policy defined for that smartpoint.

GetArchiveDecryptionPassword(String)

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

Declaration

string GetArchiveDecryptionPassword(string jsonOrUrn)

Parameters

Type	Name	Description
String	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

Type	Description
String	The password requested in UTF-8.

Exceptions

Type	Condition
MetaClientException	With a Category of CategoryInternal if the json provided is in an unrecognized format, or with CategoryNotFound if the password cannot be found. Other variations of the exception may be thrown as well.

GetClusterServers()

Declaration

IEnumerable<string> GetClusterServers()

Returns

Type	Description
IEnumerable<String>

GetEntitlement(String, String)

Declaration

[CanBeNull]
string GetEntitlement([NotNull] string name, [CanBeNull] string defaultValue = null)

Parameters

Type	Name	Description
String	name	The name of the entitlement.
String	defaultValue

Returns

Type	Description
String	The value for the entitlement of the given name, or the defaultValue if the entitlement is not found.

GetManagedAesKey(String)

Declaration

[NotNull]
IManagedAesKey GetManagedAesKey([NotNull] string serialized)

Parameters

Type	Name	Description
String	serialized

Returns

Type	Description
IManagedAesKey

Exceptions

Type	Condition
MetaClientException	With Category of CategoryUpgrade if the serialized content cannot be parsed. Also with other categories for other reasons.

GetManagedAesKeys()

Declaration

IEnumerable<ISingleAssetManager> GetManagedAesKeys()

Returns

Type	Description
IEnumerable<ISingleAssetManager>	All managed keys. Each can be used for various purposes. Perform filtering before use.

GetNotifications()

Declaration

ISet<Notification> GetNotifications()

Returns

Type	Description
ISet<Notification>

getPrefix()

Declaration

string getPrefix()

Returns

Type	Description
String

GetPublicKey()

Returns the public key of the current user.

Declaration

[CanBeNull]
string GetPublicKey()

Returns

Type	Description
String	The public key of the current user. Will be null if the account has not been created.

GetSyncInterval()

Declaration

TimeSpan GetSyncInterval()

Returns

Type	Description
TimeSpan

getUserEmail()

Gets the email address of the current user.

Declaration

[CanBeNull]
string getUserEmail()

Returns

Type	Description
String	The email address of the current user. Will be null if user information has not been synced.

getUserETag()

Declaration

int getUserETag()

Returns

Type	Description
Int32

getUserId()

Declaration

long getUserId()

Returns

Type	Description
Int64

getUserName()

Gets the name of the current user.

Declaration

[CanBeNull]
string getUserName()

Returns

Type	Description
String	The name of the current user. Will be null if user information has not been synced or if the name is not known.

getUserURN()

Declaration

string getUserURN()

Returns

Type	Description
String

getXPIDs()

Declaration

IList<KnownUser> getXPIDs()

Returns

Type	Description
IList<KnownUser>	All Smartcrypt users known to the user, excluding the representation of the current user.

isAccountAllowed()

Declaration

bool isAccountAllowed()

Returns

Type	Description
Boolean

IsAccountManaged(String)

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

Declaration

bool IsAccountManaged([NotNull] string email)

Parameters

Type	Name	Description
String	email

Returns

Type	Description
Boolean	true if the account is managed, otherwise false.

Exceptions

Type	Condition
MetaClientException	Primarily for network reasons, but could be others as well. Best to display to the user. With CategoryMigrationRequired if needing to migrate.

isAuthenticated()

Declaration

bool isAuthenticated()

Returns

Type	Description
Boolean

isDeviceAllowed()

Declaration

bool isDeviceAllowed()

Returns

Type	Description
Boolean

isLicensed()

Will perform a network call.

Declaration

bool isLicensed()

Returns

Type	Description
Boolean	true if the current user is able to acquire a license; otherwise, false.

Exceptions

Type	Condition
MetaClientException

isLoggedIn()

Declaration

bool isLoggedIn()

Returns

Type	Description
Boolean

isManagedAccount()

Declaration

bool isManagedAccount()

Returns

Type	Description
Boolean

isOfflineAccessExpired()

Declaration

bool isOfflineAccessExpired()

Returns

Type	Description
Boolean

isRegistered()

Declaration

bool isRegistered()

Returns

Type	Description
Boolean

isSatellite()

Indicates whether or not this instance of MetaClient is communicating with a satellite MDS.

Declaration

bool isSatellite()

Returns

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

Remarks

Prior to a call to PKWARE.Smartcrypt.MetaClient.MetaState.CheckDomain(System.String), which happens during typical login flows or a restore from serialized state, this function is not guaranteed to be accurate.

Login(String, String, String)

Attempts to log in the specified user.

Declaration

void Login([NotNull] string email, [NotNull] string password, [CanBeNull] string oldPassword = null)

Parameters

Type	Name	Description
String	email	The email address of the user. Must include the domain. Ex. john@example.com.
String	password	The current password of the user.
String	oldPassword	The previous password of the user. This is not required, but is available for use by application that do not synchronize the SID and do not run in isolated mode.

Exceptions

Type	Condition
MetaClientException

LoginImplicitAccount()

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.

Declaration

void LoginImplicitAccount()

Remarks

When this login method is used, Login(String, String, String) and LoginManagedAccount(String, String) must not be used. Additionally, a custom server URL must be provided using Server.

Exceptions

Type	Condition
MetaClientException	For all sorts of reasons.

See Also

LoginManagedAccount(String, String)

Login(String, String, String)

LoginManagedAccount(String, String)

Declaration

void LoginManagedAccount([NotNull] string emailWithHost, [NotNull] string accountPassword)

Parameters

Type	Name	Description
String	emailWithHost
String	accountPassword

LoginManagedAccountEncPass(String, String)

Declaration

void LoginManagedAccountEncPass([NotNull] string emailWithHost, [NotNull] string encryptedAccountPassword)

Parameters

Type	Name	Description
String	emailWithHost
String	encryptedAccountPassword	The account password after going through EncryptAccountPassword(String).

Logout()

Enables this instance to be used with another user. Information about the server(s) this instance was communicating with is retained.

Declaration

void Logout()

lookupUsers(IList<String>)

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

Declaration

IList<KnownUser> lookupUsers(IList<string> emails)

Parameters

Type	Name	Description
IList<String>	emails

Returns

Type	Description
IList<KnownUser>

migrate(String, String, String, Boolean)

Declaration

void migrate(string email, string password, string accountPassword, bool mfaExpected)

Parameters

Type	Name	Description
String	email
String	password
String	accountPassword
Boolean	mfaExpected

POST(String, String)

Declaration

string POST(string suffix, string text)

Parameters

Type	Name	Description
String	suffix
String	text

Returns

Type	Description
String

ProcessIsolatedUpdate(String)

Declaration

void ProcessIsolatedUpdate([NotNull] string blob)

Parameters

Type	Name	Description
String	blob

RecoverPassword(String, Boolean, String)

The final step of the password recovery process for unmanaged users.

Declaration

[NotNull]
string RecoverPassword([NotNull] string recoveryToken, bool mfaExpected, [CanBeNull] string recoveryCipher = null)

Parameters

Type	Name	Description
String	recoveryToken	The recovery token sent to the user via email after initiating password recovery via RequestRecoveryEmail(String).
Boolean	mfaExpected
String	recoveryCipher	The encrypted password. If empty, the value stored by MetaClient will be used.

Returns

Type	Description
String	The recovered password.

Remarks

Only unmanaged users can recover their password. Managed users should be directed to their system administrator.

Exceptions

Type	Condition
MetaClientException

See Also

CanRecoveryBePerformed()

RequestRecoveryEmail(String)

RequestAccess(String)

Declaration

void RequestAccess(string serialized)

Parameters

Type	Name	Description
String	serialized

Exceptions

Type	Condition
MetaClientException	With Category of CategoryUpgrade if the serialized content cannot be parsed. May also happen as a results of network problems and other reasons.

requestEmailVerification()

Declaration

void requestEmailVerification()

RequestRecoveryEmail(String)

Declaration

void RequestRecoveryEmail([NotNull] string email)

Parameters

Type	Name	Description
String	email	If empty, the value from the PKWARE.Smartcrypt.MetaClient.PID will be used.

RespondToNotification(String, String)

Declaration

void RespondToNotification([NotNull] string urn, [NotNull] string action)

Parameters

Type	Name	Description
String	urn
String	action

RestoreAll(IDictionary<String, String>)

Declaration

void RestoreAll([NotNull] IDictionary<string, string> serials)

Parameters

Type	Name	Description
IDictionary<String, String>	serials

Exceptions

Type	Condition
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.

SaveAppData(String, String, String)

Declaration

void SaveAppData(string kind, string name, string value)

Parameters

Type	Name	Description
String	kind
String	name
String	value

SerializeAll(Boolean)

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

Declaration

[NotNull]
IDictionary<string, string> SerializeAll(bool incremental = true)

Parameters

Type	Name	Description
Boolean	incremental	If true, only those data that have changed since the last serialization will be serialized. If false all data will be serialized.

Returns

Type	Description
IDictionary<String, String>	The serials to save/delete. Deletion is indicated by a map value of null. The values are always sorted by key in alphabetical order.

SetServer(String)

Sets the new server to communicate with. This does not involve any network IO. Clears the MDS public key.

Declaration

void SetServer([NotNull] string url)

Parameters

Type	Name	Description
String	url	The URL of the server.

SetStat(String, String, Int64)

Declaration

void SetStat(string kind, string qualifier, long value)

Parameters

Type	Name	Description
String	kind
String	qualifier
Int64	value

shouldPersistCredentials()

Declaration

bool shouldPersistCredentials()

Returns

Type	Description
Boolean

Sign(String)

Performs an RSA signature of the content, using the RSA private key of the logged-in identity.

Declaration

[NotNull]
string Sign([NotNull] string data)

Parameters

Type	Name	Description
String	data	The data to sign.

Returns

Type	Description
String	The signature with the V2 prefix.

See Also

Sign(ICryptoProvider, Byte[], String)

SwitchToCentral(String)

Declaration

void SwitchToCentral([NotNull] string prefix)

Parameters

Type	Name	Description
String	prefix	The base URL of the central server. For example, {@code https://vcs.pkware.com/mds}.

switchToDomain(String)

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

Declaration

bool switchToDomain(string domainOrEmail)

Parameters

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

Returns

Type	Description
Boolean	true if now talking to a SMDS. Otherwise, false.

Exceptions

Type	Condition
MetaClientException	Primarily for network reasons, but could be others as well. Best to display to the user.

sync()

Declaration

void sync()

WrapSessionKeyWithSmartkey(String, String)

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

Declaration

[NotNull]
EncryptionInfo WrapSessionKeyWithSmartkey([NotNull] string smartkeyUrn, [CanBeNull] string sessionKey = null)

Parameters

Type	Name	Description
String	smartkeyUrn	Of a locally held key.
String	sessionKey	If null, a new 256 bit session key is created, otherwise, the existing key is expanded to 256 bits.

Returns

Type	Description
EncryptionInfo	The session key and json document allowing key retrieval.

Extension Methods

MetaClientSemanticEncryption.DecryptGroupKey(IMetaClient, String)

MetaClientSemanticEncryption.DecryptHybrid(IMetaClient, String)