The keys

In EMA keys are binary files stored in directories. Each key or file actually contains two sub-keys half the size of the file. The first sub-key is used for the substitution/replacement stage and the second for the shuffling/Reordering stage. The files contain bytes that can have any of the 256 values in the ASCII code table. The length of the sub-key can be configured from 256 bytes to 4.194.304 bytes, and then the length of the key file can vary from 512 bytes to 8.388.608 bytes. Both the shorter and longer key can work indiscriminately with small or very large source data. For example, a key file of 8.388.608 bytes can encrypt both a 10-byte byte array and a 50 GB file. For the purposes of encryption and decryption, the only difference is that in the case of the byte array, the first 10 bytes of the file and the 10 bytes from index 4.194.304 to index 4.194.313 will be taken into account, while in the case of the 50 GB file it depends on the length of the byte block. If the configured byte block is longer than the key, all the 4.194.304 bytes of the two sub-keys will be used and then spread out to the end of the byte block size. For example, if the byte block has been configured with a size of 38.600.451 bytes, the sub-key will be fully used 9 times in a row and the last time only the first 851.715 bytes. If it is smaller, the reasoning done for the byte array applies.

The default size of the sub-key was set to 2.097.152 bytes so the key file is 4.194.304 bytes long.

512 bytes or 2.097.152 bytes for the sub-key size does not affect encryption/decryption performance.

Keys can be created by the method explained below. Alternatively, they can be created by other approaches. However, it is essential to follow the guideline that the key file must have an even number of elements, which must not be less than the minimum default value.

Clearly, regardless of the method employed to produce the key file, random numbers must be generated. It is common knowledge that generating completely random numbers is a complex task, which makes this aspect quite delicate.

The EMA program use the following Java Random class to get a random value

  • Random randomValue = new Random();

obtaining an array of values which are then shuffled is as follows:

  • Collections.shuffle(Arrays.asList(keyByteArray));

so the resulting key should be fairly random.

Configure the keys directory

Before generating a key, it is necessary to configure the key directory, otherwise an error will occur. The default path is empty.

Example of configuring the keys directory

  • setKeyFilesDirectory(“C:\\Users\\guest\\ema\\key\\”); // Windows style
  • setKeyFilesDirectory(“/home/guest/Documents/key/”); // Posix style
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2023.12.10 07:43:51.397 RUNNING setKeyFilesDirectory() :: 
2023.12.10 07:43:51.397   SETTING 'C:/Users/guest/ema/key/' as key files directory
Generating a key file

The following method is used to generate a key file ‘n’ bytes long to the specified setKeyFilesDirectory()

  • keyCreation(n, “”); // ‘n’ must be an even number and the size of each sub-key is ‘n/2’

To overwrite the directory specified by setKeyFilesDirectory():

  • keyCreation(n, “C:\\”);

To create a key file with the default size to the specified setKeyFilesDirectory()

  • keyCreation(0, “”); // 4.194.304 bytes long

In the above examples, the keys can have any value from 0 to 255.

If you do not want sub-key_1 to have a range of values, perform the method below before creating the key

  • addForbiddenValuesInKeyCreation(1, 36, 39); // sub-key_1 is not allowed to have a range values from 36 to 39

If you don’t want sub-key_2 to have only one value, use the method below before creating the key

  • addForbiddenValuesInKeyCreation(2, 0, 0); // sub-key_2 is not allowed to have the value of 0

Negative values, sub-key numbers other than 1 or 2, and sub-key values higher than 255 are not allowed.

