├── README.md ├── default-uefi.xml ├── default.xml └── readme.txt /README.md: -------------------------------------------------------------------------------- 1 | DISCONTINUATION OF PROJECT. 2 | 3 | This project will no longer be maintained by Intel. 4 | 5 | Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project. 6 | 7 | Intel no longer accepts patches to this project. 8 | 9 | If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project. 10 | -------------------------------------------------------------------------------- /default-uefi.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /default.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /readme.txt: -------------------------------------------------------------------------------- 1 | ############################################################################### 2 | # Copyright (c) 2015 Intel Corporation 3 | # 4 | # Licensed under the Apache License, Version 2.0 (the "License"); 5 | # you may not use this file except in compliance with the License. 6 | # You may obtain a copy of the License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | # See the License for the specific language governing permissions and 14 | # limitations under the License. 15 | ############################################################################### 16 | 17 | This readme covers instructions for building and launching iKGT framework and 18 | example usage (integrity) components. 19 | 20 | ============================================================================= 21 | Release Notes 22 | ============================================================================= 23 | 24 | Release v1.2 (This release) 25 | ------------ 26 | 27 | (1) Support for UEFI boot 28 | 29 | Release v1.1 30 | ------------ 31 | 32 | (1) Support for booting iKGT with TXT/tboot 33 | (2) Hypercall interface and in/out buffer security enhancemts 34 | (3) Log message enhancements and python script for instruction address 35 | attribution 36 | 37 | Release v1.0.1 38 | ------------ 39 | 40 | (1) Added fix for CoreOS. 41 | 42 | Release v1.0 43 | ------------ 44 | 45 | (1) The current release v1.0 only supports monitoring of CR0, CR4 and limited 46 | set of MSRs. For details of which specific bits in CR0/CR4 and which MSRs 47 | are supported, refer to cr0_bits, cr4_bits, and msr_regs in driver/cr0.c, 48 | driver/cr4.c, and driver/msr.c respectively. 49 | 50 | (2) Monitoring of certain bits in CR0 and CR4 may cause system instability 51 | on certain platforms. For example, CR4.SMAP bit is supported only on 52 | 5th generation of Core i processors and enabling of the SMAP bit on 53 | system that has older version of the Core i processors may hang the 54 | system. 55 | 56 | ============================================================================= 57 | Content of the Source Package 58 | ============================================================================= 59 | 60 | ikgt/ 61 | +---readme.txt /* this file */ 62 | +---xmon/ 63 | ¦ +---Makefile 64 | ¦ +---common/ /* common header files */ 65 | ¦ ¦ +---include/ 66 | ¦ ¦ +---... 67 | ¦ +---core/ /* generic xmon core */ 68 | ¦ ¦ +---common/ 69 | ¦ ¦ ¦ +---... 70 | ¦ ¦ +---include/ 71 | ¦ ¦ ¦ +---... 72 | ¦ ¦ +---vmexit/ 73 | ¦ ¦ ¦ +---... 74 | ¦ ¦ +---vmx/ 75 | ¦ ¦ ¦ +---... 76 | ¦ ¦ +---... 77 | ¦ +---api/ /* xmon API */ 78 | ¦ ¦ +---... 79 | ¦ +---package/ /* ikgt install/uninstall scripts */ 80 | ¦ ¦ +---... 81 | ¦ +---loader/ /* pre-os xmon loader */ 82 | ¦ ¦ +---... 83 | ¦ +---plugins/ /* xmon-plugin for supporting integrity use case */ 84 | ¦ +---ikgt-plugin 85 | ¦ +---... 86 | +---example-usage/ 87 | +---integrity/ 88 | +---Makefile 89 | +---policy/ /* example policy (.json) and install script */ 90 | ¦ +---... 91 | +---driver/ /* example driver to configure policy */ 92 | ¦ +---... 93 | +---handler/ /* example vmx-root policy plugin module */ 94 | +---... 95 | 96 | ============================================================================= 97 | Build environment 98 | ============================================================================= 99 | 100 | Ubuntu 12.04/14.04 64-bit 101 | Gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) 102 | 103 | ============================================================================= 104 | Target machine Configuration 105 | ============================================================================= 106 | 107 | The target machine is where iKGT is to be installed. 108 | 109 | (1) System Configuration 110 | 111 | - Intel Core i processors (3rd generation or newer) 112 | - OS: Linux (e.g. Ubuntu) 113 | - System memory: at least 2GB 114 | 115 | Note: For target machines with less than 2GB RAM, xmon launching may fail. 116 | Please refer to "Customization" section for more details. 117 | 118 | ============================================================================= 119 | Building iKGT binaries 120 | ============================================================================= 121 | 122 | The iKGT source can be obtained either from the download page of 01.org site 123 | or from the github source code repository. If you have downloaded the source 124 | package (i.e. ikgtsrcpkg.tar.gz) from 01.org page, you can skip step (1) 125 | below and start from step (2). 126 | 127 | On a Linux build machine, 128 | 129 | (0) One-time set up for new Linux system 130 | 131 | Get repo tool (make sure your proxy is setup correctly) 132 | $ mkdir ~/bin 133 | $ PATH=~/bin:$PATH 134 | $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo 135 | $ chmod a+x ~/bin/repo 136 | 137 | Install git 138 | $ sudo apt-get install git 139 | 140 | Note: If you want to load IKGT on UEFI platform, a few additional steps are 141 | required. Please refer to section Running IKGT on UEFI Platforms at 142 | the end of this document. 143 | 144 | (1) Clone the ikgt source files into a working directory (e.g. project) from 145 | GitHub 146 | $ mkdir project 147 | $ cd project 148 | 149 | To get release stable version, e.g. v1.2: 150 | 151 | $ repo init -u https://github.com/intel/ikgt-manifest.git -b release_1_2 152 | $ repo sync 153 | 154 | To get top of master (may not be stable) 155 | 156 | $ repo init -u https://github.com/intel/ikgt-manifest.git 157 | $ repo sync 158 | 159 | Note: If you want to use the UEFI loader, you need to use a different 160 | manifest file to down load UEFI preloader and UEFI xmon loader. 161 | Please refer to Running IKGT on UEFI Platforms section for details. 162 | 163 | (2) Build ikgt binaries: 164 | $ cd ikgt/example-usage/integrity 165 | $ make 166 | Or 167 | $ make debug=1 168 | 169 | Output files can be found in the directories shown below: 170 | 171 | ikgt/xmon/bin/linux/release/ikgt_pkg.bin - contains xmon loader, 172 | xmon and policy handler 173 | ikgt/example-usage/integrity/driver/ikgt_agent.ko - sample driver 174 | 175 | 176 | ============================================================================= 177 | Installing/running iKGT 178 | ============================================================================= 179 | 180 | Currently, xmon can be launched by the target system which uses GRUB loader 181 | (e.g. Ubuntu). To install xmon, 182 | 183 | (1) Type below commands: 184 | $ cd ikgt/xmon 185 | $ sudo make install 186 | or 187 | $ sudo make install debug=1 188 | 189 | This step will copy the ikgt binaries to /boot folder and update the GRUB 190 | configuration file for xmon boot. 191 | 192 | (2) Enable the GRUB menu countdown display so that it gives chance 193 | during boot to select boot entry. 194 | 195 | $ sudo vi /etc/default/grub 196 | 197 | Comment the following two lines with # 198 | GRUB_HIDDEN_TIMEOUT=0 199 | GRUB_HIDDEN_TIMEOUT_QUIET=true 200 | 201 | Modify the timeout value if necessary. 202 | GRUB_TIMEOUT=20 203 | 204 | Save the changes and quit. 205 | 206 | $ sudo update-grub 207 | 208 | This step is needed only when you want to have the chance to select the boot 209 | entry on the GRUB menu during the boot. 210 | 211 | (3) Reboot the system 212 | $ sudo reboot 213 | 214 | Linux should come up with xmon running under it in vmx-root 215 | 216 | ============================================================================= 217 | Verifying if iKGT is up and running 218 | ============================================================================= 219 | 220 | Check cpuid and verify Intel VT-x is being used. 221 | 222 | $ ikgt/xmon/package/check_vtx.sh 223 | 224 | If it returns "VTx is not available", it implies the processor VT-x 225 | feature is being used and this is expected when xmon is running. 226 | 227 | Check if xmon is running by executing the following utility: 228 | 229 | $ cd ikgt/xmon/package/check_ikgt 230 | $ make 231 | $ ./check_ikgt 232 | 233 | If xmon is running, the utility will print out "iKGT is running". 234 | Xmon runs silently under the existing OS de-privileging it. 235 | 236 | ============================================================================= 237 | Uninstalling iKGT 238 | ============================================================================= 239 | On the target machine, 240 | 241 | $ cd ikgt/xmon 242 | $ sudo make uninstall 243 | 244 | This command will delete "ikgt_pkg.bin" in /boot and "20_linux_xmon" 245 | in /etc/grub.d, restore the changes to grub configuration files. 246 | 247 | ============================================================================= 248 | Setting up for TXT/tboot & iKGT Boot-up 249 | ============================================================================= 250 | iKGT can be booted from tboot. Please follow the instruction below to install 251 | tboot and iKGT. 252 | 253 | (1) Hardware Setup 254 | 255 | - Intel Core i processors. 256 | - OS: Ubuntu 14.04/CentOS 7 257 | - Ensure the following options are enabled in the BIOS menu: 258 | 259 | TXT, VMX, HyperThread, TPM, and All CPU Cores 260 | 261 | (2) If iKGT has been installed previously, un-install in by following the 262 | "Uninstalling iKGT" 263 | 264 | (3) Getting packages & tboot sources 265 | 266 | Note: DO not install tboot by 'apt-get install tboot' command as the 267 | tboot installed by this way is 1.8.2, which has a bug to work with 268 | ikgt. 269 | 270 | a) Install dependencies 271 | 272 | $ sudo apt-get install tpm-tools openssl libssl-dev libtspi-dev 273 | 274 | Note: the above command is for Ubuntu system. For Cent OS, use yum. 275 | 276 | b) If installation of tpm-tools throws an error in trousers script then 277 | edit /etc/init.d/trousers file else jump to step d: 278 | 279 | log_daemon_msg "Starting $DESC" "$NAME" 280 | if [ ! -e /dev/tpm* ] 281 | then 282 | log_warning_msg "device driver not loaded, skipping." 283 | exit 0 284 | fi 285 | chown tss:tss /dev/tpm* 286 | chown -R tss:tss /var/lib/tpm 287 | start-stop-daemon --start --quiet --oknodo --pidfile /var/run/${NAME}.pid --user ${USER} --chuid ${USER} --exec ${DAEMON} -- ${DAEMON_OPTS} 288 | RETVAL="$?" 289 | log_end_msg $RETVAL 290 | [ "$RETVAL" = 0 ] && pidof $DAEMON > /var/run/${NAME}.pid 291 | exit $RETVAL 292 | ;; 293 | 294 | c) Remove the highlighted string in the file. Save and exit. Then 295 | execute, 296 | 297 | $ /etc/init.d/trousers start 298 | 299 | d) Get latest tboot code (1.8.3): 300 | 301 | $ hg clone http://hg.code.sf.net/p/tboot/code tboot-code 302 | 303 | (4) Building tboot 304 | 305 | $ cd tboot-code 306 | $ make 307 | 308 | (5) Installing tboot 309 | 310 | $ sudo make install 311 | 312 | (6) Getting the right SINIT 313 | 314 | a) Check status 315 | 316 | $ sudo txt-stat 317 | 318 | You can find device ID in following format: 319 | DIDVID: 0x0000001fa0008086 320 | vendor_id: 0x8086 321 | device_id: 0xa000 322 | revision_id: 0x1f 323 | 324 | b) Download the ACM from https://software.intel.com/en-us/articles/intel-trusted-execution-technology/ according to the device ID you got in last step.i 325 | 326 | c) Unzip and copy the ACM to /boot. You may need to test more than one 327 | latest sinit bin file to get the right one. 328 | 329 | d) Update grub. 330 | 331 | $ sudo update-grub 332 | 333 | (7) Testing TXT Boot 334 | 335 | a) Reboot the system. Select tboot in grub. Type below command to check 336 | if tboot is launched. 337 | 338 | $ sudo txt-stat | less 339 | 340 | You should find following words to indicate tboot was launched 341 | successfully: 342 | 343 | ************************************************* 344 | TXT measured launch: TRUE 345 | secrets flag set: TRUE 346 | ************************************************* 347 | 348 | (8) Installing iKGT 349 | 350 | Follow the steps "Installing/running iKGT" to install iKGT. 351 | 352 | (9) Booting with tboot and iKGT 353 | 354 | Reboot the system. In GRUB menu, choose the boot entry with tboot and iKGT. 355 | 356 | (10) Verifying tboot and iKGT 357 | 358 | Use below commands to verify tboot and iKGT boot-up were successful: 359 | 360 | $ sudo txt-stat | less 361 | $ ./check_ikgt 362 | 363 | ============================================================================= 364 | Setting up configfs and installing ikgt_agent.ko 365 | ============================================================================= 366 | 367 | Follow these steps to set up the configfs file system under /sys/kernel/config 368 | 369 | (1) $ sudo mkdir //sys/kernel/config 370 | 371 | If configfs driver is not installed: 372 | (2) sudo insmod \ 373 | /lib/modules//kernel/fs/configfs/configfs.ko 374 | 375 | (3) $ sudo mount -t configfs none /sys/kernel/config 376 | 377 | (4) $ sudo insmod ikgt_agent.ko 378 | 379 | After successful installation, the driver will create /sys/kernel/config/ikgt_agent 380 | as its configuration space. The resource to be monitored and policy actions can now 381 | be specified by creating directories and files in this space. 382 | 383 | ============================================================================== 384 | Installing example policy 385 | ============================================================================== 386 | Use python script to parse policy file and create configfs directories. 387 | The python script is under ikgt/example-usage/integrity/policy/parse_policy.py. 388 | 389 | sudo python parse_policy.py -f -b 390 | where 391 | is the JSON file, 392 | is the base directory under which the resource directories 393 | are to be created 394 | 395 | $ sudo python parse_policy.py -f policy.json -b /sys/kernel/config/ikgt_agent 396 | 397 | You can check the new entries in configfs by executing following command 398 | $ tree /sys/kernel/config 399 | 400 | Above command should create directories and files based on the contents 401 | of .json file. The example policy enables monitoring of following resources 402 | with actions as shown below: 403 | CR0:WP - LOG & ALLOW 404 | CR0:PG - LOG & SKIP 405 | CR4:PAE - LOG & SKIP 406 | MSR:EFER - LOG & SKIP 407 | 408 | ============================================================================= 409 | Testing policy enforcement 410 | ============================================================================= 411 | 412 | After the policy is successfully installed, all attempts to modify monitored 413 | resources will be controlled as per the actions specified against them. 414 | 415 | For example, if the OS tries to modify CR0:WP, the event will be logged 416 | but will be allowed. Similarly, if the OS tries to modify EFER, the event will 417 | be logged and the violating instruction will be skipped. 418 | 419 | The contents of the log can be seen in /sys/kernel/config/ikgt-agent/log/log.txt 420 | 421 | $cat /sys/kernel/config/ikgt_agent/log/log.txt 422 | 423 | cpu=0, sequence-number=19, resource-name=CR0, access=write, 424 | value=0x80050033, RIP=0x81055074, action=LOG_SKIP 425 | 426 | You can use the python script, parse_log.py, to get a more descriptive 427 | output of each event log entry. 428 | 429 | $ sudo python parse_log.py /sys/kernel/config/ikgt-agent/log/log.txt 430 | 431 | Example output: 432 | cpu=0, sequence-number=3, resource-name=msr[0xc0000080], access=write, 433 | value=0x00000d00ffffffff, RIP=0xffffffffc087b9f4, action=LOG_SKIP, 434 | caller_type=module, module-name=ikgt_test 435 | 436 | For detailed instructions on how to set up configfs space and how to interpret 437 | log entries, please refer to iKGT-user-guide. 438 | 439 | ============================================================================= 440 | Customization 441 | ============================================================================= 442 | 443 | XMON Loading Address 444 | -------------------- 445 | 446 | Currently the loading address for xmon loader is located at 0x10000000. 447 | The address may not available for some systems. To avoid unexpected behavior, 448 | verify if this address is available or not on your system as following. 449 | 450 | (1) Boot to GRUB menu 451 | 452 | (2) Press 'c' to grub command line when GRUB boot menu appears 453 | 454 | (3) Type the following command: 455 | 456 | # lsmmap 457 | 458 | (4) If 0x10000000 is not within an available RAM range, change this 459 | hardcoded value in xmon/loader/pre_os/build_xmon_pkg_linux.sh to an 460 | address that within any of the "available RAM" regions from lsmmap command. 461 | 462 | Note: whenever ikgt/loader/pre_os/build_xmon_pkg_linux.sh is modified, 463 | it is required to rebuild loader by rebuilding ikgt_pkg.bin. 464 | 465 | XMON Memory Size 466 | ---------------- 467 | 468 | The memory size used by XMON is hard-coded by xmon_mem_size to 6 MB. This 469 | works for typical desktops with 4-8 GB of RAM and 2-4 CPUs. If you wish to 470 | change this, please modify the value defined in 471 | pre_os/build_xmon_pkg_linux.sh build script. 472 | 473 | This can be adjusted upwards or downwards to accommodate different systems 474 | and usages. For example systems with large amount of RAM and CPUs will need 475 | more memory. For usages in embedded systems the value can similarly be 476 | adjusted downwards. Target system launch can fail due to lack of memory. 477 | 478 | ============================================================================= 479 | Known problems 480 | ============================================================================= 481 | 482 | (1) Dependency on *.h may not always be checked. 483 | Use "make clean" before rebuilding after modification of any 484 | header file. 485 | 486 | (2) Shutdown or reboot will lead to system hanging, if system was booted 487 | with tboot and iKGT. The issue will be fixed in future release. 488 | 489 | 490 | 491 | ============================================================================= 492 | Running IKGT on UEFI Platforms 493 | ============================================================================= 494 | 495 | Dev System Tool chain 496 | --------------------- 497 | 498 | Note: The current version of UEFI loader works only when built with a specific 499 | version of GCC tool-chain. Newer GCC versions have a linker issue that is 500 | currently under debug. On your Ubuntu dev system, make sure you install 501 | and use the right versions of tools as described below: 502 | 503 | Install gcc 4.6 504 | 505 | $ sudo apt-get update 506 | $ sudo apt-get install gcc-4.6 build-essential 507 | 508 | $ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.6 20 509 | $ sudo update-alternatives --config gcc 510 | 511 | $ gcc -v 512 | 513 | Install GNU Linker 2.22 514 | 515 | $ wget https://launchpad.net/ubuntu/+archive/primary/+files/binutils_2.22-6ubuntu1.3_amd64.deb 516 | $ sudo dpkg -i binutils_2.22-6ubuntu1.3_amd64.deb 517 | 518 | $ ld -v 519 | 520 | Get IKGT source and build iKGT 521 | ------------------------------ 522 | 523 | Use special manifest to checkout UEFI loader. This loader checks out preloader 524 | EFI app and UEFI version of xmon loader from a different repo. 525 | 526 | $ mkdir r1.2 527 | $ cd r1.2 528 | $ repo init -u https://github.com/intel/ikgt-manifest.git -b release_1_2 -m default-uefi.xml 529 | $ repo sync 530 | $ cd ikgt/example-usage/integrity 531 | $ make 532 | 533 | It will generate ikgt_pkg.bin in r1.2/ikgt/xmon/bin/linux/release 534 | 535 | Building UEFI bootloader 536 | ------------------------ 537 | 538 | $ cd ikgt/xmon/loader/uefi_bootloader 539 | $ ./build.sh 540 | 541 | It will generate the preload_x64.efi in the out/ folder 542 | 543 | Testing the UEFI loader 544 | ------------------------ 545 | 546 | On Dev Machine: 547 | - Prepare USB disk with FAT32 file system. Call it USB1 548 | - Copy ikgt_pkg.bin and preload_64.efi in the root directory of USB1 549 | 550 | Systems that have EFI 64 shell 551 | ------------------------------ 552 | 553 | - Insert USB1 in the test system 554 | - Boot your UEFI system to EFI shell 555 | - Enter FS: to go to your USB 556 | - Launch preload_x64.efi 557 | - You will see several debug messages. After launching ikgt, the control will 558 | come back to EFI shell 559 | 560 | Systems that do not have EFI shell 561 | ---------------------------------- 562 | 563 | You need ability to start EFI shell. Boot-manager rEFInd is one option. 564 | http://www.rodsbooks.com/refind/getting.html 565 | 566 | On Dev System: 567 | - Get the rEFInd from soureforge. We need a USB flash drive image file0. 568 | 569 | You can get the latest package here: 570 | http://sourceforge.net/projects/refind/files/0.9.2/refind-flashdrive-0.9.2.zip/download 571 | 572 | - Format a USB with FAT32 file system. Call it USB2 573 | 574 | - Unzip the package and flash to USB disk (for Ubuntu) 575 | $ unzip refind-flashdrive-0.9.2.zip 576 | $ cd refind-flashdiver-0.9.2 577 | 578 | NOTE: First find out where your USB is mounted using mount command. 579 | Be careful to not accidentally dd on you HDD 580 | 581 | $ dd if=refind-flashdrive-0.9.2.img of=/dev/sd 582 | 583 | This will prepare your bootable USB. When you boot using this USB, it starts rEFInd boot 584 | manager, which has EFI shell. 585 | 586 | On the test system: 587 | - Change the BIOS setting to EFI boot 588 | - Boot from rEFInd USB device USB2. You should see rEFInd menu. 589 | - Start EFI shell from rEFInd menu 590 | - Insert the USB1 (containing preload_64.efi, ikgt_pkg.bin)in the test machine 591 | - Go to the usb drive, by typing “FS: “ 592 | - Type map -r to see the partition list 593 | - Type ls to see the two files you copied earlier 594 | - Run preload_x64.efi 595 | - You will see several debug messages. After launching ikgt, the control will 596 | come back to EFI shell 597 | 598 | Launching Linux 599 | --------------- 600 | 601 | You can now launch Linux from EFI shell as usual. 602 | 603 | Example: 604 | 605 | - On HP Elite Desk Core i5 5th generation system running Ubuntu 14.04, Linux can be 606 | launched via EFI application named grubx64.efi. On tihs system the EFI partition 607 | is mounted at /boot/efi and grubx64.efi can be accessed from /boot/efi/EFI/ubuntu. 608 | You can manually launch this application from the EFI shell to get to grub menu. 609 | - After launching IKGT, when the control returns to EFI shell, go to your HDD EFI 610 | partition by typing 611 | 612 | FS: 613 | cd EFI 614 | cd ubuntu 615 | grubx64.efi 616 | 617 | This will bring up grub menu. If you have multiple options in grub menu, 618 | choose Linux only option. IKGT is already running. 619 | 620 | After Linux boots, open a terminal window and type following to check if IKGT 621 | is running 622 | $ r1.2/ikgt/xmon/package/check_vtx.sh 623 | $ r1.2/ikgt/xmon/package/check_ikgt/check_ikgt 624 | 625 | Known Issues: 626 | ------------ 627 | 628 | We have done limited testing of UEFI loader on select few OEM platforms 629 | including HP Elite Desk, Lenovo Thinkcentre, and Sony ultrabooks. 630 | - Works only with GCC 4.6 and ld 2.22 631 | - IKGT launch hangs on Lenovo X230 632 | - Linux boot hangs on a Lenovo and Sony platforms 633 | 634 | 635 | End of file 636 | 637 | --------------------------------------------------------------------------------