CryptoKeyStore Class

Properties   Methods   Events   Config Settings   Errors  

The iaKeystore class offers key storage functionality for a variety of key store types.

Syntax

pkiproxy.cryptokeystore()

Remarks

TBD

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CryptoKeyStore.ChannelSettings Property

Manages security and authentication settings.

Syntax

 getChannelSettings(): CryptoChannel;

Default Value

Remarks

Use this property to adjust security, authentication, and signature settings.

This property is read-only.

CryptoKeyStore.Keys Property

An accessor to the collection of keys contained in the key store.

Syntax

 getKeys(): CryptoKeyList;

Default Value

Remarks

Use this property to access, browse, or iterate over keys contained in the storage.

This property is read-only and not available at design time.

CryptoKeyStore.Mechanisms Property

An accessor to the collection of mechanisms supported by the key store.

Syntax

 getMechanisms(): CryptoMechanismList;

Default Value

Remarks

Use this property to access cryptographic mechanisms supported by the key store.

This property is read-only and not available at design time.

CryptoKeyStore.Objects Property

An accessor to the collection of objects - such as certificates - contained in the key store.

Syntax

 getObjects(): CryptoObjectList;

Default Value

Remarks

Use this property to access, browse, or iterate over objects contained in the storage.

This property is read-only and not available at design time.

CryptoKeyStore.Opened Property

Indicates whether the storage is in the open state.

Syntax

 isOpened(): boolean;

Default Value

FALSE

Remarks

Use this property to check if the storage has been 'opened.' Different kinds of key storages imply different meanings for 'being opened', but generally a storage is open if it is available for operations.

Use Open method to open a storage.

This property is read-only and not available at design time.

CryptoKeyStore.Pars Property

Contains a list of store parameters.

Syntax

 getPars(): CryptoParamList;

Default Value

Remarks

Use this property to adjust any access or operation parameters, such as secondary credentials or IDs.

This property is read-only and not available at design time.

CryptoKeyStore.PinnedKey Property

A pinned key.

Syntax

 getPinnedKey(): CryptoKey;

 setPinnedKey(pinnedKey: CryptoKey): void;

Default Value

Remarks

Use this property to pin a key before adding it to the storage with AddKey method.

This property is not available at design time.

CryptoKeyStore.PinnedObject Property

A pinned key.

Syntax

 getPinnedObject(): CryptoObject;

 setPinnedObject(pinnedObject: CryptoObject): void;

Default Value

Remarks

Use this property to pin a key before adding it to the storage with AddObject method.

This property is not available at design time.

CryptoKeyStore.SessionInfo Property

Provides access to the session information.

Syntax

 getSessionInfo(): CryptoSession;

Default Value

Remarks

Use this property to check session parameters.

This property is read-only.

CryptoKeyStore.StorageID Property

A unique identifier of this storage.

Syntax

 getStorageID(): string;

Default Value

""

Remarks

Use this property to get a unique ID of this storage. The format of ID may differ for different kinds of key storages, and may range from a file path for a file storage, to a URI-like ID for a PKCS#11 storage, to an empty value for an in-memory storage.

This property is read-only.

CryptoKeyStore.UserId Property

TBD.

Syntax

 getUserId(): string;

 setUserId(userId: string): void;

Default Value

""

Remarks

TBD

This property is not available at design time.

CryptoKeyStore.UserKeySecret Property

TBD.

Syntax

 getUserKeySecret(): string;

 setUserKeySecret(userKeySecret: string): void;

Default Value

""

Remarks

TBD

This property is not available at design time.

CryptoKeyStore.addKey Method

Adds the pinned key to the storage.

Syntax

async cryptokeystore.addKey(): Promise<void>

Remarks

This method adds a key attached to the PinnedKey property to the storage. This method is a handy way of adding keys generated/returned by other components.

CryptoKeyStore.addObject Method

Adds the pinned object to the storage.

Syntax

async cryptokeystore.addObject(): Promise<void>

Remarks

This method adds a key attached to the PinnedObject property to the storage.

CryptoKeyStore.clear Method

Removes all existing keys and objects from the storage.

Syntax

async cryptokeystore.clear(): Promise<void>

Remarks

Use this method to empty the storage.

