Crypto Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

pkiproxy.crypto()

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.

Crypto.BlockSize Property

The block size of the chosen symmetric cipher.

Syntax

 getBlockSize(): number;

Default Value

0

Remarks

This property returns the block size of the chosen symmetric cipher.

Modern symmetric algorithms typically use blocks of 16 bytes. Some older algorithms, such as DES or Blowfish, use 8-byte blocks.

This property is read-only.

Crypto.CanEncrypt Property

Returns true if the crypto object can be used for encryption.

Syntax

 isCanEncrypt(): boolean;

Default Value

FALSE

Remarks

This property returns true if the crypto object can be used for encryption and decryption. This capability depends on the cryptographic algorithm.

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

Crypto.CanSign Property

Returns true if the crypto object is capable of data signing.

Syntax

 isCanSign(): boolean;

Default Value

FALSE

Remarks

This property returns true if the crypto object can be used for signing data and validating signatures. This capability depends on the cryptographic algorithm.

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

Crypto.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.

Crypto.CryptoKey Property

The key to employ for the crypto operation.

Syntax

 getCryptoKey(): CryptoKey;

 setCryptoKey(cryptoKey: CryptoKey): void;

Default Value

Remarks

Use this property to specify the key to perform the crypto operation with.

Please note that the key assigned should be of a proper type (a public key, not a symmetric key),have a proper set of capabilities (signing and/or encryption), and include its private partfor signing and decryption operations.

This property is not available at design time.

Crypto.InputEncoding Property

The encoding to apply to the input data.

Syntax

 getInputEncoding(): CryptoInputEncodings;

 setInputEncoding(inputEncoding: CryptoInputEncodings): void;

enum CryptoInputEncodings {
  cetDefault,
  cetBinary,
  cetBase64,
  cetCompact,
  cetJSON
}

Default Value

0

Remarks

Use this property to specify the encoding to apply to the input data.

Crypto.InputIsHash Property

Indicates whether the input data contains the hash or the actual data.

Syntax

 isInputIsHash(): boolean;

 setInputIsHash(inputIsHash: boolean): void;

Default Value

FALSE

Remarks

Set this property to true to tell the class that the data you are passing to it is the hash of the data, rather than the actual (unhashed) data. If this property is set to false, class will hash the provided data internally if it is assumed by the algorithm.

This property is not available at design time.

Crypto.KeySize Property

Returns the cryptographic key size in bytes.

Syntax

 getKeySize(): number;

Default Value

0

Remarks

Use this property to read the cryptographic key size. For the majority of the symmetric algorithms this is hard-coded in the algorithm itself (such as 16 bytes for AES128), but may be variable for certain exceptions, such as Blowfish or RC4.

This property is read-only.

Crypto.Mechanism Property

The security mechanism to be used during the crypto operation.

Syntax

 getMechanism(): string;

 setMechanism(mechanism: string): void;

Default Value

"sha256WithRSAEncryption"

Remarks

Use this property to provide the name of the algorithm, in the form supported by the key store, that should be used for the cryptographic operation. If left empty, the default algorithm (deducible from the key) will be used.

Crypto.Nonce Property

Specifies the Nonce value to employ.

Syntax

 getNonce(): Uint8Array;

 setNonce(nonce: Uint8Array): void;

Remarks

Use this property to specify the Nonce value for the symmetric operation. Not every algorithm or modeuses nonce.

This property is not available at design time.

Crypto.OutputEncoding Property

The encoding type to apply to the output data.

Syntax

 getOutputEncoding(): CryptoOutputEncodings;

 setOutputEncoding(outputEncoding: CryptoOutputEncodings): void;

enum CryptoOutputEncodings {
  cetDefault,
  cetBinary,
  cetBase64,
  cetCompact,
  cetJSON
}

Default Value

0

Remarks

Use this property to specify the encoding type to apply to the protected data.

Crypto.Padding Property

The padding type to apply to the encrypted data.

Syntax

 getPadding(): CryptoPaddings;

 setPadding(padding: CryptoPaddings): void;

enum CryptoPaddings {
  scpNone,
  scpPKCS5,
  scpANSIX923
}

Default Value

1

Remarks

Use this property to specify the padding type to use with the encrypted data. A paddingtype commonly used in modern security environments is PKCS#5.

Crypto.Pars Property

Contains a list of operation parameters.

Syntax

 getPars(): CryptoParamList;

Default Value

Remarks

Use this property to adjust the operation parameters, such as AssociatedData, PayloadSize, or TagSize for AEAD, or SaltSize for PSS.

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

Crypto.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.

Crypto.SignatureValidationResult Property

The signature validation result.

Syntax

 getSignatureValidationResult(): CryptoSignatureValidationResults;



enum CryptoSignatureValidationResults {
  svtValid,
  svtUnknown,
  svtCorrupted,
  svtSignerNotFound,
  svtFailure
}

Default Value

1

Remarks

Use this property to check the result of the most recent signature validation.

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

Crypto.StreamCipher Property

Returns true if the selected algorithms works as a stream cipher.

Syntax

 isStreamCipher(): boolean;

Default Value

FALSE

Remarks

This property returns true if the selected algorithm processes data as a stream (byte-by-byte), rather than block-by-block. This affects the need to use a proper padding settings.

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

Crypto.SymmetricMode Property

Specifies the symmetric cipher mode of operation.

Syntax

 getSymmetricMode(): CryptoSymmetricModes;

 setSymmetricMode(symmetricMode: CryptoSymmetricModes): void;

enum CryptoSymmetricModes {
  scmDefault,
  scmECB,
  scmCBC,
  scmCTR,
  scmCFB8,
  scmGCM,
  scmCCM,
  scmPoly1305
}

Default Value

0

Remarks

Use this property to specify the mode of operation as required by your environment. The defaultsetting is CBC.

Crypto.UserId Property

TBD.

Syntax

 getUserId(): string;

 setUserId(userId: string): void;

Default Value

""

Remarks

TBD

This property is not available at design time.

Crypto.UserKeySecret Property

TBD.

Syntax

 getUserKeySecret(): string;

 setUserKeySecret(userKeySecret: string): void;

Default Value

""

Remarks

TBD

This property is not available at design time.

Crypto.config Method

Sets or retrieves a configuration setting.

Syntax

async crypto.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.

Crypto.decrypt Method

Decrypts a buffer.

Syntax

async crypto.decrypt(buffer : Uint8Array): Promise<Uint8Array>

Remarks

Use this method to decrypt a byte array and get the encrypted message in another byte array.

Specify the decryption key in CryptoKey property before calling this method.

Crypto.decryptFile Method

Decrypts a file.

Syntax

async crypto.decryptFile(sourceFile : string, destFile : string): Promise<void>

Remarks

Use this method to decrypt an encrypted file and save the decrypted data to another file.

Specify the decryption key in CryptoKey property before calling this method.

Crypto.decryptFinal Method

Finalization of decryption by blocks.

Syntax

async crypto.decryptFinal(): Promise<Uint8Array>

Remarks

Use this method to finalize of decryption by blocks.

Specify decryption key in CryptoKey property.

Crypto.decryptInit Method

Initializes a per-block decryption process.

Syntax

async crypto.decryptInit(): Promise<void>

Remarks

Use this method to start a block-by-block decryption process.

Specify the decryption key in CryptoKey property before starting the decryption.

Crypto.decryptUpdate Method

Decrypts the next block of encrypted data.

Syntax

async crypto.decryptUpdate(buffer : Uint8Array): Promise<Uint8Array>

Remarks

When using block-by-block decryption, pass every subsequent block of the encryptedmessage to this method until the entire message is processed. For each encryptedblock the method returns a piece of decrypted data.

Please note that in general case there is no direct correspondence between the data actuallycontained in the encrypted block with the output of this method. The component maychoose to cache a piece of the provided buffer internally if it doesn't constitutea full block of encrypted data.

Remember to call DecryptInit before calling this method to prepare the controlfor the decryption process.

Crypto.encrypt Method

Encrypts a buffer.

Syntax

async crypto.encrypt(buffer : Uint8Array): Promise<Uint8Array>

Remarks

Use this method to encrypt a byte array and get the protected message in another byte array.

Specify the encryption key in the CryptoKey property before commencing encryption.

Crypto.encryptFile Method

Encrypts a file.

Syntax

async crypto.encryptFile(sourceFile : string, destFile : string): Promise<void>

Remarks

Use this method to encrypt a file and save the protected message to another file.

Specify the encryption key in CryptoKey property before commencing encryption.

Crypto.encryptFinal Method

Finalization of encryption by blocks.