Obviously, you can execute as many times as you wish for both sub-key_1 and sub-key_2, before to generate a key.

  • addForbiddenValuesInKeyCreation(1, 36, 39);
  • addForbiddenValuesInKeyCreation(1, 252, 254);
  • addForbiddenValuesInKeyCreation(2, 1, 1);
  • addForbiddenValuesInKeyCreation(1, 36, 39);
  • addForbiddenValuesInKeyCreation(2, 86, 101);
  • addForbiddenValuesInKeyCreation(2, 150, 193);
  • addForbiddenValuesInKeyCreation(1, 99, 120);
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING setKeyFilesDirectory() :: 
2024.03.06 09:47:00.693   SETTING 'C:\Users\guest\ema\key\' as keys files directory                                  
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '36' to '39' cannot be assigned to sub-key_1
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '252' to '254' cannot be assigned to sub-key_1
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '1' to '1' cannot be assigned to sub-key_2
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '36' to '39' cannot be assigned to sub-key_1
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '86' to '101' cannot be assigned to sub-key_2
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '150' to '193' cannot be assigned to sub-key_2
2024.03.06 09:47:00.693   
2024.03.06 09:47:00.693 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.03.06 09:47:00.693 RUNNING addForbiddenValuesInKeyCreation() :: 
2024.03.06 09:47:00.693   SETTING the forbidden values from '99' to '120' cannot be assigned to sub-key_1
  • keyCreation(0, “”); // 0 is default and is 4.194.304-byte
2024.04.04 08:44:06.082 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:44:06.083 RUNNING keyCreation() :: 
2024.04.04 08:44:06.295   CREATING the key
2024.04.04 08:44:06.296   Naming type:  Random
2024.04.04 08:44:06.297   C:\Users\guest\ema\key\1712213046373340100_XFuNvPpK5NMRTeNKVPOULE4Jn7OS3tKu.key     4.194.304-byte
2024.04.04 08:44:06.297     sub-key_1: from index '0' to index '2.097.151'
2024.04.04 08:44:06.297     sub-key_2: from index '2.097.152' to index '4.194.304'
2024.04.04 08:44:06.336   
2024.04.04 08:44:06.336   This key adds 27199 random bytes to the top of pre-encryption data if origin data is a file
2024.04.04 08:44:06.337   and 849 random bytes to the top of pre-encryption data if origin data is a byte array
  • enableChecksumKeyName(); // default is random, if enabled default is MD5
  • setKeyNamingChecksumAlgorithm(2); // ‘MD5’ = 1, ‘SHA-1’ = 2, ‘SHA-256’ = 3 and ‘SHA-512’ = 4, default is ‘MD5’
  • keyCreation(55556); // 0 is default and is 4.194.304-byte
2024.04.04 08:45:10.890 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:45:10.891 RUNNING enableChecksumKeyName() :: 
2024.04.04 08:45:10.891   ENABLING checksum as key name
2024.04.04 08:45:10.892   
2024.04.04 08:45:10.892 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:45:10.892 RUNNING setKeyNamingChecksumAlgorithm() :: 
2024.04.04 08:45:10.893   SETTING checksum algorithm to 'SHA-1' as key naming
2024.04.04 08:45:10.893   
2024.04.04 08:45:10.894 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:45:10.894 RUNNING keyCreation() :: 
2024.04.04 08:45:10.919   CREATING the key
2024.04.04 08:45:10.919   Naming type: SHA-1 Checksum
2024.04.04 08:45:10.920   C:\Users\guest\ema\key\1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key
2024.04.04 08:45:10.920   Size = 55.556-byte
2024.04.04 08:45:10.921     sub-key_1: from index '0' to index '27.777'
2024.04.04 08:45:10.920     sub-key_2: from index '27.778' to index '55.556'
2024.04.04 08:45:10.925   
2024.04.04 08:45:10.925   This key adds 10297 random bytes to the top of pre-encryption data if origin data is a file
2024.04.04 08:45:10.926   and 321 random bytes to the top of pre-encryption data if origin data is a byte array
Examples of key filenames

The default key name is the current date in the format nanoseconds from 1970.01.01 + ‘_’ + 32 random characters from the string “0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvxywz” followed by the suffix ‘.key’ is as follow:

  • 1710499995215249800_NVYip61O6PEOVVyEa7VNgkwJIaRdszbJ.key

It can be modified by partially matching its checksum with one of the three allowed algorithms (MD5, SHA-256 and SHA-512) using the following methods:

  • enableChecksumKeyName();
  • setKeyNamingChecksumAlgorithm(1); // ‘MD5’ = 1, ‘SHA-1’ = 2, ‘SHA-256’ = 3 and ‘SHA-512’ = 4, default is ‘MD5’

To set the random file name again

  • enableRandomKeyName(); // default

