Syntax

Result = ToringoDES.Encrypt(SourceFile, TargetFile, Password)

OR

Result = ToringoDES.Encrypt(SourceMB, ByRef TargetMB, Password)

Part	Type	Description
Result	Integer	Returns an integer to determine the reason of failure or state of execution. You can compare it with the following values (called Result Code): 0 - Success, the data encrypted (cipher) has been written to TargetMB or the file that TargetFile refers to. 1 - Source is not readable: SourceFile or SourceMB is empty, nonexistent/Nil or inaccessible, or SourceFile refers to a folder. Encryption failed. 2 - Target is not writeable: TargetFile is read-only (or SourceFile and TargetFile refer to the same file), or TargetFile refers to a folder, or TargetMB is locked. Encryption has failed. 4 - The length or format of Password is illegal for encryption. 7 - Other error occurred, usually you won't get this result. It's very important to test the value of Result after calling the Encrypt method. You'd better not operate further on TargetFile or TargetMB unless Result is 0, otherwise an exception may occur.
SourceFile	FolderItem	File to encrypt.
SourceMB	MemoryBlock	MemoryBlock to encrypt.
TargetFile	FolderItem	File used to save the data encrypted.
TargetMB	MemoryBlock	MemoryBlock used to save the data encrypted.
Password	String	Password to encrypt data. To encrypt with DES, please pass a string consisted of 8 bytes or 16 Hex characters (for the latter, should only contains "0-9","a-f" and "A-F"). To encrypt with TDEA, please pass a string consisted of 24 bytes or 48 Hex characters. Passing string at other length or 16/48 non-Hex characters, encryption will fail.

Notes