Syntax

async crypto.encryptFinal(): Promise<Uint8Array>

Remarks

Use this method to finalize of encryption by blocks.

Specify encryption key in CryptoKey property.

Crypto.encryptInit Method

Initializes a per-block encryption process.

Syntax

async crypto.encryptInit(): Promise<void>

Remarks

Use this method to initialize a block-by-block encryption process. Follow it with calls to EncryptUpdate (as many as needed), and complete the encryptionwith an EncryptFinal call.

Specify the encryption key in CryptoKey property before calling this method.

Crypto.encryptUpdate Method

Encrypts the next block of data.

Syntax

async crypto.encryptUpdate(buffer : Uint8Array): Promise<Uint8Array>

Remarks

Use this method to encrypt the next block of data contained in Buffer.

Call this method after calling EncryptInit for as many times as needed, until the wholevolume of data is processed. Having done that, call EncryptFinal to complete the encryptionand get the terminating encrypted trailer.

Crypto.hash Method

Calculates a message digest over a byte array.

Syntax

async crypto.hash(buffer : Uint8Array): Promise<Uint8Array>

Remarks

This method calculates and returns a message digest over the content of Buffer. This is a quick way to calculate a hash over a byte array in one go.

Crypto.hashFile Method

Calculates a message digest over data contained in a file.

Syntax

async crypto.hashFile(sourceFile : string): Promise<Uint8Array>

Remarks

This method calculates and returns a message digest over the data contained in file SourceFile. This is a quick way to calculate a hash over a file content in one go.

Crypto.hashFinal Method

Completes the hash and returns the resulting message digest.

Syntax

async crypto.hashFinal(): Promise<Uint8Array>

Remarks

This method finalizes the hashing operation and returns the message digest of the input data. Use it in conjunction with HashInit and HashUpdate methods to process data in chunks.

Crypto.hashInit Method

Resets the hash function context.

Syntax

async crypto.hashInit(): Promise<void>

Remarks

HashInit resets the context of the hash function, discarding any data passed to it previously.

Use this method to restart the hash calculation process from scratch.

Crypto.hashUpdate Method

Feeds a chunk of data to the hash function.

Syntax

async crypto.hashUpdate(buffer : Uint8Array): Promise<void>

Remarks

This method feeds Buffer to the hash function. Call this methodrepeatedly to pass your data to the hash function chunk by chunk.

Remember to initialize the hash function with a HashInit call beforestarting to feed data with this method. After the whole volume ofdata has been sent, complete the calculation and obtain the resultingmessage digest with a HashFinal call.

Crypto.performAction Method

Performs a custom action and returns its result.

Syntax

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

Remarks

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

Crypto.randomGenerate Method

Generates an array of random bytes.

Syntax

async crypto.randomGenerate(len : number): Promise<Uint8Array>

Remarks

Call this method to generate an array of random bytes of length Len.

Crypto.randomSeed Method

Seeds the generator with a data in a byte array.

Syntax

async crypto.randomSeed(value : Uint8Array): Promise<void>

Remarks

Use this method to seed the generator with data provided in a byte array.

Crypto.sign Method

Signs a buffer.

Syntax

async crypto.sign(buffer : Uint8Array, detached : boolean): Promise<Uint8Array>

Remarks

Use this method to sign a byte array and get the protected message in another byte array. Set the Detached parameter to false to create an enveloped/enveloping, rather than detached signature.Please note that certain signature algorithms/kinds only support detached signing.

Specify the signing key in CryptoKey property before commencing the signing.

Please note that the key assigned must have a private key part.

Crypto.signFile Method

Signs a file.

Syntax

async crypto.signFile(sourceFile : string, destFile : string, detached : boolean): Promise<void>

Remarks

Use this method to sign a file and save the protected message to another file.

Specify the signing key in CryptoKey property before the signing. Please make sure the assigned key has a private key associated with it.

Set Detached parameter to false to create an enveloped/enveloping signature. This maynot be supported by certain algorithms or encryption modes.

Crypto.signFinal Method

Finalizes the multi-step signing operation.

Syntax

async crypto.signFinal(): Promise<Uint8Array>

Remarks

Use this method to finalize the multi-block signing.

Crypto.signInit Method

Initializes a per-block signing process.

Syntax

async crypto.signInit(detached : boolean): Promise<void>

Remarks

Use this method to start a block-by-block signing process.

Specify the signing key in CryptoKey property before starting the signing.

Crypto.signUpdate Method

Sends the next block of data for signing.

Syntax

async crypto.signUpdate(buffer : Uint8Array): Promise<Uint8Array>

Remarks

TBD

Crypto.verify Method

Verifies an enveloped or enveloping signature contained in a buffer.

Syntax

async crypto.verify(buffer : Uint8Array): Promise<Uint8Array>

Remarks

Use this method to verify an enveloped or enveloping signature contained in a byte array.The method verifies the signature and extracts the original signed content intoanother byte array.

The validation result is stored in SignatureValidationResult property.

Use VerifyDetached to verify detached signatures.

Specify the verification key in the CryptoKey property before commencing verification.

Crypto.verifyDetached Method

Verifies a detached signature.

Syntax

async crypto.verifyDetached(signedData : Uint8Array, signature : Uint8Array): Promise<void>

Remarks

Use this method to verify a detached signature. Pass the original message via the SignedData parameter, and the signature via the Signature parameter.

The validation result is stored in SignatureValidationResult property.

Provide the verification key in CryptoKey property before commencing verification.

Crypto.verifyDetachedFile Method

Verifies a detached signature.

Syntax

async crypto.verifyDetachedFile(signedDataFile : string, signatureFile : string): Promise<void>

Remarks

Use this method to verify a detached signature. Pass the original data via the SignedDataFile parameter, and the signature via the SignatureFileparameter.

The validation result is stored in SignatureValidationResult property.

Provide the verification key in CryptoKey property.

Crypto.verifyDetachedFinal Method

Finalizes the multi-step detached verification operation.

Syntax

async crypto.verifyDetachedFinal(): Promise<void>

Remarks

Use this method to finalize the multi-block verification.

Crypto.verifyDetachedInit Method

Initiates multi-step verification of a detached signature.

Syntax

async crypto.verifyDetachedInit(signature : Uint8Array): Promise<void>

Remarks

TBD

Crypto.verifyDetachedUpdate Method

Sends a data block for detached signature verification.

Syntax

async crypto.verifyDetachedUpdate(signedDataBlock : Uint8Array): Promise<void>

Remarks

TBD

Crypto.verifyFile Method

Verifies an enveloped or enveloping signature contained in a file.

Syntax

async crypto.verifyFile(sourceFile : string, destFile : string): Promise<void>

Remarks

Use this method to verify an enveloped or enveloping signature and extract the original signed message to another file.

The validation result is stored in SignatureValidationResult property.

Specify the public verification key in CryptoKey property before commencing the validation.

Crypto.verifyFinal Method

Finalizes the multi-step verification operation.

Syntax

async crypto.verifyFinal(): Promise<Uint8Array>

Remarks

Use this method to finalize the multi-block verification.

Crypto.verifyInit Method

Initializes a per-block verification process.

Syntax

async crypto.verifyInit(): Promise<void>

Remarks

Use this method to start a block-by-block verification process.

Specify the signing key in CryptoKey property before starting the signing.

Crypto.verifyUpdate Method

Sends the next block of data for verification.

Syntax

async crypto.verifyUpdate(buffer : Uint8Array): Promise<Uint8Array>

Remarks

TBD

Crypto.AttestationRecord Event

Passes an attestation record to the user code.

Syntax

crypto.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.

Crypto.ClientAuth Event

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

Syntax

crypto.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.

Crypto.ClientAuthFailed Event

Notifies the application about the failure of attempted authentication type.

Syntax

crypto.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).

Crypto.Error Event

Information about errors during data delivery.

Syntax

crypto.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.

Crypto.Notification Event

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

Syntax

crypto.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.

Crypto.OperationFinish Event

Reports the completion of data processing operation.

Syntax

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

Remarks

This event fires when the cryptographic operation has completed.

Crypto.OperationStart Event

Reports the start of data processing operation.

Syntax

crypto.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.

Crypto.Progress Event

Reports the data encryption/decryption progress.

Syntax

crypto.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.

Crypto.ServiceAuth Event

Notifies about the start of service authentication.

Syntax

crypto.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.

Crypto.ServiceAuthFailed Event

Notifies about the failure of service authentication attempt.

Syntax

crypto.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.

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.crypto)

Crypto Config Settings

Trappable Errors (class pkiproxy.crypto)

Crypto Errors