A random key name

  • 1710499995215249800_NVYip61O6PEOVVyEa7VNgkwJIaRdszbJ.key

A MD5 checksum key name

  • 1710499995215249800_075dcc529ce0fe265729f0ccf3c5a4fd.key

A SHA-1 checksum key name

  • 1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key

A SHA-256 checksum key name

  • 1710499995215249800_41e169351ab5794a66c770f4f2389deba1b8f6a3e332a9f2eb3ffe7ce5b9cb48.key

A SHA-512 checksum key name

  • 1710499995215249800_08702ecebe3e95b0324668259a79ecc744422435db5c32765888a70a4de0bf13fe517c0a88cb65f3705655dd828b29f69008cf63cb5efc8ed73d6e8b01560ff4.key
The key first byte

The first byte of the key plays a special role, as it determines which algorithm will be used to calculate the key checksum and thus which string to include in the data header before encryption. The key’s hash is only used to verify its correctness for decryption. If a hash collision occurs, decryption will fail due to incorrect index calculations or incorrect checksum of the decrypted data.

  • If the first byte value ‘i’ (decimal with sign) is:

    1. >=0 i <64; (MD5 checksum)
    2. >=64 i <128; (SHA-1 checksum)
    3. >=128 i <191; (SHA-256 checksum)
    4. >=191 i <256; (SHA-512 checksum)
Setting a key

To encrypt, decrypt, view key values, or simply view information about an encrypted file, you need to set a key.

To set a key you need to pass its name

  • setKey(“1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key”);

In this case, the file must be placed or created in the designated directory using the

  • setKeyFilesDirectory(“C:\\Users\\guest\\ema\\key\\”);
2024.04.04 08:48:19.933 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:48:19.933 RUNNING setKeyFilename() :: 
2024.04.04 08:48:19.933   SETTING the key
2024.04.04 08:48:19.935   C:\Users\guest\ema\key\1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key
2024.04.04 08:48:19.935   Size = 55.556-byte
2024.04.04 08:48:19.936     sub-key_1: from index '0' to index '2.097.151'
2024.04.04 08:48:19.935     sub-key_2: from index '2.097.152' to index '4.194.304'
2024.04.04 08:48:19.956   
2024.04.04 08:48:19.957   This key adds 10297 random bytes to the top of pre-encryption data if origin data is a file
2024.04.04 08:48:19.957   and 321 random bytes to the top of pre-encryption data if origin data is a byte array

Or pass its absolutePath name. If a key has already been generated and saved on a storage device, you can also provide the absolute path without setting the keys folder is as follow:

  • setKeyFilesDirectory(“”); // default
  • setKey(“C:\\Users\\guest\\ema\\key\\1710489243724393900_7fUYuzFTd38UEAyqOvsxXW9YCmK67rXp.key”);

If you want to set a newly just generated key, the same session must be is active

  • setKey(“”);
Unset a key

To unset a key (only deselects a key, it does not delete it) you need to perform the following method:

  • unsetKey();

After removed a key, to provide a new encryption/decryption must set a new one.

Key and its SHA-512 checksum

When a key is set for encryption and decryption, its checksum is always calculated using the SHA-512 algorithm. It is necessary to calculate a variable number of random bytes that are added to the data to be encrypted. They vary from a minimum of 0 to a maximum of 32.768 bytes for file encryption and from 0 to a maximum of 1.024 bytes for byte array encryption. Take a look to detailed calculation of n1.

List the key values

To list by log the 1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key values from index 5 to index 20

  • keyPeeking(“1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key”, 5, 20); 
2024.04.04 08:50:01.551 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.04.04 08:50:01.551 RUNNING keyPeeking() :: 
2024.04.04 08:50:01.551   SETTING the key
2024.04.04 08:50:01.552   C:\Users\guest\ema\key\1712213110928004300_a7721cd837e1de1e5c0daec15bf4c13fca340142.key
2024.04.04 08:50:01.552   Size = 55.556-byte
2024.04.04 08:50:01.553     sub-key_1: from index '0' to index '2.097.151'
2024.04.04 08:50:01.553     sub-key_2: from index '2.097.152' to index '4.194.304'
2024.04.04 08:50:01.568   
2024.04.04 08:50:01.568   This key adds 10297 random bytes to the top of pre-encryption data if origin data is a file
2024.04.04 08:50:01.569   and 321 random bytes to the top of pre-encryption data if origin data is a byte array   
2024.04.04 08:50:01.569
2024.04.04 08:50:01.569   PEEK AT THE KEY
2024.04.04 08:50:01.570   Index        Signed  Unsigned
2024.04.04 08:50:01.570   -----------------------------
2024.04.04 08:50:01.570   000000005      -23      233
2024.04.04 08:50:01.571   000000006     -109      147
2024.04.04 08:50:01.571   000000007      -96      160
2024.04.04 08:50:01.572   000000008      -79      177
2024.04.04 08:50:01.572   000000009      -70      186
2024.04.04 08:50:01.573   000000010       10       10
2024.04.04 08:50:01.573   000000011      103      103
2024.04.04 08:50:01.574   000000012     -116      140
2024.04.04 08:50:01.574   000000013       96       96
2024.04.04 08:50:01.574   000000014       75       75
2024.04.04 08:50:01.575   000000015      -81      175
2024.04.04 08:50:01.575   000000016       -1      255
2024.04.04 08:50:01.576   000000017       -8      248
2024.04.04 08:50:01.576   000000018      -35      221
2024.04.04 08:50:01.576   000000019       61       61
2024.04.04 08:50:01.577   000000020       89       89

To display the values of a just freshly created key from index 125 to index 362 in the same Java session

  • keyPeeking(“”, 125, 362);

(from index) must be >= 0 and (to index) must be >= (from index). If (to index) = -1 it means the last value of the key.
Values from index 0 to index ((key length / 2) – 1) are assigned to sub-key_1, whereas values from index (key length / 2) to (key length – 1) are allocated to sub-key_2.

List the files in the directory for the designated keys.

To show the complete list of files in the keys directory

  • listKeyFiles(false); // file list only
2024.02.15 16:09:20.600 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.02.15 16:09:20.600 RUNNING listKeyFiles() :: 
2024.02.15 16:09:20.600   List of files in 'D:\Users\guest\ema\key\'
2024.02.15 16:09:20.601   ..................................................................................................
2024.02.15 16:09:20.601   1710499995215249800_sPFL0vCELCygGMS3qlvoNmQ1DdGguFx5.key                            4.194.304-byte
2024.02.15 16:09:20.602   1710499995215249801_LJ4urj0M40LocXiAPuj99y31W5mish8b.key                            4.194.304-byte
2024.02.15 16:09:20.602   1710499995215249802_OyQiYNVhgNXB7NKhYKjv7ewheiwb5WtF.key                            4.194.304-byte
2024.02.15 16:09:20.603   1710499995215249803_7NX9BWm1xP9o8pxIAJuMAEW6vyBpiTNJ.key                            4.194.304-byte
2024.02.15 16:09:20.603   1710499995215249804_bJY3eHubldFFzcc6Ev1i4B002pzskdBv.key                            4.194.304-byte
2024.02.15 16:09:20.604   1710499995215249805_4bIVi1nPXLs0wDiD9rXENgdwWHlU1jcv.key                            4.194.304-byte
2024.02.15 16:09:20.604   1710499995215249806_NdFkZJTGQ6Vhg0tNpdfKe6xxw1QLqvq7.key                            4.194.304-byte
2024.02.15 16:09:20.604   1710499995215249807_axhjn6whNN42DQgT3SLZNsdjA4b3MOw0.key                            4.194.304-byte
  • listKeyFiles(true); // file list with the checksum SHA-512
