Syntax

Result = ToringoRSA.Encrypt(SourceMB, ByRef TargetMB, PublicKey)

OR

Result = ToringoRSA.Encrypt(SourceStr, ByRef TargetStr, PublicKey)

Part	Type	Description
PublicKey	String	The public key used to encrypt SourceMB or SourceStr . Actually it's a big hexadecimal integer. Since the integer is too large to store in any numerical variable, type String is used to store it. PublicKey should be the public key of the pair of cipher keys acquired by using GetRandomKeys method. Encrypt method will decide the strength (currently 128, 256, 512 and 1024 bits are supported) of encryption according to the digits of the big integer that parameter PublicKey represents.
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, TargetMB or TargetStr returns the result of encryption. 1 - The parameter SourceMB or SourceStr passed is inaccessible, empty or illegally formatted. 2 - Cannot write data into TargetMB or TargetStr . 3 - The content of SourceMB or SourceStr is too much, so that the superfluous content is neglected and TargetMB or TargetStr returns the result for the first part of SourceMB or SourceStr . 4 - The parameter PublicKey passed is too long, too short or illegally formatted (characters except "0-9", "a-f" and "A-F" are included). 7 - Other error occurred, usually you won't get this result, and generally TargetMB or TargetStr returns a Nil Memoryblock or an empty string ("").
SourceMB	MemoryBlock	Data stored in MemoryBlock to encrypt. The length limit of SourceMB are as following: For 128 bit encryption, length should be no more than 15 bytes; For 256 bit encryption, length should be no more than 31 bytes; For 512 bit encryption, length should be no more than 63 bytes; For 1024 bit encryption, length should be no more than 127 bytes. Content exceeded the limits will be truncated during encryption.
SourceStr	String	A string made up of hex characters (should only include "0-9", "a-f" and "A-F") to encrypt. The length limit of SourceStr are as following: For 128 bit encryption, length should be no more than 30 characters; For 256 bit encryption, length should be no more than 62 characters; For 512 bit encryption, length should be no more than 126 characters; For 1024 bit encryption, length should be no more than 254 characters. Content exceeded the limits will be truncated during encryption.
TargetMB	MemoryBlock	Result of encryption, its content is a string made up of hex characters.
TargetStr	String	Result of encryption, a String made up of hex characters ("0-9" and "A-F").

Notes

Unsymmetrical encryption algorithms including RSA are slower. Usually they are used to encrypt/decrypt important data (such as the password used in symmetrical encryption algorithms such as DES and AES). Encrypting hundreds of KB or several MB of data at one time will make your program cannot respond in a long time.

As a result, unlike the Encrypt method of ToringoDES module, Encrypt method of this module won't divide data into many little pieces and encrypt them one by one, instead it will only encrypt the first part of data inside length limit. Therefore, if you want to encrypt data longer than the limited length, please write code to divide it into several segments for separated encryption, and then merge the encrypted results. You can refer to "RSA_Tool.rbp" in Examples folder, which is an example for encrypting ordinary text or hex characters of any length. Besides, Encrypt method of this module doesn't provide the function to encrypt files directly, either.

RSA algorithm treats both cipher keys and data to encrypt/decrypt as big integers, and make no effect for zeros. If the data to encrypt is a string made up of zeros (such as "000000") or a MemoryBlock made up of NULL bytes, the result of encryption will be a character "0" (for TargetStr ) or a NULL byte (for TargetMB ).

Example

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

See Also

Decrypt and GetRandomKeys methods of ToringoRSA Module; Encrypt Method of ToringoDES Module.

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

Syntax

Result = ToringoRSA.Decrypt(SourceMB, ByRef TargetMB, PublicKey,
PrivateKey)

OR

Result = ToringoRSA.Decrypt(SourceStr, ByRef TargetStr, PublicKey,
PrivateKey)