Like the Checksum method of ToringoCRC module, although the type of parameters SourceFile and TargetFile is FolderItem, they should only be passed as FolderItems that refer to files. Encrypt method cannot cope with folder or bundle (it maybe work on Linux, but it's not recommended). Encrypt method isn't designed to encrypt large file fast. Like ToringoCRC.Checksum , in theory this method doesn't support file larger than 4 GB, and its executing speed also depends on the disk and file system you use, and other system factors.

Algorithm DES/TDEA is usually used to encrypt text, since this method supports MemoryBlock object in REALbasic, you can also use it to encrypt other type (even mixed types) of data which can be filled in MemoryBlock.

The password of DES is 56 bits (namely 7 bytes). However, the password should be 8 bytes for the last bit of every byte won't be used. For programs of 21st century, obviously the encryption of 56 bits isn't strong enough. Your are recommended to use TDEA. The password of TDEA is 168 bits, that is 21 bytes. For the same reason, a 24-byte password is needed. You may see Triple-DES only needs 112-bit effective password. To be compatible with this "Triple-DES" algorithm, you can simply set the first and last 8-byte of the 24-byte password (or the first and last 16 characters for hex string version) to the same content. When the first, middle and last 8 bytes (or 16 characters) are exactly the same, TDEA and DES are compatible. But it's meaningless, since it will be a lot slower in speed than using an ordinary DES.

You can use 16/48 Hex characters to replace 8/24 bytes as password. If you use any 8-byte text or 16 Hex characters, this method will automatically select DES for encryption; if you use any 24-byte text or 48 Hex characters, this method will automatically select TDEA for encryption. For applications require user to set the password, support of regular text as password offers convenience for you. If your programs doesn't need user to input password directly, support of Hex characters as password offers more flexibility.

Although this method uses algorithm that fits FIPS and ANSI standard (only ECB mode is supported currently), it may not be compatible with other DES function libraries or encryption tools for little difference in data handling.

Example

Please refer to the Example section of ToringoDES.Decrypt method.

See Also

Decrypt Method of ToringoDES Module; Checksum Method of ToringoCRC Module.

Other keywords mentioned are built-in items of REALbasic, please refer to their entries in REALbasic's Language Reference.
 

Syntax

Result = ToringoDES.Decrypt(SourceFile, TargetFile, Password)

OR

Result = ToringoDES.Decrypt(SourceMB, ByRef TargetMB, Password)

Part	Type	Description
Result	Integer	Returns an integer to determine the reason of failure or state of execution. You can compare it with the following values (called Result Code): 0 - Success, the data decrypted has been written to TargetMB or the file that TargetFile refers to. 1 - Source is not readable: SourceFile or SourceMB is empty, nonexistent/Nil or inaccessible, or SourceFile refers to a folder. Decryption has failed. 2 - Target is not writeable: TargetFile is read-only (or SourceFile and TargetFile refer to the same file), or TargetFile refers to a folder, or TargetMB is locked. Decryption has failed. 4 - The length or format of Password is illegal for decryption. 7 - Other error occurred, usually you won't get this result. It's very important to test the value of Result after calling the Decrypt method. You'd better not operate further on TargetFile or TargetMB unless Result is 0, otherwise an exception may occur. Besides, you also should test if TargetMB is Nil, which may occur when the password is wrong and the content to decrypt is less than 8 bytes, even if zero is returned.
SourceFile	FolderItem	File to decrypt.
SourceMB	MemoryBlock	MemoryBlock to decrypt.
TargetFile	FolderItem	File used to save the data decrypted.
TargetMB	MemoryBlock	MemoryBlock used to save the data decrypted.
Password	String	Password to decrypt data. To decrypt with DES, please pass a string consisted of 8 bytes or 16 Hex characters (for the latter, should only contains "0-9","a-f" and "A-F"). To decrypt with TDEA, please pass a string consisted of 24 bytes or 48 Hex characters. Passing string at other length or 16/48 non-Hex string, decryption will fail.

Notes

Like Encrypt method, although the type of parameters SourceFile and TargetFile are FolderItems, they should only be passed FolderItems that refer to files. Decrypt method cannot cope with folder or bundle.

When using the MemoryBlock version of Decrypt method, if the content stored in the TargetMB is a string, before displaying it, you may need to use REALbasic built-in DefineEncoding method to set the encoding of the string (The encoding of text created inside REALbasic is UTF-8). Please refer to the second example of Example section.

Example

This example use DES to encrypt a file with the specified password, and then decrypt the encrypted file.

Dim f As FolderItem f = GetFolderItem("File.txt")   Dim fEn As FolderItem fEn = GetFolderItem("EncryptedFile.txt")   // encrypt Dim Password As String = "13B834E9AD9385C6" Dim ResultCode As Integer ResultCode=ToringoDES.Encrypt(f,fEn,Password)   If fEn.exists=False Or ResultCode<> 0 Then     Msgbox "Failed! Result Code: " + Str(ResultCode)     Return End If   // decrypt Dim fDe As FolderItem fDe = GetFolderItem("DecryptedFile.txt") ResultCode=ToringoDES. Decrypt (fEn,fDe,Password)   If fDe.exists=False Or ResultCode<> 0 Then     Msgbox "Failed! Result Code: " + Str(ResultCode) End If

The following example uses TDEA to encrypt the text in an EditField, and display cipher in another EditField, then decrypt the encrypted content and display the result. To use this example, you need to add 3 EditFields, EdfTextToEncrpt, EdfCipher and EdfPassword and a PushButton onto the window, and copy the following code into Action event handle of the PushButton.

Dim TextLenthInByte As Integer TextLenthInByte = LenB(EdfTextToEncrpt.Text)   Dim MBToEncrypt As MemoryBlock MBToEncrypt = NewMemoryBlock(TextLenthInByte) MBToEncrypt.StringValue(0,TextLenthInByte) = EdfTextToEncrpt.Text   // encrypt Dim MBForCipher As MemoryBlock Dim ResultCode As Integer ResultCode = ToringoDES.Encrypt(MBToEncrypt,MBForCipher,EdfPassword.Text)   If ResultCode=0 then     EdfCipher.Text = MBForCipher.StringValue(0,MBForCipher.Size) ElseIf ResultCode=4 then     MsgBox "The password you input is invalid." End if If ResultCode<>0 Then Return   // decrypt Dim MBToDecrypt As MemoryBlock ResultCode = ToringoDES. Decrypt (MBForCipher,MBToDecrypt,EdfPassword.Text)   Dim DecryptResult As String If ResultCode=0 And MBToDecrypt<>Nil then     If MBToDecrypt.Size=0 Then Return     DecryptResult=MBToDecrypt.StringValue(0,MBToDecrypt.Size)     MsgBox DecryptResult.DefineEncoding(Encodings.UTF8) // display the result End If

For more examples, please see "DES_TDEA_Tool.rbp" in Examples folder.

See Also

Encrypt Method of ToringoDES Module.

Other keywords mentioned are built-in items of REALbasic, please refer to their entries in REALbasic's Language Reference.