2024.02.15 16:06:40.443 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
2024.02.15 16:06:40.444 RUNNING listKeyFiles() :: 
2024.02.15 16:06:40.444   List of files in 'D:\Users\guest\ema\key\'
2024.02.15 16:06:40.444   ..................................................................................................
2024.02.15 16:06:40.458   1710499995215249800_sPFL0vCELCygGMS3qlvoNmQ1DdGguFx5.key                            4.194.304-byte
2024.02.15 16:06:40.529   Checksum SHA-512: ee2f33695e2b8d065d5ac4e8ed1426ed008fa428096de0dd9a7435c053ef7c7f5819229892f848ad
2024.02.15 16:06:40.529   2f0ccbbf156921917a662143e61f15f21535f4f8ef6aa5ba                                           
2024.02.15 16:06:40.529   ..................................................................................................
2024.02.15 16:06:40.530   1710499995215249801_LJ4urj0M40LocXiAPuj99y31W5mish8b.key                            4.194.304-byte
2024.02.15 16:06:40.569   Checksum SHA-512: 9a970eaaeaf89b71cb260f3d08c2f5881cbbe084d75230b87ad699ab4bab4da326b5070f9cec7fb4
2024.02.15 16:06:40.570   1dfc0d12787118a630612761975031dda2d77dbec1cfc3ea                                           
2024.02.15 16:06:40.570   ..................................................................................................
2024.02.15 16:06:40.571   1710499995215249802_OyQiYNVhgNXB7NKhYKjv7ewheiwb5WtF.key                            4.194.304-byte
2024.02.15 16:06:40.615   Checksum SHA-512: d6a78a5b28c49846edb592b6245d5b2099ca015fda9d35bf864c4c491c319b444c2ce88f92744784
2024.02.15 16:06:40.616   66d543004b61246f871868ece410d21258b611e9cee8b01e                                           
2024.02.15 16:06:40.616   ..................................................................................................
2024.02.15 16:06:40.617   1710499995215249803_7NX9BWm1xP9o8pxIAJuMAEW6vyBpiTNJ.key                            4.194.304-byte
2024.02.15 16:06:40.661   Checksum SHA-512: 073412a9058969e21a958a8090926bb3f44d88bb7d8cac1396c31397d86b3fb0ba629ef899b3d9d2
2024.02.15 16:06:40.662   05aeba1e014d5cd5ab25c9bfbe0be1e2247405263f93a0f7                                           
2024.02.15 16:06:40.663   ..................................................................................................
2024.02.15 16:06:40.663   1710499995215249804_bJY3eHubldFFzcc6Ev1i4B002pzskdBv.key                            4.194.304-byte
2024.02.15 16:06:40.711   Checksum SHA-512: a6935dca932c864a67efa1680d29af13dc00965e15b5aab18aa9b24022c9db5ae7ed55b737dd775d
2024.02.15 16:06:40.712   8f30df0f08e9ded97a9dbc493b353039b29bfd1ccb427248                                           
2024.02.15 16:06:40.713   ..................................................................................................
2024.02.15 16:06:40.713   1710499995215249805_4bIVi1nPXLs0wDiD9rXENgdwWHlU1jcv.key                            4.194.304-byte
2024.02.15 16:06:40.761   Checksum SHA-512: a1e0386796ceca3f5d3bea66928ae8c3efe062917ee651552efa45e39f6ae3930c4109f18244a5ae
2024.02.15 16:06:40.761   49736654f6828a7890dacae13fef36374b0d07c5ae08b7a6                                           
2024.02.15 16:06:40.761   ..................................................................................................
2024.02.15 16:06:40.762   1710499995215249806_NdFkZJTGQ6Vhg0tNpdfKe6xxw1QLqvq7.key                            4.194.304-byte
2024.02.15 16:06:40.807   Checksum SHA-512: 809647a2b6fd138a91f646d6dbabc9c863a31facf92ab33a17cb1678308f93262ab7dcc5c1cbb5ae
2024.02.15 16:06:40.808   14fdfdf548ea2ee3aa8f92e50d2a1213efd56ef939f183cc                                           
2024.02.15 16:06:40.808   ..................................................................................................
2024.02.15 16:06:40.808   1710499995215249807_axhjn6whNN42DQgT3SLZNsdjA4b3MOw0.key                            4.194.304-byte
2024.02.15 16:06:40.873   Checksum SHA-512: 73c9f0f8f5119b52d40d9fcf7005d077cdac6a8d103bf0675ee38e89e6fb64b05c8ee1a24fba2451
2024.02.15 16:06:40.873   e48603508afd0c52aaf0a833dae1a2456f936612a687685f
Scroll to Top