CryptoKeyStore.close Method

Closes the logical storage.

Syntax

async cryptokeystore.close(): Promise<void>

Remarks

Use this method to close the key store.

CryptoKeyStore.commit Method

Commits any changes made locally to the store.

Syntax

async cryptokeystore.commit(): Promise<void>

Remarks

This operation has no meaning for stores with direct access.

CryptoKeyStore.commitKey Method

Commits any changes made to the PinnedKey .

Syntax

async cryptokeystore.commitKey(): Promise<void>

Remarks

TBD

CryptoKeyStore.commitObject Method

Commits any changes made to the PinnedObject .

Syntax

async cryptokeystore.commitObject(): Promise<void>

Remarks

TBD

CryptoKeyStore.config Method

Sets or retrieves a configuration setting.

Syntax

async cryptokeystore.config(configurationString : string): Promise<string>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CryptoKeyStore.deriveKey Method

Generates a strong cryptographic key from a password.

Syntax

async cryptokeystore.deriveKey(keyBits : number, password : string, salt : string, sourceKeyID : string): Promise<string>

Remarks

Use this method to generate a cryptographically strong key of a needed length from a password.

This method uses a general-purpose PBKDF2 function with PRF1 and 2048 iterations.

CryptoKeyStore.exportKey Method

Exports the pinned key.

Syntax

async cryptokeystore.exportKey(wrapKeyID : string, pars : string): Promise<Uint8Array>

Remarks

Use this method to export a key referenced in PinnedKey to a byte array. If WrapKeyID is provided, the key will be exported in encrypted form.

CryptoKeyStore.exportObject Method

Exports the pinned object.

Syntax

async cryptokeystore.exportObject(wrapKeyID : string, pars : string): Promise<Uint8Array>

Remarks

Use this method to export a key referenced in PinnedObject to a byte array.

CryptoKeyStore.generateKey Method

Generates a new cryptographic key or key pair.

Syntax

async cryptokeystore.generateKey(keyAlgorithm : string, scheme : string, schemeParams : string, keyBits : number): Promise<void>

Remarks

Call this method to generate a new key or keypair with the desired KeyAlgorithmand KeyBits of length.

The generated key will be added to the store and populated in the PinnedKey property.

CryptoKeyStore.getKeyParam Method

Returns an algorithm-specific key parameter.

Syntax

async cryptokeystore.getKeyParam(name : string): Promise<Uint8Array>

Remarks

Use this method to retrieve an algorithm-specific key parameter.

CryptoKeyStore.getKeyParamStr Method

Returns an algorithm-specific key parameter to a string.

Syntax

async cryptokeystore.getKeyParamStr(name : string): Promise<string>

Remarks

Use this method to get an algorithm-specific key parameter to a string.

CryptoKeyStore.getObjectParam Method

Returns an object parameter.

Syntax

async cryptokeystore.getObjectParam(name : string): Promise<Uint8Array>

Remarks

Use this method to retrieve an object parameter.

CryptoKeyStore.getObjectParamStr Method

Returns an object parameter to a string.

Syntax

async cryptokeystore.getObjectParamStr(name : string): Promise<string>

Remarks

Use this method to get an object parameter to a string.

CryptoKeyStore.importKey Method

Imports a key to the storage.

Syntax

async cryptokeystore.importKey(value : Uint8Array, keyAlgorithm : string, scheme : string, schemeParams : string, wrapKeyID : string, pars : string): Promise<string>

Remarks

Use this method to import a key contained in a byte array.

CryptoKeyStore.importObject Method

Imports an object to the storage.

Syntax

async cryptokeystore.importObject(objType : number, objData : Uint8Array, pars : string): Promise<string>

Remarks

Use this method to import an object contained in a byte array.

CryptoKeyStore.lock Method

Locks the store, preventing concurrent operations by other users.

Syntax

async cryptokeystore.lock(access : string, timeout : number): Promise<string>

Remarks

This operation may not be supported by all store types. Supported Access values: "read", "write". Returns a lock token, which should be passed to the Unlock method when the work is over.

CryptoKeyStore.open Method

Opens existing storage or creates one in memory.

Syntax

async cryptokeystore.open(storageID : string, openMode : string, access : string): Promise<void>

Remarks

Use this method to open the storage with the given StorageID. Key storages can come from several different locations, detailed below. OpenMode: "open", "create", "createnew", "openorcreate" Access: "read", "readwrite", "write", plus a "direct" modifier for real-time access (not commit/update). For example: "read,direct"

CryptoKeyStore.performAction Method

Performs a custom action and returns its result.

Syntax

async cryptokeystore.performAction(action : string, param : string): Promise<string>

Remarks

Use this method to perform secondary actions not available via the default API.

CryptoKeyStore.removeKey Method

Removes a key from the storage.

Syntax

async cryptokeystore.removeKey(index : number): Promise<void>

Remarks

Use this method to remove a key from the storage by its index.

CryptoKeyStore.removeKeys Method

Removes a subset of keys from the storage by their IDs.

Syntax

async cryptokeystore.removeKeys(IDs : string): Promise<void>

Remarks

Use this method to remove a selection of keys from the storage by their IDs. Pass comma-separated IDs or ":selected:" to remove the selected keys.

CryptoKeyStore.removeObject Method

Removes an object from the storage.

Syntax

async cryptokeystore.removeObject(index : number): Promise<void>

Remarks

Use this method to remove an object from the storage by its index.

CryptoKeyStore.removeObjects Method

Removes a subset of objects from the storage by their IDs.

Syntax

async cryptokeystore.removeObjects(IDs : string): Promise<void>

Remarks

Use this method to remove a selection of objects from the storage by their IDs. Pass comma-separated IDs or ":selected:" to remove the objects previously selected.

CryptoKeyStore.select Method

Allows the selection of keys from the store.

Syntax

async cryptokeystore.select(filter : string, selectKeys : boolean, selectObjects : boolean, maxCount : number): Promise<string>

Remarks

This function allows the user to select keys from the storage by applying a Filter. MaxCount limits the number of objects and keys selected. If not all objects and keys were returned because of the MaxCount limit, the method returns a "select token" that can be used to continue the search. Pass it as a filter to obtain the next portion of the list.

CryptoKeyStore.setKeyParam Method

Sets an algorithm-specific key parameter.

Syntax

async cryptokeystore.setKeyParam(name : string, value : Uint8Array): Promise<void>

Remarks

Use this method to set an algorithm-specific key parameter.

CryptoKeyStore.setKeyParamStr Method

Sets an algorithm-specific key parameter.

Syntax

async cryptokeystore.setKeyParamStr(name : string, valueStr : string): Promise<void>

Remarks

Use this method to set an algorithm-specific key parameter provided in a string.

CryptoKeyStore.setObjectParam Method

Sets an algorithm-specific object parameter.

Syntax

async cryptokeystore.setObjectParam(name : string, value : Uint8Array): Promise<void>

Remarks

Use this method to set an algorithm-specific object parameter.

CryptoKeyStore.setObjectParamStr Method

Sets an algorithm-specific object parameter.

Syntax

async cryptokeystore.setObjectParamStr(name : string, valueStr : string): Promise<void>

Remarks

Use this method to set an algorithm-specific object parameter provided in a string.

CryptoKeyStore.unlock Method

Unlocks the store previously locked with the Lock method.

Syntax

async cryptokeystore.unlock(token : string): Promise<void>

Remarks

This operation may not be supported by all store types. Pass the lock token obtained from the Lock method as parameter to this method.

CryptoKeyStore.update Method

Performs an Update operation on the store, obtaining the up-to-date view of it.

Syntax

async cryptokeystore.update(): Promise<void>

Remarks

This operation invalidates any key and data objects previously obtained from the store.

CryptoKeyStore.updateKey Method

Performs an Update operation on the pinned key.

Syntax

async cryptokeystore.updateKey(): Promise<void>

Remarks

TBD

CryptoKeyStore.updateObject Method

Performs an Update operation on the pinned object.

Syntax

async cryptokeystore.updateObject(): Promise<void>

Remarks

TBD

CryptoKeyStore.AttestationRecord Event

Passes an attestation record to the user code.

Syntax

cryptokeystore.on('AttestationRecord', listener: (e: {readonly operation: string, readonly opId: string, readonly attRec: string}) => void )

Remarks

This event can fire repeatedly during the operation to pass any attestation records to the component user.

The data returned via this event can be saved and used as evidence of the operation performed.

CryptoKeyStore.ClientAuth Event

Notifies the application that the service requested an authentication credential from the client.

Syntax

cryptokeystore.on('ClientAuth', listener: (e: {readonly operation: string, readonly opId: string, readonly authTypes: string, accept: boolean}) => void )

Remarks

AuthTypes contain a list of supported/suggested authentication methods. Use the CryptoChannel object to adjust authentication parameters.

This event can fire repeatedly during an operation, reflecting multi-factor authentication stages.

CryptoKeyStore.ClientAuthFailed Event

Notifies the application about the failure of attempted authentication type.

Syntax

cryptokeystore.on('ClientAuthFailed', listener: (e: {readonly operation: string, readonly opId: string, readonly authType: string, retry: boolean}) => void )

Remarks

AuthType contain the authentication method that failed.

Set Retry to true to try again (subject to service acceptance).

CryptoKeyStore.Error Event

Information about errors during data delivery.

Syntax

cryptokeystore.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

CryptoKeyStore.Notification Event

This event notifies the application about an underlying control flow event.

Syntax

cryptokeystore.on('Notification', listener: (e: {readonly eventID: string, readonly eventParam: string}) => void )

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

CryptoKeyStore.OperationFinish Event

Reports the completion of data processing operation.

Syntax

cryptokeystore.on('OperationFinish', listener: (e: {readonly operation: string, readonly opId: string}) => void )

Remarks

This event fires when the cryptographic operation has completed.

CryptoKeyStore.OperationStart Event

Reports the start of data processing operation.

Syntax

cryptokeystore.on('OperationStart', listener: (e: {readonly operation: string, readonly opId: string, cancel: boolean}) => void )

Remarks

This event fires when the cryptographic operation is about to start.

Use the Cancel parameter to cancel the operation.

CryptoKeyStore.Progress Event

Reports the data encryption/decryption progress.

Syntax

cryptokeystore.on('Progress', listener: (e: {readonly operation: string, readonly opId: string, readonly total: number, readonly current: number, cancel: boolean}) => void )

Remarks

This event fires periodically during a file encrypt/decrypt operation to report its progress.

Use the Cancel parameter to terminate the encryption/decryption if needed.

CryptoKeyStore.ServiceAuth Event

Notifies about the start of service authentication.

Syntax

cryptokeystore.on('ServiceAuth', listener: (e: {readonly operation: string, readonly opId: string, readonly authType: string, readonly authID: string, readonly authToken: string, accept: boolean}) => void )

Remarks

Subscribe to this event to respond to service authentication and validate credentials as required.

This event can fire repeatedly during an operation, reflecting multi-factor authentication stages.

CryptoKeyStore.ServiceAuthFailed Event

Notifies about the failure of service authentication attempt.

Syntax

cryptokeystore.on('ServiceAuthFailed', listener: (e: {readonly operation: string, readonly opId: string, readonly authType: string, readonly authID: string}) => void )

Remarks

Subscribe to this event to track service authentication failures.

CryptoChannel Type

This container represents security and authentication parameters for accessing the storage.

Remarks

Use the properties of this object to tune up security, authentication, and authorization parameters.

Fields

public CryptoChannel();

Constructors

public CryptoKey();

Creates an empty crypto key object.

CryptoMechanism Type

This container represents a cryptographic mechanism information.

Remarks

This type is a universal placeholder for cryptographic mechanisms.

Fields

public CryptoMechanism();

Constructors

public CryptoObject();

Creates an empty crypto object.

CryptoParam Type

A simple name-value pair object.

Remarks

The class represents a name-value string pair used in a variety of network components.

Fields

public CryptoParam(String name, String value);

Creates a name-value pair from a name and a value.

public CryptoParam();

Creates an empty name-value object.

CryptoSession Type

Contains information about a crypto keystore connection.

Remarks

Use this property to check various details of the keystore connection.

Fields

public CryptoSession();

Config Settings (class pkiproxy.cryptokeystore)

CryptoKeyStore Config Settings

Trappable Errors (class pkiproxy.cryptokeystore)

CryptoKeyStore Errors