Part	Type	Description
PrivateKey	String	The private key used to decrypt SourceMB or SourceStr . Actually it's a big hexadecimal integer. Since the integer is too large to store in any numerical variable, type String is used to store it. PrivateKey should be the private key of the pair of cipher keys acquired by using GetRandomKeys method. Decrypt method will decide the way (128, 256, 512 and 1024 bits) of decryption according to the digits of the big integer that PrivateKey and PublicKey represent.
PublicKey	String	The public key used to decrypt SourceMB or SourceStr , which should be the same as the PublicKey parameter passed when using Encrypt method. Actually PublicKey is a big integer in hex. Since the integer is too large to store in any numerical variable, type String is used to store it. PublicKey should be the public key of the pair of cipher keys acquired by using GetRandomKeys method. Decrypt method will decide the way (128, 256, 512 and 1024 bits) of decryption according to the digits of the big integer that PrivateKey and PublicKey represent.
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, TargetMB or TargetStr returns the result of encryption. 1 - The parameter SourceMB or SourceStr passed is inaccessible, empty or illegally formatted. 2 - Cannot write data into TargetMB or TargetStr. 3 - The content of parameter SourceMB or SourceStr is too much, so that the superfluous content will be neglected. It tries to decrypt the first part of SourceMB or SourceStr and succeed. 4 - PrivateKey and/or PublicKey is too long, too short, illegally formatted (characters except "0-9", "a-f" and "A-F" are included) or invalid (For example, PrivateKey is greater than PublicKey ). 7 - An uncertain error occurred: usually occurs when PublicKey and SourceMB / SourceStr don't fit the restriction required by RSA algorithm. In this case, it's hard to know the key is wrong or the source is invalid. Generally TargetMB or TargetStr returns a Nil Memoryblock or a empty string ("").
SourceMB	MemoryBlock	Data stored in MemoryBlock to decrypt. Its content is a string made up of hex characters, which actually represents a big integer and should be smaller than PublicKey .
SourceStr	String	A string made up of hex characters (should only include "0-9", "a-f" and "A-F") to decrypt. It actually represents a big integer and should be smaller than PublicKey .
TargetMB	MemoryBlock	Result of decryption, a MemoryBlock.
TargetStr	String	Result of encryption, a String made up of hex characters ("0-9" and "A-F").

Notes

Just like the ToringoRSA.Encrypt method, Decrypt method won't divide data into many little pieces and decrypt them one by one, instead it will only decrypt the first part of data inside length limit.

RSA algorithm treats both cipher keys and data to encrypt/decrypt as big integers. If the data to encrypt is a string started with zeros ("0") or a MemoryBlock started with NULL bytes, all these zeros or NULL bytes will be lost after decrypting. You can either record the length of the data to encrypt before encrypting, and add enough zeros/NULL bytes after decrypting (Please refer to the first example of Example section), or insert a non-zero character / a non-NULL byte in the front of data to encrypt, and remove it after decrypting.

When using the String version of Decrypt method, characters "A-F" in the result of decryption ( TargetStr) will be represented in uppercase, even if lowercase letters are passed to SourceStr when encrypting.

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 uses 512 bits RSA encryption algorithm to encrypt the randomly generated 48 characters in hexadecimal, then decrypt them and show the result of decryption.

// generate random data Dim r as New Random Dim MB as New MemoryBlock(48) For ByteIndex As Integer=0 to 47     Select Case r.InRange(0,4)     Case 0 to 2         MB.byte(ByteIndex)=r.InRange(48,57) // 1-9     Case 3,4         MB.byte(ByteIndex)=r.InRange(65,70) // A-F     End Select Next   // store the data to a string Dim EncryptSource As String EncryptSource = MB.StringValue(0,MB.Size)   // generate a pair of cipher keys randomly Dim PublicKey, PrivateKey As String Dim ResultCode As Integer ResultCode = ToringoRSA.GetRandomKeys(PublicKey,PrivateKey,ToringoRSA.RSA512)   Dim EncryptTarget As String Dim DecryptTarget As String   If ResultCode=0 Then     // encrypt     ResultCode=ToringoRSA.Encrypt(EncryptSource,EncryptTarget,PublicKey)     If ResultCode<>0 Then Return       // decrypt     ResultCode=ToringoRSA. Decrypt (EncryptTarget,DecryptTarget,PublicKey,PrivateKey)     If ResultCode=0 Then          // insert zeros to the beginning of the string if they are lost          While Len(DecryptTarget)<48               DecryptTarget="0"+DecryptTarget          Wend           // display the result         MsgBox DecryptTarget     End If End If

This example uses 1024 bits RSA encryption algorithm to encrypt the text of an EditField -- EncryptField, and show the result of decryption in DecryptField.

// store the text to a MemoryBlock Dim EncryptSource As MemoryBlock EncryptSource = NewMemoryBlock (LenB(EncryptField.Text)) EncryptSource.StringValue(0,EncryptSource.Size)=EncryptField.Text   // generate a pair of cipher keys randomly Dim PublicKey, PrivateKey As String Dim ResultCode As Integer ResultCode = ToringoRSA.GetRandomKeys(PublicKey,PrivateKey,ToringoRSA.RSA1024)   Dim EncryptTarget As MemoryBlock Dim DecryptTarget As MemoryBlock   If ResultCode=0 Then     // encrypt     ResultCode=ToringoRSA.Encrypt(EncryptSource,EncryptTarget,PublicKey)     If ResultCode<>0 and ResultCode<>3 Then Return       // decrypt     ResultCode=ToringoRSA. Decrypt (EncryptTarget,DecryptTarget,PublicKey,PrivateKey)     If ResultCode=0 Then         // display the result in DecryptField         DecryptField.Text=DecryptTarget.StringValue(0,DecryptTarget.Size). _         DefineEncoding(Encodings.UTF8)     End If End If

For more examples, please refer to "RSA_Tool.rbp" in Examples folder.

See Also

Encrypt and GetRandomKeys methods of ToringoRSA Module.

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

Notes

