''' for each component.
{{CodeSelect|code=
gpg --verify --multifile grsecurity* gradm* paxctld*
}}
The signature is made against the uncompressed version of the archive. This is done so there is only one signature required for .gz, .bz2 and .xz compressed versions of the release. Start by uncompressing the archive, using unxz. You should see '''Good signature from "Greg Kroah-Hartman''':
{{CodeSelect|code=
sudo apt install xz-utils
unxz linux*.tar.xz
gpg --verify linux*.tar.sign
}}
In this document the kernel source archive linux*.tar and the matching grsecurity patch grsecurity*.patch are both files are in the same directory.
{{CodeSelect|code=
tar -xf linux*.tar
cd linux*
sudo patch -p1 < ../grsecurity-*-*-*.patch
}}
Install the build tools:
{{CodeSelect|code=
sudo apt install flex bison libncurses5-dev fakeroot gcc-4.9-plugin-dev libgmp-dev libmpfr-dev libmpc-dev libssl-dev build-essential
}}
See what version of GCC you have installed and install the matching plugin-dev packages for it. [https://forums.grsecurity.net/viewtopic.php?f=3&t=3484]
{{CodeSelect|code=
gcc -v
}}
To open the kernel configuration menu run:
{{CodeSelect|code=
sudo make menuconfig
}}
Grsecurity is endlessly customizable and if you have different security requirements feel free to dive in the documentation [
https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options
] [
https://en.wikibooks.org/wiki/Grsecurity/Runtime_Configuration
] but be advised very high security settings usually break Xorg server and common packages like Iceweasel and OpenJDK. However for the purposes of compiling a kernel suitable for normal desktop use the Automatic configuration comes with sane defaults. Same for the other usage profiles provided. To have a bootable desktop you will need to disable PaX mprotect at first[https://web.archive.org/web/20190211085205/http://www.insanitybit.com/2012/05/31/compile-and-patch-your-own-secure-linux-kernel-with-pax-and-grsecurity/] It can be re-enabled later when an exception list is loaded.
The configuration should look like this. A lack of mention means leave as default:
Networking Support → Networking options → Network packet filtering framework (Netfilter) → IP:Netfilter Configuration → Enable: IPv4 masquerade support + iptables NAT support
Security options → Grsecurity → Configuration Method → Automatic
→ Usage Type → Desktop
→ Virtualization Type → Guest
→ Virtualization Software → KVM
→ Required Priorities → Security
→ Customize Configuration → PaX → Non-executable pages → Deselect: Restrict mprotect
→ Customize Configuration → Memory Protections → Disable privileged I/O
→ Customize Configuration → Role Based Access Control Options → Hide kernel processes
→ Customize Configuration → Sysctl Support → Deselect: Sysctl support
To save time you can compile one kernel for both the guest and host . NB This only works if you compiled a custom {{project_name_short}} x64. A x64 Linux Host/Guest configuration would look like:
64-bit kernel
Networking Support → Networking options → Network packet filtering framework (Netfilter) → IP:Netfilter Configuration → Enable: IPv4 masquerade support + iptables NAT support
Security options → Grsecurity → Configuration Method → Automatic
→ Usage Type → Desktop
→ Virtualization Type → Host
→ Virtualization Software → KVM
→ Required Priorities → Security
→ Customize Configuration → PaX → Non-executable pages → Deselect: Restrict mprotect
→ Customize Configuration → Memory Protections → Disable privileged I/O
→ Customize Configuration → Role Based Access Control Options → Hide kernel processes
→ Customize Configuration → Sysctl Support → Deselect: Sysctl support
Once you are done select save and keep the .config name then exit out of all menus.
Compile while specifying the number of cores after the '''-j''' option. The number should be the number of cores assigned to the VM + 1. This will result in a huge speed up during compilation and reduce compilation time drastically.
{{CodeSelect|code=
sudo fakeroot make -j 5 deb-pkg
}}
Now sit tight. Go make yourself a cup of coffee or read a book until its finished.
To install your new packages including Pax's configuration utility in the guest run:
{{CodeSelect|code=
cd ..
sudo dpkg -i linux-image-*-grsec_*-*_*.deb
sudo dpkg -i linux-firmware*.deb
sudo dpkg -i linux-headers*.deb
sudo dpkg -i linux-libc*.deb
sudo dpkg -i paxctld*.deb
}}
Move the package to the host via a shared folder and install with dpkg from there.
{{CodeSelect|code=
mv linux-image-*-grsec_*-*_*.deb /mnt/shared
mv linux-firmware*.deb /mnt/shared
mv linux-headers*.deb /mnt/shared
mv linux-libc*.deb /mnt/shared
}}
Done. After installation the system should automatically boot up with the Grsecurity kernel. To inspect the kernel version type:
{{CodeSelect|code=
uname -r
}}
==== Upgraded Kernel Builds ====
Backup your customized kernel configuration file [named .config]. Its available in the root of the kernel source code folder. You may need to enable viewing of hidden files to see it.
To build with newer kernel releases, restore the .config file to the source folder and run:
{{CodeSelect|code=
sudo make oldconfig
}}
Hold 'Enter' to answer questions about new kernel features.
=== Gradm ===
Gradm is the administration tool for RBAC, Grsecurity's intelligent Mandatory Access Control system. Unlike other MACs that require painstaking attention to configuration, RBAC is capable of automatic behavior learning and auto-generating safe program acess policies.
==== Compilation and Installation ====
To prepare and compile:
{{CodeSelect|code=
tar xzf gradm*.tar.gz
cd gradm
}}
Add the iptables patch:
{{CodeSelect|code=
sudo patch -p1 < ../grsecurity-*-iptables.patch
}}
Compile and install:
{{CodeSelect|code=
sudo make install
}}
For the Host install the required build dependencies (make sure '''apt-transport-tor''' is installed on host first) then move the patched extracted and patched gradm directory via the shared folder into your home directory. Then run the same commands as above.
{{CodeSelect|code=
sudo apt install bison flex
}}
Its very important you choose a long password that's different from your root account's.
To upgrade to a newer gradm release, re-run the same build commands above.
==== Usage ====
A detailed [https://wiki.archlinux.org/title/Grsecurity#RBAC guide] on generating and enforcing RBAC policy is available on the Arch Linux wiki. Note these instructions apply to all distros.
==How-To: {{q_project_name_long}}==
This work is being undertaken by Coldhak and the instructions are drawn almost exclusively from their blog and github account. [https://coldhak.ca/blog/2016/12/12/coldkernel-qubes-1.html] [https://github.com/coldhakca/coldkernel] The Debian-8 Template is currently supported. Work is ongoing to support the Fedora and {{project_name_short}} Templates, as well as the Qubes Disposable and dom0. [https://github.com/coldhakca/coldkernel/issues]
Note: These instructions have been tested to work with the 4.8 Linux "coldkernel" in a Debian-8 Template. At the time of writing, Qubes users report post-build Template problems when using the 4.9 Linux kernel with pvgrub2 in a Debian-8 template. [https://github.com/QubesOS/qubes-issues/issues/2762] It is advisable to use the 4.8 Linux coldkernel series until this bug is fixed or alternatively attempt to build the 4.9 Linux coldkernel in a Debian-9 Template (untested).
'''Warning:''' These instructions are extremely alpha and may potentially break the template. Always clone default templates before proceeding!
===Debian Template===
====Configuring the Debian Template====
'''1. Clone the Debian Template'''
'''2. Increase the Maximum Storage Size of the Debian Template'''
https://coldhak.ca/assets/img/blog/coldkernel_pt1/size.png
Note: A minimum of 4GB is recommended. 10GB is a safe value so you don't run out of disk space at the end of the build.
'''3. Edit sources.list'''
In the Debian Template, run.
sudoedit /etc/apt/sources.list
Uncomment the lines starting with deb-src. It should look something like this.
deb https://deb.debian.net/debian jessie main contrib non-free
deb-src https://deb.debian.net/debian jessie main contrib non-free
deb https://security.debian.org jessie/updates main contrib non-free
deb-src https://security.debian.org jessie/updates main contrib non-free
Save and exit.
'''4. Install dom0 Dependencies'''
In dom0, run.
sudo qubes-dom0-update grub2-xen
'''5. Install Debian Dependencies'''
In the Debian Template, run.
sudo apt install qubes-kernel-vm-support grub2-common
sudo apt install paxctl bc wget gnupg fakeroot build-essential devscripts libfile-fcntllock-perl git gcc-4.9-plugin-dev
sudo apt build-dep linux
====Building the grsec Coldkernel====
'''1. Clone and Verify the Coldkernel Build Scripts'''
Note: Always verify and checkout the latest kernel available from coldhak. For the 4.8 Linux kernel branch, this is version 4.8.17. For the 4.9 Linux kernel branch, as at April 2017 this was version 4.9.20. The 4.8.17 (stable) coldkernel is referenced in instructions below.
In the Debian Template, run.
wget "https://coldhak.ca/coldhak/keys/coldhak.asc" -O coldhak.asc
gpg --import coldhak.asc
git clone https://github.com/coldhakca/coldkernel
cd coldkernel
git verify-tag coldkernel-0.9a-4.8.17
git checkout --quiet tags/coldkernel-0.9a-4.8.17
The verfication step (git verify-tag) should produce a good signature from the Coldhak developers, similar to this.
gpg: Signature made Mon 03 Apr 2017 11:50:21 AM EDT using RSA key ID DE32FEBB
gpg: Good signature from "Coldhak developers (signing key) "
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 1073 B61B 69CB 0444 33B6 4F7B 0B1F 9321 DE32 FEBB
The fingerprint should match that found on the coldhak website.
https://coldhak.ca/assets/img/blog/coldkernel_pt1/verify.png
'''2. Build the grsec Coldkernel'''
Note: This step can take several hours depending on your computer hardware; later architectures can finish this step in less than one hour. This process is CPU intensive, and the system may crash if other programs are used simultaneously.
To make the build with hypervisor support, in the Debian Template run.
make qubes-guest
The output should look as follows.
patching file coldkernel.config
Importing signing keys... [DONE]
Removing previous working directory (if one exists)... [DONE]
Fetching kernel sources and signatures... [DONE]
Fetching grsecurity patch and signatures... [DONE]
Unpacking Linux Kernel sources... [DONE]
Verifying the Linux Kernel sources... [DONE]
Verifying Kernel patches... [DONE]
Extracting Linux Kernel sources... [DONE]
Applying grsecurity patch, and moving coldkernel.config into place... [DONE]
Building coldkernel... [DONE]
====Installing the grsec Coldkernel====
Note: During the sudo update-grub2 step below, this error message can be safely ignored if it appears. [https://github.com/QubesOS/qubes-doc/blob/master/configuration/managing-vm-kernel.md]
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
Post-build, in the Debian Template VM run.
wget https://grsecurity.net/paxctld/paxctld_1.2.1-1_amd64.{deb,deb.sig}
gpg --homedir=.gnupg --verify paxctld_1.2.1-1_amd64.{deb.sig,deb}
sudo dpkg -i paxctld_1.2.1-1_amd64.deb
sudo make install-deb
sudo cp paxctld.conf /etc/paxctld.conf
sudo paxctld -d
sudo systemctl enable paxctld
sudo mkdir /boot/grub
sudo update-grub2
sudo shutdown -h now
====Post-install Template Configuration====
'''1. Change the Debian Template Kernel'''
After the Template has been shutdown, change the kernel in the Qubes VM Manager to use pvgrub2.
https://coldhak.ca/assets/img/blog/coldkernel_pt1/pvgrub.png
'''2. Check the Debian Template is Functional'''
Start the Debian Template. If successful, the VM state should be green in Qubes VM Manager and the VM log should contain output similar to this.
Linux Version 4.8.17-coldkernel-grsec-2
'''3. Set Default Grsec Special Groups'''
In the Debian Template, run.
sudo groupadd -g 9001 grsecproc
sudo groupadd -g 9002 tpeuntrusted
sudo groupadd -g 9003 denysockets
Note: Respectively, users in these groups are:
* Exempted from grsecurity's /proc restrictions.
* Unable to execute any files that are not in root-owned directories writable only by root.
* Unable to connect to other hosts from your machine or run server applications.
'''4. Install paxtest and Check that Grsecurity is Running'''
In the Debian Template, run.
sudo apt install paxtest
paxtest blackhat
You should see output similar to this.
Executable anonymous mapping: Killed
Executable bss: Killed
Executable data: Killed
Executable heap: Killed
Executable stack: Killed
Executable shared library bss: Killed
Executable shared library data: Killed
Executable anonymous mapping (mprotect): Killed
Executable bss (mprotect): Killed
Executable data (mprotect): Killed
Executable heap (mprotect): Killed
Executable stack (mprotect): Killed
Executable shared library bss (mprotect): Killed
Executable shared library data (mprotect): Killed
Writable text segments: Killed
Anonymous mapping randomisation test: 28 bits (guessed)
Heap randomisation test (ET_EXEC): 23 bits (guessed)
Heap randomisation test (PIE): 35 bits (guessed)
Main executable randomisation (ET_EXEC): 28 bits (guessed)
Main executable randomisation (PIE): 28 bits (guessed)
Shared library randomisation test: 28 bits (guessed)
Stack randomisation test (SEGMEXEC): 35 bits (guessed)
Stack randomisation test (PAGEEXEC): 35 bits (guessed)
Arg/env randomisation test (SEGMEXEC): 39 bits (guessed)
Arg/env randomisation test (PAGEEXEC): 39 bits (guessed)
Randomization under memory exhaustion @~0: 29 bits (guessed)
Randomization under memory exhaustion @0: 28 bits (guessed)
Return to function (strcpy): paxtest: return address contains a NULL byte.
Return to function (memcpy): Killed
Return to function (strcpy, PIE): paxtest: return address contains a NULL byte.
Return to function (memcpy, PIE): Killed
'''5. ''Advanced (Untested)'' - Secure the AppVM Further by Using gradm2 in Learning Mode'''
Follow the steps [https://en.wikibooks.org/wiki/Grsecurity/The_Administration_Utility#Full_System_Learning here].
====Post-install Debian AppVM Configuration====
'''1. Create an AppVM Based on the Debian Coldkernel Template'''
'''2. Change the AppVM Kernel Selection'''
Use Qubes VM Manager to set "pvgrub2" for the AppVM's kernel selection. Otherwise, it defaults to the standard Qubes kernel.
====Upgraded Kernel Builds====
When an upgraded grsec Linux kernel is released by Coldhak, [https://github.com/coldhakca/coldkernel] the kernel version of the existing grsec Template can be bumped via the following steps.
'''1. Fetch and Verify the Upgraded Kernel Branch'''
Note: Do not perform the cloning step again. The signing key is not imported again, unless it has changed.
''If the signing key has changed,'' in the Template run.
wget "https://coldhak.ca/coldhak/keys/coldhak.asc" -O coldhak.asc
gpg --import coldhak.asc
In all cases, verify and checkout the upgraded kernel branch (change the kernel reference below to match the updated release) in the Template.
cd coldkernel
git fetch
git verify-tag coldkernel-0.9a-4.9.20
git checkout --quiet tags/coldkernel-0.9a-4.9.20
The verfication step (git verify-tag) should produce a good signature from the Coldhak developers.
gpg: Signature made Mon 03 Apr 2017 11:50:21 AM EDT using RSA key ID DE32FEBB
gpg: Good signature from "Coldhak developers (signing key) "
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 1073 B61B 69CB 0444 33B6 4F7B 0B1F 9321 DE32 FEBB
The fingerprint should match that found on the coldhak website.
https://coldhak.ca/assets/img/blog/coldkernel_pt1/verify.png
'''2. Build the Upgraded Kernel'''
To make the build with hypervisor support, in the Template run.
make qubes-guest
The output should look as follows.
patching file coldkernel.config
Importing signing keys... [DONE]
Removing previous working directory (if one exists)... [DONE]
Fetching kernel sources and signatures... [DONE]
Fetching grsecurity patch and signatures... [DONE]
Unpacking Linux Kernel sources... [DONE]
Verifying the Linux Kernel sources... [DONE]
Verifying Kernel patches... [DONE]
Extracting Linux Kernel sources... [DONE]
Applying grsecurity patch, and moving coldkernel.config into place... [DONE]
Building coldkernel... [DONE]
'''3. Installing the Upgraded grsec Coldkernel'''
paxctld is not downloaded again, unless there was an update. First check: https://github.com/coldhakca/coldkernel to see if this is required.
If paxctld has changed, change the paxctld reference below to match the updated release and run in the Template.
wget https://grsecurity.net/paxctld/paxctld_1.2.1-1_amd64.{deb,deb.sig}
gpg --homedir=.gnupg --verify paxctld_1.2.1-1_amd64.{deb.sig,deb}
sudo dpkg -i paxctld_1.2.1-1_amd64.deb
In all cases, repeat these installation steps.
sudo make install-deb
sudo cp paxctld.conf /etc/paxctld.conf
sudo paxctld -d
sudo update-grub2
sudo shutdown -h now
'''4. Post-install Template Configuration'''
Follow steps 2-4 [[Grsecurity#Post-install_Template_Configuration|here]], except:
* Do not set default grsec special groups again, unless they have changed.
* Do not install paxtest again, only run paxtest blackhat to check grsecurity is running correctly.
'''5. Post-install AppVM Configuration'''
Follow [[Grsecurity#Post-install_Debian_AppVM_Configuration|these steps]] to create a new AppVM based on the upgraded kernel branch.
===Fedora Template===
''To do following Coldhak release.''
==={{project_name_short}} Templates===
''To do following Coldhak release.''
===Qubes Disposable===
''To do following Coldhak release.''
===Qubes dom0===
''To do following Coldhak release.''
= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]