dataStore.provideDataKey( )

Home

4D v18.4


dataStore.provideDataKey ( curPassPhrase \| curDataKey ) -> Result

Parameter	Type	Description
curPassPhrase \| curDataKey	Text, Object	Current passphrase (text) or current data encryption key (object)
Result	Object	Result of the encryption key matching

Description

The dataStore.provideDataKey( ) method allows providing a data encryption key for the current data file of the datastore and detects if the key matches the encrypted data. This command can be used when opening an encrypted database, or when executing any encryption operation that requires the encryption key, such as re-encrypting the data file.

Notes:

The dataStore.provideDataKey( ) method must be called in an encrypted database. If it is called in a non-encrypted database, the error 2003 (the encryption key does not match the data.) is returned. Use the Data file encryption status command to determine if the database is encrypted.
The dataStore.provideDataKey( ) method cannot be called from a remote 4D or an encrypted remote datastore.

In the parameter, pass the curPassPhrase or curDataKey that matches the database:

curPassPhrase: String used to generate the data encryption key. When you use this parameter, an encryption key is generated.
curDataKey: Object (with encodedKey property) that contains the data encryption key. This key may have been generated with the New data key command.

If a valid data encryption key is provided, it is added to the keyChain in memory and the encryption mode is enabled:

all data modifications in encryptable tables are encrypted on disk (.4DD, .journal. 4Dindx files)
all data loaded from encryptable tables is decrypted in memory

Result

The result of the command is described in the returned object:

Property		Type	Description
success		Boolean	True if the provided encryption key matches the encrypted data, False otherwise

			Properties below are returned only if success is FALSE
status		Number	Error code (4 if the provided encryption key is wrong)
statusText		Text	Error message
errors		Collection	Stack of errors. The first error has the highest index
	[ ].componentSignature	Text	Internal component name
	[ ].errCode	Number	Error number
	[ ].message	Text	Error message

If no curPassphrase or curDataKey is given, dataStore.provideDataKey( ) returns null (no error is generated).

Example

 C_OBJECT($keyStatus)

 C_TEXT($passphrase)

 

 $passphrase:=Request("Enter the passphrase")

 If(OK=1)

    $keyStatus:=ds.provideDataKey($passphrase)

    If($keyStatus.success)

       ALERT("You have provided a valid encryption key")

    Else

       ALERT("You have provided an invalid encryption key, you will not be able to work with encrypted data")

    End if

 End if