RSA arithmetic can be used to sign and verify a little piece of data (such as a serial number / license key, or a hash / digest of a file). It requires that the data to sign (for Sign method, the HexStr parameter) should be smaller than the public key, otherwise unexpectable result will be returned. Also, if HexStr is too close to PublicKey , for example, only one or two less than PublicKey , the Signature returned is possible the same as HexStr .

Example

Please refer to the Example section of ToringoRSA.Verify method.

See Also

Verify and GetRandomKeys methods of ToringoRSA Module.
 

Syntax

Result = ToringoRSA.Verify(Signature, ByRef HexStr, PublicKey)

Part	Type	Description
HexStr	String	The original string returned. It’s made up of hex characters (should only include “0-9”, “a-f” and “A-F”). It actually represents a big integer. Typically, it’s the hash or digest of a file or a piece of date which you want to sign and verify.
PublicKey	String	The public key used when generating the Signature . Actually PublicKey is a big integer in hex. Since the integer is too large to store in any numerical variable, String type is used. PublicKey should be the public key of the pair of cipher keys acquired by using GetRandomKeys method.
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, HexStr returns the original string signed. 1 - The parameter Signature passed is empty or has non-hex characters. 3 - Signature is greater than PublicKey . HexStr won’t be returned. 4 - The parameter PublicKey passed is too long, too short or illegally formatted (characters except “0-9”, “a-f” and “A-F” are included). 7 - Other error occurred, usually you won’t get this result. HexStr will return an empty string ("") in this case.
Signature	String	The signature returned by Sign function to verify, a hex string.

Notes

Typically, if you want to sign a file or a piece of data, you will:

1. Generate the hash or digest of the file/data;

2. Generate a pair of public key and private key, and ensure the public key greater than the hash/digest;

3. Send you public key to any person you like;

4. Sign the hash/digest with the public and private keys via ToringoRSA.Sign method. Then send the file with the signature to someone else.

To verify it, the person who received them will:

1. Pass the signature and the public key to Verify method to get the hash/digest back;

2. Generate a hash/digest of the file/data again;

3. Compare the values got in above 2 steps. If they are the same, he/she can be sure that the file is intact and it’s the original file/data sent by you -- no one has intercepted and modified it or feign you to send it, as long as no one else knows your private key.

Example

Please refer to “RSASigningFile.rbp” in Examples folder. It can be used to sign and verify files via ToringoRSA module and REALbasic built-in MD5 method.

In that project, there is a module called “SignModule”, which can be reused directly. Sign / Verify method of ToringoRSA module and REALbasic’s MD5 method are wrapped within it.

In the SignModule, there are two methods for you to use:

SignFile(f As FolderItem, PublicKey As String, PrivateKey As String) As String

f: the file to sign

PublicKey/PrivateKey: the cipher keys used with RSA arithmetic. RSA requires that the big integer (such as the hash value of a file) to handle should be smaller than the public key. Since MD5 is a 128 bits hash/digest, passing keys whose length are 256 bits or above to this method will be safe. To generate a pair of keys for RSA arithmetic, use ToringoRSA.GetRandomKeys .

Return value: the signature of the file returned. Actually, it's the RSA signature of the MD5 digest of the file passed.

VerifyFile (f As FolderItem, Signature As String, PublicKey As String) As Boolean

f: the file to verify

Signature: the signature of the file.

PublicKey: the public key used when signing the file. Of course, private key is unnecessary for verifying, only the person signs the file knows it.

Return value: if the file and the signature are matched, return True, otherwise, return False.
 

Syntax

Result = ToringoRSA.Decrypt(ByRef PublicKey, ByRef PrivateKey[, Mode])

Part	Type	Description
Mode	Integer	Decides the length of cipher keys to get (128, 256, 512 or 1024 bits). The default mode is RSA 128. Please set this parameter by passing a Mode constant.
PrivateKey	String	The private key for decryption. It is actually a big hexadecimal integer.
PublicKey	String	The public key for encryption and decryption. It is actually a big integer in hex.
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, returns the cipher keys. 5 - A wrong value passed for Mode, and returns 128 bits cipher keys. 7 - Other error occurred, usually you won't get this result.

Notes

Before encrypting, please use this method to get a pair of public key and private key. You can call this method to get a pair of cipher keys automatically in runtime, or you can get them in advance and write these keys into the program as constants or variables. To use which way depends on the purpose of your application.

Example

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

See Also

Encrypt and Decrypt methods and Mode constants of ToringoRSA Module.
 

Constant

Use the following contants to set the Mode parameter of GetRandomKeys method.

Name	Value	Description
RSA128	128	128 bits
RSA256	256	256 bits
RSA512	512	512 bits
RSA1024	1024	1024 bits

Notes

We recommend that you use the name of a constant to set the Mode parameter of GetRandomKeys method, instead of using the value of any constant directly. The scope of those constants is the module, so "ToringoRSA." should be added to them as prefix when using.

Example

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

See Also

GetRandomKeys Method of ToringoRSA Module.