First, this walk-through will explain how to set up your system so that it has a working framework and WBC-based decryption application on your ARM board. The next section will then explain in detail how the renewable aspects of this system work. This code is based on Dusan Klinec's WBC code. The original readme file associated with that repo can be found in README-Dusan-Klinec.md.
This is basically setting up the ASPIRE Framework repo and checking out this repository in the correct location.
$ git clone https://github.com/aspire-fp7/framework
$ cd framework/
$ ./setup.sh
[...]
Would you like to include the anti_debugging protection? (y/N) N
$ cd projects/
$ git clone https://github.com/aspire-fp7/wbc
$ cd wbc
The next few steps will be automated in the future. For now, you'll need to perform a few manual steps to prepare everything:
$ wget https://www.shoup.net/ntl/ntl-10.3.0.tar.gz
$ tar zxvf ntl-10.3.0.tar.gz
$ cd ntl-10.3.0/src/
$ NTL_INSTALL_PREFIX=${PWD}/../install--ntl-diablo-x86-native
$ ./configure PREFIX=${NTL_INSTALL_PREFIX} CXX=g++ "CXXFLAGS=-g -O2" SHARED=on
$ make
$ make install
$ cd ../..
Now we will create the binary that will be run on our host to both create and re-randomize WBC tables, and to encrypt content with those tables.
$ cmake -DBUILD_DECRYPT_ONLY=OFF -DBUILD_MAIN=ON -DNTL_INCLUDE_PATH=${NTL_INSTALL_PREFIX}/include/ -DNTL_LIB=${NTL_INSTALL_PREFIX}/lib/libntl.so.33 "-DCMAKE_EXE_LINKER_FLAGS=-lgmp -lz" .
$ make
Because we'll be using this file inside of our ACTC Docker environment, which might have a different version of boost, and needs to refer to the NTL libraries, we copy those to the current directory:
$ cp ntl-10.3.0/src/.libs/*so* .
$ cp /usr/lib/x86_64-linux-gnu/libboost_* .
(Once these steps are automated in a Docker, this last step should become obsolete.)
Now we'll use our tool to generate both a binary version and a C header file containing WBC tables:
$ ./main --decrypt --extEnc=0 --create-table WBTables
AES key to use: 2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c
Table output file given: WBTables
External coding will be used: 0
Generating WB-AES instance (encryption)...
Generating WB-AES instance (decryption)...
Generating AES tables took: [5] seconds
We can then use the same tool to encrypt /etc/passwd:
$ ./main --decrypt=0 --extEnc=0 --load-tables WBTables.binary --out-file encrypted.inputfile.todecode --input-files /etc/passwd
Output file given: encrypted.inputfile.todecode
Table input file given: WBTables.binary
Input file /etc/passwd
Generating External encoding, identity: 0...
Loading stored AES tables: 0
Loading AES tables took: [0] seconds
Going to encrypt file [/etc/passwd] with WBAES
Finished reading the file
Encryption ended in [0]s; Pure encryption took [0.002211] s (clock call); time: [0] s; encrypted [182] blocks
Our decryption application that will be run on the ARM board has only the basic functionality embedded in its main file (decrypt-only.cpp), as opposed to the many-featured main file on our host. The decryption functionality is located in decrypt-fn.cpp's decrypt_fn function, which basically includes the WBTables.h C header file that was generated by the ./main --create-tables from the earlier step. This function is furthermore annotated with
_Pragma("ASPIRE begin protection(publicwbc,renewable)")
_Pragma("ASPIRE end")
This indicates to the ACTC that this is renewable WBC.
Now it's time to actually create this decryption application with the ACTC:
$ ../../docker/run.sh -d -f /projects/wbc/actc/actc.json
[...]
APPLICATION ID = DD828419B231A2BC565199D897832E42
. SERVER_RENEWABILITY_CREATE
register_app /projects/wbc/actc/build/actc/.server_renewability_create
/opt/renewability/scripts/create_new_application.sh -a DD828419B231A2BC565199D897832E42 && touch /projects/wbc/actc/build/actc/.server_renewability_create
. SERVER_RENEWABILITY_POLICY
set_policy /projects/wbc/actc/build/actc/.server_renewability_policy
/opt/renewability/scripts/set_application_policy.sh -a DD828419B231A2BC565199D897832E42 -d 5 -m 0 -r /projects/wbc/actc/build/actc/BC05/generate_blocks_wbc.sh && touch /projects/wbc/actc/build/actc/.server_renewability_policy
[...]
The DD828419B231A2BC565199D897832E42 is the application id, where we will later verify that the diversified mobile blocks are created into.
First, copy both the encrypted file and the decryption tool to our ARM board:
$ scp encrypted.inputfile.todecode ARMboard:
$ scp actc/build/actc/BC05/wbc ARMboard:
When running the decryption tool on your ARM board, it will automatically decrypt encrypted.inputfile.todecode into decrypted_file
$ ssh ARMboard
ARMboard:~$ ./wbc
[...debugging output of the online code manager...]
Input file encrypted.inputfile.todecode
Going to decrypt file [encrypted.inputfile.todecode] with WBAES
Finished reading the file
Encryption ended in [0]s; Pure encryption took [0.195877] s (clock call); time: [0] s; encrypted [182] blocks
ARMboard:~$ cat decrypted_file
root:x:0:0:root:/root:/bin/bash
[...]
We have two different ways in which we can diversify our mobile WBC code. The first one is by diversifying the binary ARM code that is part of the mobile block. This is the default manner in which our mobile blocks are renewed, this is not limited to the WBC code. The second one is by re-randomizing the WBC tables themselves, and sending the updated tables over to the client. Both are orthogonal to each other. This walk-through will illustrate both in the following two subsections.
By default, the renewability manager is instructed to renew (and diversify) blocks every 5 seconds during the execution of the program. This is configurable with the set_application_policy.sh script, which is already called with that 5 second default when the project is initially built (as can be seen in the output earlier in this walk-through). Furthermore, the renewability manager can be instructed that a client should acknowledge that it has dropped the code, and this can then be made to interact with the mobility server as a reaction mechanism.
You can easily observe the code diversification as follows. First, prepare a larger file to decrypt on your ARM board, so that it will take more than 5 seconds to decrypt it. (For example, a 100MiB file filled with zeroes might work well, depending on your board.)
On your host, go into your ACTC Docker:
$ docker-compose exec actc bash
First observe that there is already a first set of mobile blocks (in our case consisting of only a single block) generated, in the directory based on our application's APPLICATION_ID:
# ls /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/
mobile_dump_00000000 mobile_dump_00000000.metadata source.txt
# md5sum /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
76c7625db2a81200b6f3c54a36528d71 /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
The 00000000 indicates the revision of this set of mobile blocks. In this case, there is only our initial set of mobile blocks.
While running your (now long-running) decryption code on your ARM board, you can study different log files on the Docker:
/opt/online_backends/code_mobility/mobility_server.logshows the interactions the code mobility server has with its clients. In doing so, it also logs the path to the mobile block which is served, including its revision./opt/online_backends/renewability/renewability_manager.logshows the interactions the renewability manager has with its clients. This also logs the policies of the active clients, when the manager decides that a new set of revisions should be generated, how these are generated, etc.
By default the client code injected in the ARM applicatien outputs some debug information, that additionally shows when it is instructed to clear its code cache, and fetch new a new set of blocks. Thus, after a while, you can observe:
On the ARM board:
[1592922349:6092] NOTICE: ACCL - Data received from server, invoking the callback
[1592922349:6092] NOTICE: RENEWABILITY callback invoked. 520 520[1592922349:6092] NOTICE: RENEWABILITY callback invoked. type=1
[1592922349:6092] NOTICE: RENEWABILITY RN_RENEW_ALLBLOCKS received
[1592922349:6092] NOTICE: RENEWABILITY all blocks erased
This indicates that the renewability manager instructed this client to clear its code cache, so that it is forced to fetch renewed blocks.
In the renewability log:
[RN_MANAGER] Checking policies for app DD828419B231A2BC565199D897832E42...
[RN_MANAGER] * Policy found (revision duration: 5s, mandatory: 1)
[RN_MANAGER] ** Renewal needed due to application 'DD828419B231A2BC565199D897832E42' policy (Timeout: 5, Elapsed: 6).
[RN_MANAGER] New revision number: 00000001.
[RN_MANAGER] Executing renew script: /opt/renewability/scripts/create_new_revision.sh -a DD828419B231A2BC565199D897832E42 -r 00000001 -o /projects/wbc/actc/build/actc/BC05/generate_blocks_wbc.sh -f 1592922314 -t 1592922379
[RN_MANAGER] Renew script returned: 0 (0 expected)
This indicates that the renewability manager decided to create a new revision at that point.
In the code mobility log:
[Code Mobility Server] Actual revision for app_id DD828419B231A2BC565199D897832E42 is 00000002
[Code Mobility Server] BLOCK_ID 0 requested
[Code Mobility Server] BLOCK_ID 0 (filename: /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000002/mobile_dump_00000000) is going to be served.
[Code Mobility Server] BLOCK_ID 0 is 1196264 bytes long.
[Code Mobility Server] BLOCK_ID 0 correctly sent to ASPIRE Portal.
Which shows that the mobile block with id 0 from revision 00000002 was sent to the client.
Finally, you can also observe this in the directories and file which were generated:
# ls /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/
00000000 00000001 00000002 00000003 00000004 00000005
# md5sum /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/*/mobile_dump_00000000
76c7625db2a81200b6f3c54a36528d71 /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
2192c359f30a3d408e5cb09ab277ddfe /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000001/mobile_dump_00000000
37e8998a157d2ec9a1e8a88b641d83d0 /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000002/mobile_dump_00000000
1bc42280b0fc352352fff82a7b28aa4c /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000003/mobile_dump_00000000
00603adb7936895fec569197ad944dbf /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000004/mobile_dump_00000000
bf340ea2f62d55e3af527d38749fa287 /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000005/mobile_dump_00000000
Which shows that the contents of those blocks changes between the sets.
We also support re-randomizing the WBC tables, and then updating the mobile blocks associated with the WBC tables, so that those re-randomized blocks are sent to the client. This is orthogonal to diversifying the code itself. Thus, we can choose to only diversify the code (the default), only diversify the WBC tables, or even both. This explanation will focus on diversifying the WBC table.
Our framework automatically generates a script (partially based on the ACTC config, of course) you can call to regenerate the tables. The script is named after the object file in which the table is located. Thus, in our case, the script can be found as /projects/wbc/actc/build/actc/SC12_R/renew_decrypt-fn.sh. It takes only a single argument, which is the directory in which the mobile WBC block is located that needs to be updated. (You could have multiple mobile WBC Tables, they can be updated independently, a specfic script will automatically patch only the block which belongs to the object file for which that script was generated.)
By default, the mobile code of set 00000000 will be sent to a client. Thus, to re-randomize that WBC table (and showing that it has indeed changed):
# md5sum /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
76c7625db2a81200b6f3c54a36528d71 /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
# /projects/wbc/actc/build/actc/SC12_R/renew_decrypt-fn.sh /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/
AES key to use: 2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c
Table output file given: WBTables
[...]
# md5sum /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
00fa4d60bc17f0ce09a4da6e19d9d13d /opt/online_backends/DD828419B231A2BC565199D897832E42/code_mobility/00000000/mobile_dump_00000000
The script will automatically compile the updated table, and inject that table in the pre-existing associated mobile block. Running the wbc decryption code on your ARM board will automatically use this new table (you can check this in the output of the code mobility server), and the output of the decryption will still be correct.
If you want to automatically update the WBC tables together with the diversification of its code during the execution of a program, you can do this by editing the renewability script for the application to suit your exact needs. This script renewability is registered by the set_application_policy.sh script as /projects/wbc/actc/build/actc/BC05/generate_blocks_wbc.sh.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent