├── .doctrees ├── clipos │ ├── architecture.doctree │ ├── boot_integrity.doctree │ ├── development.doctree │ ├── kernel.doctree │ ├── roadmap.doctree │ ├── security.doctree │ └── update.doctree ├── environment.pickle ├── index.doctree └── toolkit │ ├── build-steps.doctree │ ├── build.doctree │ ├── contribute.doctree │ ├── derive.doctree │ ├── maintaining_portage_tree.doctree │ ├── maintaining_sdk.doctree │ ├── quick-try.doctree │ ├── setup.doctree │ ├── source-tree.doctree │ └── test.doctree ├── .nojekyll ├── CNAME ├── LICENSE.md ├── README.md ├── _images ├── clipos-boot-order.svg ├── clipos-cage-and-service-isolation.svg ├── clipos-disk-layout.svg ├── clipos-high-level-architecture.svg └── clipos-inter-level-interactions.svg ├── _sources ├── clipos │ ├── architecture.rst.txt │ ├── boot_integrity.rst.txt │ ├── development.rst.txt │ ├── kernel.rst.txt │ ├── roadmap.rst.txt │ ├── security.rst.txt │ └── update.rst.txt ├── index.rst.txt └── toolkit │ ├── build-steps.rst.txt │ ├── build.rst.txt │ ├── contribute.rst.txt │ ├── derive.rst.txt │ ├── maintaining_portage_tree.rst.txt │ ├── maintaining_sdk.rst.txt │ ├── quick-try.rst.txt │ ├── setup.rst.txt │ ├── source-tree.rst.txt │ └── test.rst.txt ├── _static ├── ajax-loader.gif ├── basic.css ├── clipos_logo.png ├── comment-bright.png ├── comment-close.png ├── comment.png ├── css │ ├── badge_only.css │ ├── colors.css │ └── theme.css ├── doctools.js ├── documentation_options.js ├── down-pressed.png ├── down.png ├── favicon.ico ├── file.png ├── fonts │ ├── Lato-Bold.ttf │ ├── Lato-Bold.woff2 │ ├── Lato-BoldItalic.ttf │ ├── Lato-BoldItalic.woff2 │ ├── Lato-Italic.ttf │ ├── Lato-Italic.woff2 │ ├── Lato-Regular.ttf │ ├── Lato-Regular.woff2 │ ├── RobotoSlab-Bold.ttf │ ├── RobotoSlab-Bold.woff2 │ ├── RobotoSlab-Regular.ttf │ ├── RobotoSlab-Regular.woff2 │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ └── fontawesome-webfont.woff2 ├── graphviz.css ├── jquery.js ├── js │ ├── modernizr.min.js │ └── theme.js ├── language_data.js ├── minus.png ├── plus.png ├── pygments.css ├── searchtools.js ├── underscore.js ├── up-pressed.png ├── up.png └── websupport.js ├── clipos ├── architecture.html ├── boot_integrity.html ├── development.html ├── kernel.html ├── roadmap.html ├── security.html └── update.html ├── genindex.html ├── index.html ├── objects.inv ├── search.html ├── searchindex.js └── toolkit ├── build-steps.html ├── build.html ├── contribute.html ├── derive.html ├── maintaining_portage_tree.html ├── maintaining_sdk.html ├── quick-try.html ├── setup.html ├── source-tree.html └── test.html /.doctrees/clipos/architecture.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/architecture.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/boot_integrity.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/boot_integrity.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/development.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/development.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/kernel.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/kernel.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/roadmap.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/roadmap.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/security.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/security.doctree -------------------------------------------------------------------------------- /.doctrees/clipos/update.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/clipos/update.doctree -------------------------------------------------------------------------------- /.doctrees/environment.pickle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/environment.pickle -------------------------------------------------------------------------------- /.doctrees/index.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/index.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/build-steps.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/build-steps.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/build.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/build.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/contribute.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/contribute.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/derive.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/derive.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/maintaining_portage_tree.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/maintaining_portage_tree.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/maintaining_sdk.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/maintaining_sdk.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/quick-try.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/quick-try.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/setup.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/setup.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/source-tree.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/source-tree.doctree -------------------------------------------------------------------------------- /.doctrees/toolkit/test.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.doctrees/toolkit/test.doctree -------------------------------------------------------------------------------- /.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/.nojekyll -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | docs.clip-os.org 2 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | LICENCE OUVERTE / OPEN LICENCE Version 2.0 2 | ========================================== 3 | 4 | Réutilisation de l’« Information » sous cette licence 5 | ----------------------------------------------------- 6 | 7 | Le « Concédant » concède au « Réutilisateur » un droit non exclusif et gratuit 8 | de libre « Réutilisation » de l’« Information » objet de la présente licence, à 9 | des fins commerciales ou non, dans le monde entier et pour une durée illimitée, 10 | dans les conditions exprimées ci-dessous. 11 | 12 | **Le « Réutilisateur » est libre de réutiliser l’« Information » :** 13 | 14 | - de la reproduire, la copier, 15 | - de l’adapter, la modifier, l’extraire et la transformer, pour créer des 16 | « Informations dérivées », des produits ou des services, 17 | - de la communiquer, la diffuser, la redistribuer, la publier et la 18 | transmettre, 19 | - de l’exploiter à titre commercial, par exemple en la combinant avec d’autres 20 | informations, ou en l’incluant dans son propre produit ou application. 21 | 22 | **Sous réserve de :** 23 | 24 | - mentionner la paternité de l’« Information » : sa source (au moins le nom du 25 | « Concédant ») et la date de dernière mise à jour de l’« Information » 26 | réutilisée. 27 | 28 | Le « Réutilisateur » peut notamment s’acquitter de cette condition en 29 | renvoyant, par un lien hypertexte, vers la source de « l’Information » et 30 | assurant une mention effective de sa paternité. 31 | Par exemple : « Ministère de xxx - Données originales téléchargées sur 32 | http://www.data.gouv.fr/fr/datasets/xxx/, mise à jour du 14 février 2017 ». 33 | 34 | Cette mention de paternité ne confère aucun caractère officiel à la 35 | « Réutilisation » de l’« Information », et ne doit pas suggérer une quelconque 36 | reconnaissance ou caution par le « Concédant », ou par toute autre entité 37 | publique, du « Réutilisateur » ou de sa « Réutilisation ». 38 | 39 | 40 | « Données à caractère personnel » 41 | --------------------------------- 42 | 43 | L’« Information » mise à disposition peut contenir des « Données à caractère 44 | personnel » pouvant faire l’objet d’une « Réutilisation ». Si tel est le cas, 45 | le « Concédant » informe le « Réutilisateur » de leur présence. 46 | L’« Information » peut être librement réutilisée, dans le cadre des droits 47 | accordés par la présente licence, à condition de respecter le cadre légal 48 | relatif à la protection des données à caractère personnel. 49 | 50 | 51 | « Droits de propriété intellectuelle » 52 | -------------------------------------- 53 | 54 | Il est garanti au « Réutilisateur » que les éventuels « Droits de propriété 55 | intellectuelle » détenus par des tiers ou par le « Concédant » sur 56 | l’« Information » ne font pas obstacle aux droits accordés par la présente 57 | licence. 58 | 59 | Lorsque le « Concédant » détient des « Droits de propriété intellectuelle » 60 | cessibles sur l’« Information », il les cède au « Réutilisateur » de façon non 61 | exclusive, à titre gracieux, pour le monde entier, pour toute la durée des 62 | « Droits de propriété intellectuelle », et le « Réutilisateur » peut faire tout 63 | usage de l’« Information » conformément aux libertés et aux conditions définies 64 | par la présente licence. 65 | 66 | 67 | Responsabilité 68 | -------------- 69 | 70 | L’« Information » est mise à disposition telle que produite ou reçue par le 71 | « Concédant », sans autre garantie expresse ou tacite que celles prévues par la 72 | présente licence. L’absence de défauts ou d’erreurs éventuellement contenues 73 | dans l’« Information », comme la fourniture continue de l’« Information » n’est 74 | pas garantie par le « Concédant ». Il ne peut être tenu pour responsable de 75 | toute perte, préjudice ou dommage de quelque sorte causé à des tiers du fait de 76 | la « Réutilisation ». 77 | 78 | Le « Réutilisateur » est seul responsable de la « Réutilisation » de 79 | l’« Information ». 80 | 81 | La « Réutilisation » ne doit pas induire en erreur des tiers quant au contenu 82 | de l’« Information », sa source et sa date de mise à jour. 83 | 84 | 85 | Droit applicable 86 | ---------------- 87 | 88 | La présente licence est régie par le droit français. 89 | 90 | 91 | Compatibilité de la présente licence 92 | ------------------------------------ 93 | 94 | La présente licence a été conçue pour être compatible avec toute licence libre 95 | qui exige au moins la mention de paternité et notamment avec la version 96 | antérieure de la présente licence ainsi qu’avec les licences « Open Government 97 | Licence » (OGL) du Royaume-Uni, « Creative Commons Attribution » (CC-BY) de 98 | Creative Commons et « Open Data Commons Attribution » (ODC-BY) de l’Open 99 | Knowledge Foundation. 100 | 101 | 102 | Définitions 103 | ----------- 104 | 105 | Sont considérés, au sens de la présente licence comme : 106 | 107 | - Le « Concédant » : toute personne concédant un droit de « Réutilisation » sur 108 | l’« Information » dans les libertés et les conditions prévues par la présente 109 | licence. 110 | 111 | - L’« Information » : 112 | - toute information publique figurant dans des documents communiqués ou 113 | publiés par une administration mentionnée au premier alinéa de l’article 114 | L.300-2 du CRPA ; 115 | - toute information mise à disposition par toute personne selon les termes 116 | et conditions de la présente licence. 117 | 118 | - La « Réutilisation » : l’utilisation de l’« Information » à d’autres fins 119 | que celles pour lesquelles elle a été produite ou reçue. 120 | 121 | - Le « Réutilisateur » : toute personne qui réutilise les « Informations » 122 | conformément aux conditions de la présente licence. 123 | 124 | - Des « Données à caractère personnel » : toute information se rapportant à une 125 | personne physique identifiée ou identifiable, pouvant être identifiée 126 | directement ou indirectement. Leur « Réutilisation » est subordonnée au 127 | respect du cadre juridique en vigueur. 128 | 129 | - Une « Information dérivée » : toute nouvelle donnée ou information créées 130 | directement à partir de l’« Information » ou à partir d’une combinaison de 131 | l’« Information » et d’autres données ou informations non soumises à cette 132 | licence. 133 | 134 | - Les « Droits de propriété intellectuelle » : tous droits identifiés comme 135 | tels par le Code de la propriété intellectuelle (notamment le droit d’auteur, 136 | droits voisins au droit d’auteur, droit sui generis des producteurs de bases 137 | de données…). 138 | 139 | 140 | À propos de cette licence 141 | ------------------------- 142 | 143 | La présente licence a vocation à être utilisée par les administrations pour la 144 | réutilisation de leurs informations publiques. Elle peut également être 145 | utilisée par toute personne souhaitant mettre à disposition de 146 | l’« Information » dans les conditions définies par la présente licence 147 | 148 | La France est dotée d’un cadre juridique global visant à une diffusion 149 | spontanée par les administrations de leurs informations publiques afin d’en 150 | permettre la plus large réutilisation. 151 | Le droit de la « Réutilisation » de l’« Information » des administrations est 152 | régi par le code des relations entre le public et l’administration (CRPA). 153 | Cette licence facilite la réutilisation libre et gratuite des informations 154 | publiques et figure parmi les licences qui peuvent être utilisées par 155 | l’administration en vertu du décret pris en application de l’article L.323-2 du 156 | CRPA. 157 | 158 | Etalab est la mission chargée, sous l’autorité du Premier ministre, d’ouvrir le 159 | plus grand nombre de données publiques des administrations de l’Etat et de ses 160 | établissements publics. Elle a réalisé la Licence Ouverte pour faciliter la 161 | réutilisation libre et gratuite de ces informations publiques, telles que 162 | définies par l’article L321-1 du CRPA. 163 | 164 | Cette licence est la version 2.0 de la Licence Ouverte. 165 | 166 | Etalab se réserve la faculté de proposer de nouvelles versions de la Licence 167 | Ouverte. Cependant, les « Réutilisateurs » pourront continuer à réutiliser les 168 | informations qu’ils ont obtenues sous cette licence s’ils le souhaitent. 169 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Static content for docs.clip-os.org 2 | 3 | See . 4 | -------------------------------------------------------------------------------- /_images/clipos-boot-order.svg: -------------------------------------------------------------------------------- 1 | 2 | 17 | 19 | 20 | 22 | image/svg+xml 23 | 25 | 26 | 27 | 28 | 29 | 31 | 55 | 58 | 65 | 72 | 78 | UEFI Firmware 82 | 83 | 84 | 87 | 94 | 101 | 107 | Bootloader 111 | 112 | 113 | 116 | 123 | 130 | 136 | EFI Binary 140 | (Linux kernel + initramfs 144 | + kernel command line) 148 | 149 | 150 | 153 | 158 | 163 | 168 | 169 | 172 | 177 | 182 | 187 | 188 | 191 | 198 | 205 | 211 | / 215 | (DM-Verity & 219 | read-only rootfs) 223 | 224 | 225 | 228 | 233 | 237 | 242 | 243 | 249 | 253 | 254 | 257 | 264 | 271 | 277 | 1 281 | 282 | 283 | 286 | 293 | 300 | 306 | 3 310 | 311 | 312 | 315 | 322 | 329 | 335 | 2 339 | 340 | 341 | 342 | -------------------------------------------------------------------------------- /_images/clipos-disk-layout.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | EFI system 16 | partition 17 | 18 | 19 | 20 | 21 | 22 | 23 | LVM partition 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /_images/clipos-high-level-architecture.svg: -------------------------------------------------------------------------------- 1 | 2 | 17 | 19 | 20 | 22 | image/svg+xml 23 | 25 | 26 | 27 | 28 | 29 | 31 | 55 | 58 | 65 | 72 | 78 | Cage 2 82 | (Gentoo) 86 | 87 | 88 | 91 | 98 | 105 | 111 | Cage 3 115 | (...) 119 | 120 | 121 | 128 | 135 | 138 | 145 | 152 | 158 | Core (Gentoo Hardened) 162 | 163 | 164 | 167 | 174 | 180 | Linux kernel 184 | 185 | 186 | 189 | 196 | 203 | 209 | Hardware 213 | 214 | 215 | 218 | 225 | 232 | 238 | Cage 1 242 | (Debian) 246 | 247 | 248 | 255 | 262 | 269 | 276 | 282 | Controlled interaction 286 | 287 | 293 | Enforced isolation 297 | 298 | 304 | 308 | 309 | 310 | -------------------------------------------------------------------------------- /_sources/clipos/architecture.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | Architecture 7 | ============ 8 | 9 | System components and their interactions 10 | ---------------------------------------- 11 | 12 | A CLIP OS system is split into several logically separated entities: 13 | 14 | * A **bootloader** and an **initial EFI binary** responsible for the system 15 | start-up. 16 | * A **Core** responsible for system service hosting and sub environments 17 | (called *Cages* from now on) start-up. The *Core* is also responsible for 18 | the isolation and control of all interactions between those *Cages*. 19 | * One or several **Cages** usually available as graphical sessions for users. 20 | Each *Cage* may host applications and documents from a specific 21 | confidentiality level. 22 | 23 | .. _clipos-high-level-architecture: 24 | .. figure:: imgs/clipos-high-level-architecture.svg 25 | :align: center 26 | :figwidth: 90 % 27 | 28 | High level overview of CLIP OS components 29 | 30 | The execution environment of each Cage is logically isolated from the Core and 31 | from all the other Cages. Interactions between a Cage and the Core is carefully 32 | controlled and goes through confined and unprivileged services as shown in 33 | :numref:`clipos-cage-and-service-isolation`. 34 | 35 | .. _clipos-cage-and-service-isolation: 36 | .. figure:: imgs/clipos-cage-and-service-isolation.svg 37 | :align: center 38 | :figwidth: 90 % 39 | 40 | Communication channels between a Cage, the Core and the hardware 41 | 42 | Direct communication between Cages is forbidden. All inter-Cage interaction is 43 | mediated by services running in the Core. 44 | 45 | .. _clipos-inter-level-interactions: 46 | .. figure:: imgs/clipos-inter-level-interactions.svg 47 | :align: center 48 | :figwidth: 90 % 49 | 50 | Flow of interaction required for inter-level communications 51 | 52 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 53 | -------------------------------------------------------------------------------- /_sources/clipos/boot_integrity.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | =================================== 7 | Boot chain and integrity guarantees 8 | =================================== 9 | 10 | On-disk layout 11 | ============== 12 | 13 | .. sidebar:: Disk partition layout 14 | 15 | .. _clipos-disk-layout: 16 | .. figure:: imgs/clipos-disk-layout.svg 17 | :align: center 18 | 19 | Disk partition layout 20 | 21 | The main disk GPT partition layout is as follows (:numref:`clipos-disk-layout`): 22 | 23 | #. EFI system partition (ESP) which includes: 24 | 25 | * The EFI bootloader and its configuration; 26 | * An EFI binary for each version currently installed (usually two, but only 27 | one at installation time). Each EFI binary bundles a Linux kernel, its 28 | command line and an initramfs. 29 | 30 | #. LVM partition which holds all LVM Volume Groups and Logical Volumes for the 31 | system. The currently available ones are: 32 | 33 | .. csv-table:: 34 | :header: "Volume Group", "Logical Volume", "Layer", "Filesystem" 35 | :widths: 1, 1, 5, 5 36 | 37 | "mainvg", "core_", "DM-Verity block device and metadata appended at 38 | the end", "Uncompressed squashfs filesystem" 39 | "mainvg", "core_state", "DM-Crypt + DM-Integrity block device", "ext4 40 | filesystem" 41 | "mainvg", "swap", "DM-Crypt with a random key generated at boot time", "N/A" 42 | 43 | Boot chain order 44 | ================ 45 | 46 | .. sidebar:: Boot chain order 47 | 48 | .. _clipos-boot-order: 49 | .. figure:: imgs/clipos-boot-order.svg 50 | :align: center 51 | 52 | Boot chain order 53 | 54 | As shown in :numref:`clipos-boot-order`, the boot steps (following hardware 55 | initialization) are as follows: 56 | 57 | #. The UEFI Firmware executes the initial bootloader from the EFI system 58 | partition. 59 | 60 | #. Following the `Boot Loader Specification 61 | `_, the bootloader 62 | (gummiboot/systemd-boot) executes the EFI binary in the ``EFI/Linux`` folder 63 | with the highest version number. The executed EFI binary is a bundle created 64 | by `dracut `_ which 65 | wraps a Linux kernel, its command line and an initramfs. 66 | 67 | #. The initramfs opens the ``core-`` DM-Verity block device and mounts 68 | the SquashFS filesystem in ``/sysroot``. Then, using the TPM, it unseals the 69 | key required to open the DM-Crypt/DM-Integrity ``core_state`` partition and 70 | mounts the resulting ext4 partition in ``/sysroot/mnt/state``. Finally, it 71 | performs a pivot_root to switch to the final root. 72 | 73 | 74 | Boot chain and rootfs integrity 75 | =============================== 76 | 77 | The integrity of the boot chain and root filesystem is guaranteed by the 78 | following mechanisms. 79 | 80 | Secure Boot 81 | ----------- 82 | 83 | All EFI binaries installed in the EFI System Partition (ESP) are 84 | signed in order to protect their integrity *via* Secure Boot. Their 85 | confidentiality however is not assured. Currently, two EFI binaries are 86 | necessary: 87 | 88 | * The **systemd-boot EFI bootloader**. Its only purpose is to execute the 89 | latest CLIP OS EFI binary. This bootloader is minimal and only acts as a 90 | switch between the available CLIP OS versions. This enables recovery in case 91 | of update failure or temporary rollback due to bugs in a new version. 92 | 93 | * The **main CLIP OS EFI binary**. It contains the initial kernel image, the 94 | initramfs and the kernel command line. Signing this binary guarantees the 95 | integrity of its three components. Note that the kernel command line also 96 | includes the DM-Verity root hash for the CLIP OS Core partition. This binary 97 | is chosen by the bootloader and the Secure Boot signature verification is 98 | performed by the UEFI Firmware. 99 | 100 | No default keys are supported (e.g., Microsoft keys) thus you will need to 101 | generate you own Secure Boot signing keys and use them during the build 102 | process. Those keys must then be enrolled in hardware. 103 | 104 | DM-Verity 105 | --------- 106 | 107 | Once the kernel is booted with the initial initramfs, it will look for the 108 | ``core-`` LVM Logical Volume which includes a DM-Verity block device. 109 | The ``root hash`` used to verify the integrity of this partition is included in 110 | the kernel command line (thus protected in integrity by Secure Boot). This 111 | assures the integrity of the content of the DM-Verity block device, which 112 | includes the read-only uncompressed SquashFS root filesystem. Support for 113 | forward error correction (FEC) is also enabled thus increasing resistance to 114 | disk read errors or failures. 115 | 116 | .. _trusted_boot: 117 | 118 | Trusted Boot 119 | ------------ 120 | 121 | Objective 122 | ~~~~~~~~~ 123 | 124 | We want to achieve full-disk encryption in a way that is both secure and 125 | unnoticeable to the end user. The TPM enables us to do that by sealing the 126 | encryption key and providing it at boot time if and only if the machine is in a 127 | known-good state (via PCRs extension). In other words, we want to be able to 128 | decrypt the disk only once we *prove* we have booted trusted code. 129 | 130 | However, we would like to avoid re-sealing the encryption key every single 131 | time we upgrade the kernel, the initramfs or the command line. 132 | 133 | Chosen Solution 134 | ~~~~~~~~~~~~~~~ 135 | 136 | We already have Secure Boot, ensuring the UEFI firmware boots our signed EFI 137 | binary containing the kernel, the initramfs and the command line. In other 138 | words, we already *assert* the boot of trusted code. 139 | 140 | A `specification `_, 141 | pointed out `here `_, exists that 142 | combines Secure and Trusted Boot, using PCR 7, by: 143 | 144 | * recording whether Secure Boot is turned on; 145 | * recording the key database; 146 | * recording which keys were used. 147 | 148 | By sealing the disk-encryption key according to the PCR 7 value, we ensure that 149 | the disk is decrypted if and only if our Secure Boot policy has not been 150 | tampered with, which in turn means that we booted a trusted EFI binary, i.e. 151 | trusted kernel, initramfs and command line. 152 | 153 | Naturally, we can in addition use most if not all PCRs 0 to 6 to measure 154 | firmware integrity. In the future, we may also use an additional PCR to 155 | measure the LUKS header(s), similarly to what 156 | `TrustedGRUB2 `_ 157 | does with PCR 12. 158 | 159 | Implementation Choices 160 | ~~~~~~~~~~~~~~~~~~~~~~ 161 | 162 | TPM specification 163 | ***************** 164 | 165 | We rely on TPM 2.0, for various reasons including: 166 | 167 | * TPM 1.2 only supports deprecated cryptographic algorithms and TrouSerS is 168 | hard to deal with and not satisfying (partly due to tcsd); 169 | * TPM 2.0 is already replacing TPM 1.2 in new machines; 170 | * TPM 2.0 offers several new interesting functionalities, such as multiple 171 | hierarchies. 172 | 173 | One issue with TPM 2.0 is that utilities and libraries to deal with it are 174 | still under heavy development. We chose to use the `tpm2-tools 175 | `_, which rely on the `tpm2-tss 176 | `_ implementation of the TCG's TPM2 177 | Software Stack (TSS2). 178 | 179 | Initramfs and LUKS 180 | ****************** 181 | 182 | * We use a Bash script located in our initramfs. 183 | * TPM-sealed LUKS keyfiles are located in the EFI System Partition. 184 | * The kernel's Resource Manager (RM) is used to ease objects management. 185 | Basically, the RM presents each new call to a ``tpm2_*`` tool with an empty 186 | TPM (i.e. it cleans transient objects when the file handle to ``/dev/tpmrm0`` 187 | is closed). 188 | * We use the Owner Hierarchy (OH) and leave the Endorsement Hierarchy (EH) for 189 | remote attestation. 190 | * We make the primary key a persistent object to avoid running the 191 | time-consuming Key Derivation Fonction at each boot. We do not make the 192 | loaded keyfile object persistent as we would not have enough space in the TPM 193 | for all keyfiles we are going to want to use. 194 | 195 | Planned Improvements 196 | ******************** 197 | 198 | * We would like to use different PCR lists for a given machine's first boots 199 | following/during its provisioning, as we may for instance change its BIOS 200 | configuration. 201 | * We would like to use keyctl in order to directly store the decrypted LUKS key 202 | in a kernel keyslot so that cryptsetup can use it without it being passed 203 | through userspace. Note that, currently, keyfiles are in memory and may be 204 | swapped to disk, but that is tolerable as we use an encrypted swap device. 205 | Another solution could be to use ramfs instead of tmpfs. 206 | 207 | Setup for testing 208 | ================= 209 | 210 | Under QEMU with OVMF 211 | -------------------- 212 | 213 | Secure Boot 214 | ~~~~~~~~~~~ 215 | 216 | As a short term solution, we use hard-coded dummy keys to sign the EFI binaries 217 | with **sbsigntools** and ship an OVMF VARS template file in which these keys 218 | have been manually enrolled. 219 | 220 | The optimal way of setting up Secure Boot for a virtual machine will be to 221 | develop and use an EFI binary to automatically enroll PK, KEK and db keys, 222 | similarly to `what Fedora is performing 223 | `_. Such keys would be 224 | generated at build time for a given deployment using the relevant PKI. 225 | 226 | The standard CLIP OS build process includes build steps to enable Secure Boot 227 | testing under QEMU with OVMF. 228 | 229 | Trusted Boot 230 | ~~~~~~~~~~~~ 231 | 232 | QEMU (and libvirt) support two TPM backends: 233 | 234 | * TPM passthrough device: requires the end user to have a hardware TPM on its 235 | host machine, which in addition cannot be used simultaneously by anything 236 | else. There are also some problems due to the way the TPM is initialized by 237 | the host, and thus some commands used by the guest cannot work as expected, 238 | and so on. 239 | * TPM emulator: provides TPM functionality for each VM using a TPM emulator 240 | installed on the host. `swtpm `_ is 241 | currently the only supported emulator. 242 | 243 | The second option is more adapted to our needs but requires people to install 244 | swtpm, which requires `libtpms `_. 245 | 246 | The EFI firmware (OVMF) needs to be built with TPM support. We provide and use 247 | our own derived ``sys-firmware/edk2-ovmf`` to enable Secure Boot and TPM 248 | support. 249 | 250 | With real hardware 251 | ------------------ 252 | 253 | This is not supported at the moment. The main difference is that Secure Boot 254 | keys will need to be enrolled through the manufacturer's UEFI firmware. 255 | However, we expect the EFI binary mentioned above to make this step as 256 | automated as possible. 257 | 258 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 259 | -------------------------------------------------------------------------------- /_sources/clipos/development.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2019 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _development: 7 | 8 | Development and debug 9 | ===================== 10 | 11 | This section describes all changes and information specific to development and 12 | debug that only applies to the CLIP OS product. 13 | 14 | Effect of instrumentation features 15 | ---------------------------------- 16 | 17 | This is a summary of all changes made to the project during build and 18 | configuration steps for each instrumentation feature available for development 19 | only. Instrumentation features must be configured before project builds in 20 | ``instrumentation.toml`` which must be located in the project repo root 21 | directory. See ``toolkit/instrumentation.toml.example`` to get good default 22 | values for development. 23 | 24 | * **instrumented-core:** Install additional software development tools in the 25 | Core, such as Bash, Vim, tmux, tree, strace, grep, ip, less, gdb, tcpdump, 26 | etc. (This is a non-exhautive list, for the complete list please refer to 27 | the ``clipos-meta/clipos-core`` ebuild) 28 | 29 | * **passwordless-root-login:** Enable local and remote (SSH) root login 30 | without password. 31 | 32 | .. admonition:: Dependency 33 | :class: warning 34 | 35 | To use this instrumentation feature, you must also enable 36 | **instrumented-core**. 37 | 38 | * **allow-ssh-root-login:** Configure SSH in order to allow a developer to 39 | log in as root (account must be enabled with the appropriate 40 | instrumentation feature) via SSH and without any password thanks to an 41 | installed SSH key pair (an SSH key pair will be generated in the cache 42 | directory at first usage of this instrumentation feature). This also makes 43 | the openssh server accessible over the local network and not only restricted 44 | to IPsec interface. 45 | 46 | .. admonition:: Dependency 47 | :class: warning 48 | 49 | To use this instrumentation feature, you must also enable 50 | **passwordless-root-login** and **instrumented-core**. 51 | 52 | * **dev-friendly-bootloader:** Configure the bootloader to provide handy 53 | features to developer (i.e. "Reboot into firmware") and set a smaller 54 | timeout before loading the default boot entry. 55 | 56 | * **instrumented-initramfs:** Install additional software development tools in 57 | the initramfs, such as strace, ltrace, less, grep, gdb, etc. (This is a 58 | non-exhautive list, for the complete list please refer to the 59 | ``clipos-meta/clipos-efiboot`` ebuild). 60 | 61 | * **soften-kernel-configuration:** Lower Linux kernel security parameters at 62 | runtime. 63 | 64 | * **initramfs-no-require-tpm:** Do not require a TPM 2.0 for the LUKS disk 65 | partition decryption. Therefore, in case of missing TPM 2.0, LUKS passphrase 66 | will be prompted on the active console (either tty or serial console ttyS0). 67 | 68 | * **initramfs-no-tpm-lockout:** Do not lockout TPM (brute-force attack 69 | protection) when interacting with the TPM 2.0 (check out the TPM 70 | documentation for the "noDA" attribute and for "dictionary attack 71 | protections"). 72 | 73 | * **debuggable-initramfs:** Activate alterations to initramfs/efiboot packages 74 | intended to ease their debugging (e.g. debugging symbols): 75 | 76 | * **breakpointed-initramfs:** Enable dracut breakpoints with interactive shell 77 | drop-outs. 78 | 79 | .. admonition:: Important note 80 | :class: important 81 | 82 | This feature requires multiple interactions on the console (or serial 83 | console for the QEMU target) to make the boot sequence proceed to the 84 | final pivot_root(2). 85 | 86 | .. admonition:: Dependency 87 | :class: warning 88 | 89 | To use this instrumentation feature, you must also enable 90 | **instrumented-initramfs**. 91 | 92 | * **early-root-shell:** Spawn a persistent root interactive shell on a serial 93 | console or an tty very early in the boot up sequence (right after the 94 | pivot_root(2) done by the initramfs) in order to ease systemd debugging 95 | tasks. See `systemd debugging 96 | `_ for more 97 | information. 98 | 99 | .. admonition:: Dependency 100 | :class: warning 101 | 102 | To use this instrumentation feature, you must also enable 103 | **instrumented-core**. 104 | 105 | * **debuggable-kernel:** Activates features for debugging purposes in the 106 | kernel (KALLSYMS, core dump production, etc.) with logging output sent on the 107 | serial port (ttyS0) early on boot up sequence. 108 | 109 | * **verbose-systemd:** Sets parameters on the kernel command line to make 110 | systemd very verbose on the defined console output (ttyS0 serial port by 111 | default): 112 | 113 | * **coredump-handler:** Configure systemd in order to install the 114 | systemd-coredump to allow kernel produce core dump files. 115 | 116 | .. admonition:: Dependency 117 | :class: warning 118 | 119 | To use this instrumentation feature, you must also enable 120 | **debuggable-kernel**. 121 | 122 | * **test-update:** In addition to the normal build, create everything required 123 | to test updates. This creates a second build with the same content but a 124 | higher version. 125 | 126 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 127 | -------------------------------------------------------------------------------- /_sources/clipos/roadmap.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _roadmap: 7 | 8 | Roadmap 9 | ======= 10 | 11 | This roadmap lists CLIP OS features planned for integration into each release. 12 | 13 | .. admonition:: Work in progress 14 | :class: warning 15 | 16 | **This roadmap is still a work in progress and will evolve with the project 17 | as features are added.** 18 | 19 | 5.0 Alpha: Initial open source preview release 20 | ---------------------------------------------- 21 | 22 | .. admonition:: Status 23 | :class: tip 24 | 25 | Released on **2018-09-20**. 26 | 27 | Features 28 | ~~~~~~~~ 29 | 30 | Security aware system architecture and partition layout 31 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 32 | 33 | * Root partition mounted read-only 34 | * Restricted set of state partitions bind-mounted at pre-determined 35 | emplacements (listed in the read-only root partition) 36 | 37 | Initial boot chain integrity with UEFI Secure Boot support and DM-Verity 38 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 39 | 40 | * Signed EFI bootloader 41 | * Signed EFI binaries (includes Linux kernel, initramfs and kernel command 42 | line) 43 | * Root partition integrity enforced by DM-Verity 44 | 45 | Development model and secure by default software compilation 46 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 47 | 48 | * Everything is rebuilt from source (excepted proprietary firmware required for 49 | hardware support) 50 | * Gentoo Hardened based binary executable compilation 51 | * Most of Portage compilation security features are enabled 52 | 53 | Linux kernel 54 | ^^^^^^^^^^^^ 55 | 56 | * Latest stable kernel: 57 | 58 | * is properly configured, 59 | * and includes additional security features imported from public patches. 60 | 61 | Hardware support 62 | ^^^^^^^^^^^^^^^^ 63 | 64 | * QEMU/KVM with virtio devices on Linux 65 | * Boot with Secure Boot enabled UEFI firmware 66 | 67 | 68 | 5.0 Beta: Main security & service enabling release 69 | -------------------------------------------------- 70 | 71 | .. admonition:: Status 72 | :class: tip 73 | 74 | Released on **2019-12-10**. See the `5.0 Beta milestone 75 | `_. 76 | 77 | Features 78 | ~~~~~~~~ 79 | 80 | Robust update system 81 | ^^^^^^^^^^^^^^^^^^^^ 82 | 83 | * Atomic system update using A/B partitions (similar to Android or ChromeOS) 84 | * Fallback system version available in case of unexpected failure or bug 85 | * Support for Core system updates 86 | 87 | System partition integrity and confidentiality 88 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 89 | 90 | * LUKS2/DM-Crypt/DM-Integrity support 91 | * Mandatory system read/write partition encryption (journal logs, 92 | configuration, etc.) 93 | * TPM-backed secret sealing and unsealing for unattended system partition 94 | decryption 95 | 96 | Confined system services 97 | ^^^^^^^^^^^^^^^^^^^^^^^^ 98 | 99 | * Confinement using Linux security features supported in systemd: 100 | 101 | * namespaces 102 | * cgroups 103 | * seccomp-bpf 104 | * capability bounding set 105 | * etc. 106 | 107 | Services available 108 | ^^^^^^^^^^^^^^^^^^ 109 | 110 | * IPsec client 111 | * Update daemon 112 | * SSH daemon 113 | 114 | Firewall rules 115 | ^^^^^^^^^^^^^^ 116 | 117 | * Static firewall rules for system services with IPsec awareness 118 | 119 | Confined (non-root) administration roles 120 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 121 | 122 | * Admin role: can edit some files in the state configuration folder 123 | * Audit role: can read all system logs 124 | * Administration roles are accessible through the IPsec tunnel, over SSH with 125 | key-based authentication only 126 | 127 | Linux kernel 128 | ^^^^^^^^^^^^ 129 | 130 | * Latest stable kernel: 131 | 132 | * Inclusion of additional security features, some expected to be merged 133 | upstream 134 | 135 | Hardware support 136 | ^^^^^^^^^^^^^^^^ 137 | 138 | * Initial laptop, desktop and server platforms support 139 | 140 | 141 | 5.0: First stable release with multi-level support 142 | -------------------------------------------------- 143 | 144 | .. admonition:: Status 145 | :class: notice 146 | 147 | In progress. See the `5.0 Stable milestone 148 | `_. 149 | 150 | Features 151 | ~~~~~~~~ 152 | 153 | User data integrity and confidentiality 154 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 155 | 156 | * Fixed size LUKS2/DM-Crypt/DM-Integrity based user partition support 157 | * Encryption based on user-only known secret 158 | * User credentials managed independently from system roles credentials 159 | * User credentials supported: 160 | 161 | * Password 162 | * Smartcard 163 | 164 | * Smartcard daemon isolation using Caml Crush 165 | 166 | Multi-level environment support 167 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 168 | 169 | * Multiple isolated environment available with different security settings: 170 | 171 | * Environments confined using a kernel LSM inspired from Vserver 172 | * Controlled communication between environments (UNIX sockets or encrypted 173 | connections) 174 | 175 | * Host and inter-levels interaction enabled through trusted services on the 176 | host: 177 | 178 | * File transfer, encryption and decryption using diodes 179 | 180 | * Intra-level application isolation using Flatpak 181 | 182 | Multi-level aware device assignment 183 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 184 | 185 | * Printers, scanners 186 | * USB flash drives 187 | * Smartcards 188 | * Webcam 189 | * Sound cards 190 | * Microphone 191 | 192 | Virtualized environments support 193 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 194 | 195 | * Linux only 196 | * virtio-based peripherals only 197 | * UEFI Secure Boot optional 198 | 199 | Firewall rules 200 | ^^^^^^^^^^^^^^ 201 | 202 | * Dynamic firewall rules for user environments 203 | 204 | Update system 205 | ^^^^^^^^^^^^^ 206 | 207 | * Support for user environment updates 208 | 209 | Trusted graphical environment 210 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 211 | 212 | * Wayland-based system compositor and lock screen 213 | * Permanently displayed and trusted panel for interaction with system 214 | services and configuration 215 | 216 | Arbitrary code execution restrictions in user environments 217 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 218 | 219 | * Applied to interpreters (e.g. Bash, Python, Perl): ``O_MAYEXEC`` 220 | 221 | Linux kernel 222 | ^^^^^^^^^^^^ 223 | 224 | * Additional kernel version supported: latest LTS kernel: 225 | 226 | * Supported until the next upstream LTS kernel release 227 | 228 | Hardware support 229 | ^^^^^^^^^^^^^^^^ 230 | 231 | * List of validated laptop, desktop and server platforms supported 232 | * Generic laptop, desktop and server platforms support 233 | 234 | Automatic installation 235 | ^^^^^^^^^^^^^^^^^^^^^^ 236 | 237 | * Automatic installer (PXE) with secret provisioning 238 | * Support for install time escrow keys setup for administrator enabled recovery 239 | 240 | 241 | Milestone features whose integration planning are yet to be determined 242 | ---------------------------------------------------------------------- 243 | 244 | .. admonition:: Status 245 | :class: warning 246 | 247 | Not started yet. 248 | 249 | * Optional system read-only partition (Core) encryption 250 | 251 | * Administration roles accessible locally on a console, using a password 252 | 253 | * Split credential management for password-based authentication (``pam-tcb``) 254 | 255 | * Remote integrity and version attestation using TPM-backed signatures 256 | 257 | * Port remaining security features from CLIP OS version 4: 258 | 259 | * Ignored SUID binaries 260 | * System entropy and RNG improvements: timer_entropyd, kernel patch 261 | * Remaining kernel features from CLIP LSM patches: 262 | 263 | * Veriexec: additional integrity measurements and capability granting tool 264 | 265 | * Mandatory Access Control support: 266 | 267 | * SELinux 268 | 269 | * Reproducible builds 270 | 271 | * Additional user credential support: 272 | 273 | * U2F-based user session unlocking 274 | 275 | * Append-only log storage and automatic log rotation support 276 | 277 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 278 | -------------------------------------------------------------------------------- /_sources/clipos/update.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2019 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _update: 7 | 8 | System updates 9 | ============== 10 | 11 | Safe, convenient and regular updates are required to ensure that a CLIP OS 12 | system is able to enforce and keep its security properties over time. 13 | 14 | .. admonition:: Goal of this document 15 | :class: notice 16 | 17 | This document is a global description of the update model. Please see the 18 | `update client documentation 19 | `_ for instructions on 20 | client configuration and server setup. 21 | 22 | Requirements 23 | ------------ 24 | 25 | The following properties are required for the interaction between updates and 26 | the local system (client side): 27 | 28 | * **Safe**: Updates must never interfere with the currently running system 29 | and must be safe to apply while the system is online and in use. 30 | * **In-background**: Updates should happen transparently to the user and in 31 | the background. 32 | * **Atomic**: Updates are either completely installed or not available as a 33 | choice during system boot. A system should always boot by default to a 34 | properly installed version and never into a partially updated system. 35 | * **Rollback**: If the newly updated system has issues, the user must be able 36 | to return temporarily to the previous version until a new update is 37 | available. 38 | 39 | The following properties are required to control update deployments (server 40 | side): 41 | 42 | * **Client identification**: Administrators must be able to identify requests 43 | for each client. This indirectly allows administrators to check for system 44 | usage and aliveness. 45 | * **Client version reporting**: Administrators must be able to identify which 46 | version is installed on each client. 47 | * **Update channels (alpha, beta, stable)**: Administrators must be able to 48 | progressively deploy an update to small groups of clients for live tests. 49 | 50 | Threats considered 51 | ------------------ 52 | 53 | Here is a list of threat scenario considered and for which we would like to 54 | protect the system from regarding the update process: 55 | 56 | 1. Compromised update server: 57 | 58 | * Has full control over the content served to the client. 59 | * Has no direct physical access to the system. 60 | * Does not have access to the update signing key. 61 | 62 | 2. Active man-in-the-middle attacker: 63 | 64 | * Has full control over the external network on which is connected the 65 | workstation. 66 | * Has no direct physical access to the system. 67 | * Does not have access to the update signing key. 68 | 69 | 3. Active local attacker: 70 | 71 | * Has full control over the external network on which is connected the 72 | workstation. 73 | * Has full physical access to the system. 74 | * Does not have access to the update signing key. 75 | 76 | Implementation 77 | -------------- 78 | 79 | CLIP OS systems have the following system layout: 80 | 81 | * UEFI boot only, following the `Boot Loader Specification 82 | `_. 83 | * A/B partition setup using Logical Volumes for system Read-Only partitions 84 | (for example: Core). 85 | * Single partition setup for stateful partitions. 86 | 87 | Updating a CLIP OS system is equivalent to: 88 | 89 | * Downloading the latest Core partition and EFI binary from the update 90 | server. 91 | * Installing the Core partition in the currently unused Logical Volume or 92 | creating a new one if only one exists. 93 | * Installing the EFI binary with a name following the `Boot Loader 94 | Specification `_ and 95 | removing binaries associated with previous and now unavailable versions. 96 | * Rebooting the system to automatically boot the new version. 97 | 98 | The requirements for the client are met with the following implementation: 99 | 100 | * **Safe**: Since updates are never applied onto files or partitions 101 | currently used by the running system, they can be performed without 102 | impacting the system integrity. 103 | * **In-background**: As updates do not impact the currently running system, 104 | they can performed in background without user interaction. They will only 105 | be effective after a reboot. There is no additional update process at 106 | shutdown/boot time. 107 | * **Atomic**: The system is either updated or not. Updates may be partially 108 | applied but the system will not see them and will always boot on the latest 109 | working version. Updates applied at the Logical Volume granularity for the 110 | system partition (Core). 111 | * **Rollback**: Two versions of the system are always available for user 112 | choice during boot. If the new system has critical bugs, the user may 113 | choose to revert to the previously working version until the next update. 114 | 115 | The requirements for control applied on the server side are met with the 116 | following implementation: 117 | 118 | * **Client identification**: Each request made by the client includes the 119 | system's current machine-id thus providing a unique and stable identifier. 120 | * **Client version reporting**: Each request made by the client includes the 121 | system's current version. 122 | * **Update channels (alpha, beta, stable)**: As version and identification 123 | are provided on each request, the server is able to decide which version to 124 | provide to each client. 125 | 126 | .. admonition:: Status 127 | :class: notice 128 | 129 | The server side implementation of update channels has not been 130 | implemented yet. 131 | 132 | Security 133 | ~~~~~~~~ 134 | 135 | The update process security properties are implemented using the following 136 | security features: 137 | 138 | * In transport confidentiality and integrity: 139 | 140 | * HTTPS using TLS 1.2 & 1.3 only. 141 | * Pinned Root Certificate Authority (requires an empty set of system 142 | certificates). 143 | 144 | * At rest integrity: 145 | 146 | * Each update payload is verified using a cryptographic signature produced 147 | by `minisign` / `rsign2`. 148 | 149 | * Rollback resistance (during update process): 150 | 151 | * Update payload versions are specified as trusted comment in the signature 152 | and are validated before the update is applied preventing an attacker 153 | from masquerading an old release as a new one. 154 | 155 | Unaddressed threats and potential weaknesses 156 | -------------------------------------------- 157 | 158 | * Offline rollback resistance: There is currently no protection against a local 159 | attacker replacing the currently installed version of the system by an older 160 | and valid version with direct disk access. 161 | 162 | * Update signing key compromise: There is currently no mitigation strategy for 163 | a compromise of the update signing key. 164 | -------------------------------------------------------------------------------- /_sources/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | Welcome to the CLIP OS project documentation! 7 | ============================================= 8 | 9 | This is the documentation for the CLIP OS project, the tools and the OS 10 | architecture. 11 | 12 | .. admonition:: Status of the project 13 | :class: warning 14 | 15 | The CLIP OS project is still in **beta** stage. Please check out the 16 | `project homepage `_ and the :ref:`project roadmap 17 | ` to know more about the CLIP OS project history, its current 18 | status and its objectives. 19 | 20 | .. admonition:: How to get started? 21 | :class: tip 22 | 23 | * If you wish to **try** CLIP OS, please check out the :ref:`quick try guide 24 | `. 25 | * If you wish to **build** an image of the CLIP OS project, please check out 26 | the :ref:`development environment setup ` and :ref:`build ` 27 | instructions. 28 | * If you wish to **contribue** to this project, please check out the 29 | :ref:`contribute` guide. 30 | * If you wish to **adapt** this project to your specific use case, please 31 | check out the :ref:`derive` guide. 32 | 33 | .. toctree:: 34 | :caption: CLIP OS 35 | :maxdepth: 2 36 | 37 | clipos/architecture 38 | clipos/security 39 | clipos/kernel 40 | clipos/boot_integrity 41 | clipos/update 42 | clipos/roadmap 43 | clipos/development 44 | 45 | .. toctree:: 46 | :caption: Development environment 47 | :maxdepth: 3 48 | 49 | toolkit/quick-try 50 | toolkit/setup 51 | toolkit/build 52 | toolkit/test 53 | toolkit/build-steps 54 | toolkit/source-tree 55 | toolkit/maintaining_portage_tree 56 | toolkit/maintaining_sdk 57 | 58 | .. toctree:: 59 | :caption: Contributing 60 | :maxdepth: 2 61 | 62 | toolkit/contribute 63 | toolkit/derive 64 | 65 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 66 | -------------------------------------------------------------------------------- /_sources/toolkit/build-steps.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _build-steps: 7 | 8 | Build steps 9 | =========== 10 | 11 | .. important:: 12 | 13 | This page details the purpose of each step in the project build process. 14 | Running steps manually is generally not needed for development as you may 15 | use directly the instructions from the :ref:`Building page `. 16 | 17 | Building the documentation 18 | -------------------------- 19 | 20 | The project documentation is built with Sphinx. The documentation sources are 21 | available in the ``docs-src`` directory. 22 | 23 | To build the documentation and to open it in your browser, run: 24 | 25 | .. code-block:: shell-session 26 | 27 | $ cosmk doc --build 28 | $ cosmk doc --open 29 | 30 | SDK 31 | --- 32 | 33 | To build the software components of CLIP OS, we use a SDK based on Gentoo 34 | Hardened. The SDK container is created by importing the upstream `stage 3 root 35 | filesystem `_ and updating 36 | it with a current copy of the upstream Gentoo Portage tree to include various 37 | utilities. If unavailable, the SDK is automatically imported from the 38 | configured CI or build locally, and may be manually rebuild from scratch using: 39 | 40 | .. code-block:: shell-session 41 | 42 | # Remove the current SDK container images 43 | $ podman rmi /clipos/sdk: # podman 44 | $ sudo docker rmi /clipos/sdk: # Docker 45 | 46 | # Set empty URLs for the 'registry' in the 'ci' section of the 'config.toml' 47 | $ $EDITOR config.toml 48 | 49 | # Bootstrap the SDK 50 | $ cosmk bootstrap sdk 51 | 52 | Core 53 | ---- 54 | 55 | The main rootfs in CLIP OS is called Core, and can be built using: 56 | 57 | .. code-block:: shell-session 58 | 59 | $ cosmk build core 60 | $ cosmk image core 61 | $ cosmk configure core 62 | $ cosmk bundle core 63 | 64 | EFI boot partition 65 | ------------------ 66 | 67 | EFI boot is the only supported boot method. The content of the EFI boot 68 | partition (bootloader, kernel image, etc.) is built using: 69 | 70 | .. code-block:: shell-session 71 | 72 | $ cosmk build efiboot 73 | $ cosmk image efiboot 74 | $ cosmk configure efiboot 75 | $ cosmk bundle efiboot 76 | 77 | Initial state for QEMU test image 78 | --------------------------------- 79 | 80 | To test the resulting OS in a QEMU virtual machine, we generate a tarball with 81 | the configuration to be installed in the system state partition: 82 | 83 | .. code-block:: shell-session 84 | 85 | $ cosmk bundle qemu 86 | 87 | QEMU image 88 | ---------- 89 | 90 | In order to test the resulting OS, we use ``libguestfs`` tools to assemble a 91 | QEMU qcow2 disk image to boot inside a EFI enabled virtual machine using 92 | ``libvirt``. The qcow2 QEMU image may be assembled using: 93 | 94 | .. code-block:: shell-session 95 | 96 | $ cosmk test --qemu 97 | 98 | Testbed environment setup 99 | ------------------------- 100 | 101 | To setup the virtual testbed environment with ``Vagrant`` and ``libvirt``, use: 102 | 103 | .. code-block:: shell-session 104 | 105 | $ cosmk test --setup 106 | 107 | Testing the QEMU image 108 | ---------------------- 109 | 110 | To setup a EFI & QEMU/KVM enabled virtual machine with ``libvirt``, use: 111 | 112 | .. code-block:: shell-session 113 | 114 | $ cosmk test --start 115 | 116 | Caching and binary packages 117 | --------------------------- 118 | 119 | To speed up the build process during development, we keep the output of each 120 | build action in the ``cache`` and ``out`` folders. The ``cache`` directory 121 | keeps binary packages and logs. The ``out`` directory keeps the intermediate 122 | rootfs and temporary files that are safe to remove before a rebuild. 123 | 124 | By default, the ``cosmk`` tool will clear the ``out`` folder and reuse cached 125 | output (mainly packages) to speedup iterative development builds. To restart 126 | everything from scratch: 127 | 128 | .. code-block:: shell-session 129 | 130 | $ rm -rf out cache 131 | # If using Docker or rootfull podman 132 | $ sudo rm -rf out cache 133 | 134 | .. admonition:: Pre-built binary packages by a continuous integration 135 | infrastructure (GitLab CI) 136 | :class: important 137 | 138 | We use GitLab CI to automatically build CLIP OS. The GitLab CI configuration 139 | and build scripts are tracked in the `clipos/ci 140 | `_ repository and the resulting artifacts are 141 | made available at `files.clip-os.org `_. 142 | 143 | To download CI-built binary packages from the last successful CI job, use: 144 | 145 | .. code-block:: shell-session 146 | 147 | $ cosmk cache 148 | 149 | SDKs are automatically downloaded from the CI if configured in ``config.toml``. 150 | 151 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 152 | -------------------------------------------------------------------------------- /_sources/toolkit/build.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _build: 7 | 8 | Building 9 | ======== 10 | 11 | .. admonition:: Before going further, ensure to get a functional build 12 | environment setup 13 | :class: important 14 | 15 | You must complete the :ref:`environment setup ` before executing any 16 | command from this page. 17 | 18 | Building the CLIP OS toolkit (cosmk) 19 | ------------------------------------ 20 | 21 | To build the CLIP OS toolkit, run and follow the setup instructions from the 22 | script: 23 | 24 | .. code-block:: shell-session 25 | 26 | $ ./toolkit/setup.sh 27 | 28 | Creating a ``config.toml`` for cosmk 29 | ------------------------------------ 30 | 31 | We now need to tell ``cosmk`` what it should build by writing a ``config.toml`` 32 | file at the repository root directory. A working default configuration to build 33 | the CLIP OS project is provided in the ``config.toml.example`` file from the 34 | ``toolkit`` repository: 35 | 36 | .. code-block:: shell-session 37 | 38 | $ cp toolkit/config.toml.example config.toml 39 | 40 | Instrumentation features for testing 41 | ------------------------------------ 42 | 43 | Default builds of the project are meant to be set up with a production-ready 44 | configuration. There is currently no password-based local login available in 45 | this configuration. Thus if you want to test the project in QEMU, you will 46 | have to enable some :ref:`instrumentation features ` in 47 | ``config.toml``. Here are some good defaults for development builds: 48 | 49 | .. code-block:: shell-session 50 | 51 | $ sed -i '/#"instrumented-core"/s/#//g' config.toml 52 | $ sed -i '/#"passwordless-root-login"/s/#//g' config.toml 53 | $ sed -i '/#"allow-ssh-root-login"/s/#//g' config.toml 54 | $ sed -i '/#"instrumented-initramfs"/s/#//g' config.toml 55 | $ sed -i '/#"initramfs-no-require-tpm"/s/#//g' config.toml 56 | $ sed -i '/#"initramfs-no-tpm-lockout"/s/#//g' config.toml 57 | $ sed -i '/#"test-update"/s/#//g' config.toml 58 | 59 | This configuration will keep most system configuration unchanged, will install 60 | common tools (vim, tar, grep, etc.) and will give you local password-less 61 | `root` access. 62 | 63 | .. note:: 64 | 65 | Any change of instrumentation features requires a full project rebuild. 66 | 67 | Building the full project 68 | ------------------------- 69 | 70 | You will then be able to use ``cosmk`` to run commands to build CLIP OS. 71 | Building the CLIP OS project requires multiple successive steps that are 72 | described in TOML files called ``recipes``. 73 | 74 | By default, to reduce compilation time, ``cosmk`` will download pre-built SDKs 75 | from the public CLIP OS CI infrastructure. To further reduce compilation time, 76 | you may also download binary packages from the public CLIP OS CI using: 77 | 78 | .. code-block:: shell-session 79 | 80 | $ cosmk cache 81 | 82 | To run all the steps required to build CLIP OS: 83 | 84 | .. code-block:: shell-session 85 | 86 | $ cosmk all 87 | 88 | Congratulations, you are now ready to :ref:`test CLIP OS `. 89 | 90 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 91 | -------------------------------------------------------------------------------- /_sources/toolkit/contribute.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _contribute: 7 | 8 | How to contribute 9 | ================= 10 | 11 | Getting started 12 | --------------- 13 | 14 | To work on the CLIP OS project, you should start with the :ref:`toolkit 15 | environment setup ` instructions. 16 | 17 | Bug reports 18 | ----------- 19 | 20 | Bugs should be reported as issues in the `bugs repository on GitHub 21 | `_. 22 | 23 | Submitting patches and code review 24 | ---------------------------------- 25 | 26 | We use `Gerrit `_ to review changes for the 27 | project. You may submit patches at `review.clip-os.org 28 | `_ (see Gerrit's `User Guide 29 | `_ 30 | if you are new to Gerrit). 31 | 32 | .. note:: 33 | A GitHub account is required to log into this Gerrit instance. 34 | 35 | .. note:: 36 | In order to push commits for review, you need to use an `HTTP password 37 | randomly generated by Gerrit 38 | `_. Please note that 39 | you can not use your GitHub credentials to push changes to 40 | `review.clip-os.org `_. Git access is only 41 | provided over HTTPS (i.e. no SSH). 42 | 43 | .. note:: 44 | You should use ``https://review.clip-os.org/clipos/manifest`` as the manifest URL for 45 | ``repo init`` (see `toolkit environment setup 46 | `_). 47 | 48 | You may also init the master branch as follows: 49 | 50 | .. code-block:: shell-session 51 | 52 | $ repo start master --all 53 | 54 | Low difficulty issues 55 | --------------------- 56 | 57 | We have tagged some issues with the `good first issue` label to help you 58 | identify low difficulty tasks for first time contributors to the project. You 59 | may find them in the `bugs repository 60 | `_. 61 | 62 | Continuous integration 63 | ---------------------- 64 | 65 | We use `GitLab CI `_ to automatically build 66 | CLIP OS and the projects composing it. The GitLab CI configuration is available 67 | in the `CI repository `_, the build status can be 68 | tracked on `GitLab `_ and the build 69 | artifacts for each pipeline are available at `files.clip-os.org 70 | `_. 71 | 72 | Discussion space 73 | ---------------- 74 | 75 | Discussions about the project should happen on our `Discourse 76 | `_ instance at `discuss.clip-os.org 77 | `_. Please ask questions there and feel 78 | free to submit ideas. You may log in with your GitHub account. 79 | 80 | Please contact us before committing time on an issue or a change to make sure 81 | we will be able to integrate it once completed. 82 | 83 | If you have specific questions, you may also send a mail to `clipos@ssi.gouv.fr 84 | `_. 85 | 86 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 87 | -------------------------------------------------------------------------------- /_sources/toolkit/derive.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _derive: 7 | 8 | How to derive this project 9 | ========================== 10 | 11 | We designed the project to be extensible and maintainable over time for 12 | downstream derivative projects. 13 | 14 | .. admonition:: Work in progress 15 | :class: note 16 | 17 | We will add more information about the way you may extend the CLIP OS 18 | project with your own changes in a near future. 19 | 20 | .. admonition:: CLIP OS trademark 21 | :class: warning 22 | 23 | CLIP OS is a trademark of the French Republic. As a consequence, any use of 24 | the name "CLIP OS" has to be first authorized by the ANSSI. This does not 25 | preclude changes to the software posted online and their republication or 26 | quotation from identifying the original software under the terms of the LGPL 27 | v2.1+ license. Regardless, no use of the name "CLIP OS" on a modified 28 | version should suggest that this version is the original work published by 29 | the ANSSI. 30 | 31 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 32 | -------------------------------------------------------------------------------- /_sources/toolkit/maintaining_portage_tree.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2020 ANSSI. 2 | CLIP OS is a trademark of the French Republic. Content licensed under the Open License version 2.0 as published by Etalab 3 | (French task force for Open Data). 4 | 5 | .. _maintaining_portage_tree: 6 | 7 | Maintaining the Portage tree 8 | ============================ 9 | 10 | CLIP OS leverages the `portage-derive `_ 11 | tool to efficiently maintain its Portage tree. 12 | 13 | Fetching the upstream Portage tree 14 | ---------------------------------- 15 | 16 | First, start by retrieving the latest Gentoo Portage tree using the 17 | ``fetch-upstreams`` helper script: 18 | 19 | .. code-block:: shell-session 20 | 21 | $ repo forall src_portage_gentoo --command "fetch-upstreams.sh" 22 | 23 | This will fetch upstream remote references and update the local 24 | ``upstream/gentoo/master`` branch. 25 | 26 | Updating the Portage tree using portage-derive 27 | ---------------------------------------------- 28 | 29 | In compliance with the `portage-derive documentation 30 | `_, 31 | an *artificial merge* should be started to keep track of the Git history: 32 | 33 | .. code-block:: shell-session 34 | 35 | $ cd src/portage/gentoo 36 | $ git checkout autoclean 37 | $ git merge --no-commit --strategy=ours upstream/gentoo/master 38 | $ git read-tree -u -m upstream/gentoo/master 39 | 40 | Next, **enter the SDK** and **equalize** the Portage tree: 41 | 42 | .. code-block:: shell-session 43 | 44 | $ cosmk run sdk 45 | 46 | # cd /mnt/src/portage/gentoo 47 | # egencache --update "--jobs=$(($(nproc) + 1))" --repo=gentoo 48 | # portage-derive --portdir . \ 49 | --profile /mnt/src/portage/clipos/profiles/clipos/arch/amd64/core \ 50 | --profile /mnt/src/portage/clipos/profiles/clipos/arch/amd64/efiboot \ 51 | --profile /mnt/src/portage/clipos/profiles/clipos/arch/amd64/sdk \ 52 | equalize 53 | 54 | **Exit the SDK** and commit the merge: 55 | 56 | .. code-block:: shell-session 57 | 58 | # exit 59 | 60 | $ git add --all 61 | $ git commit --message="Merge branch 'upstream/gentoo/master' into autoclean" 62 | 63 | Finally, merge the *equalized* branch into the ``master`` branch, which 64 | contains CLIP OS custom changes: 65 | 66 | .. code-block:: shell-session 67 | 68 | $ git checkout master 69 | $ git merge autoclean 70 | 71 | Manually deal with the remaining merge conflicts, if any. 72 | 73 | .. admonition:: Before going further, make sure to bootstrap a new SDK 74 | :class: important 75 | 76 | Before rebuilding CLIP OS with the now up-to-date Portage tree, a new SDK 77 | should be :ref:`rebuilt `. 78 | 79 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 80 | -------------------------------------------------------------------------------- /_sources/toolkit/maintaining_sdk.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2020 ANSSI. 2 | CLIP OS is a trademark of the French Republic. Content licensed under the Open License version 2.0 as published by Etalab 3 | (French task force for Open Data). 4 | 5 | .. _maintaining_sdk: 6 | 7 | Maintaining the SDK 8 | =================== 9 | 10 | .. admonition:: Before going further, make sure to update the Portage tree 11 | :class: important 12 | 13 | You should complete the :ref:`Portage tree update ` 14 | steps before executing any command from this page. 15 | 16 | 17 | Grabbing a new Gentoo stage 3 tarball 18 | ------------------------------------- 19 | 20 | In order to obtain the latest Gentoo stage 3 tarball, use the ``vendor-gentoo-stage3`` 21 | helper script, which shall store it in ``assets/gentoo``: 22 | 23 | .. code-block:: shell-session 24 | 25 | $ toolkit/helpers/vendor-gentoo-stage3.sh 26 | 27 | Updating the SDK recipe 28 | ----------------------- 29 | 30 | The SDK recipe then **needs** to be updated: 31 | 32 | .. code-block:: shell-session 33 | 34 | # product/clipos/sdk/sdk.toml 35 | tag = 36 | rootfs = "assets/gentoo/stage3-amd64-hardened+nomultilib-.tar.xz" 37 | 38 | Rebuilding the SDK from scratch 39 | ------------------------------- 40 | 41 | * Remove all **distfiles** from the ``assets/distfiles`` directory (**and only 42 | distfiles**, do not delete ``README.md`` nor hidden configuration files) 43 | * Delete the ``out/sdk`` and ``cache/sdk`` directories. 44 | * **Disable** all instrumentation features for the SDK build and rebuild the 45 | SDK: 46 | 47 | .. code-block:: shell-session 48 | 49 | $ cosmk bootstrap sdk 50 | 51 | The resulting SDK can then be employed, for instance, to launch a full project 52 | rebuild with the up-to-date Portage tree and the desired instrumentation 53 | features. 54 | 55 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 56 | -------------------------------------------------------------------------------- /_sources/toolkit/quick-try.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2019 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _quick-try: 7 | 8 | Quick try guide 9 | =============== 10 | 11 | .. important:: 12 | 13 | **Those files are provided AS IS for TESTING PURPOSES ONLY and MUST NOT be 14 | used in a PRODUCTION CONTEXT.** 15 | 16 | To easily try the latest version (nightly build) of CLIP OS 5, you may download 17 | pre-built packages, SDK and pre-installed QEMU images from `files.clip-os.org 18 | `_. 19 | 20 | Be aware that those packages and QEMU images are instrumented, which means they 21 | allow full root access without any password on the system. 22 | 23 | To run the CLIP OS system in a virtual machine, you will have to install QEMU. 24 | It is also strongly recommended to have KVM support enabled for your current 25 | user (i.e. your current user is part of the ``kvm`` group). 26 | 27 | .. code-block:: shell-session 28 | 29 | # For Debian & Ubuntu 30 | $ sudo apt-get install qemu-system-x86 31 | 32 | # For Fedora & CentOS 33 | $ sudo dnf install -y qemu-system-x86 34 | 35 | # For Arch Linux 36 | $ sudo pacman -Syu qemu 37 | 38 | Then, you can download and start a CLIP OS QEMU virtual machine with the 39 | following commands: 40 | 41 | .. code-block:: shell-session 42 | 43 | # Pick the latest successful build from https://gitlab.com/CLIPOS/ci/pipelines 44 | $ BUILD="$(curl 'https://gitlab.com/api/v4/projects/14752889/pipelines?scope=finished&status=success' | jq '.[0].id')" 45 | 46 | # Retrieve the QEMU image 47 | $ wget https://files.clip-os.org/$BUILD/qemu.tar.zst 48 | 49 | # Extract and enter directory 50 | $ tar xf qemu.tar.zst && cd clipos_*_qemu 51 | 52 | # Read the README 53 | $ cat README.md 54 | 55 | # Start CLIP OS with QEMU 56 | $ ./qemu.sh 57 | 58 | # Start CLIP OS with QEMU without KVM support (not supported, may have issues) 59 | # See: https://discuss.clip-os.org/t/qemu-system-x86-64-overcommit-invalid-option-at-boot/76/12 60 | $ ./qemu-nokvm.sh 61 | 62 | You can login as root with no password. 63 | 64 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 65 | -------------------------------------------------------------------------------- /_sources/toolkit/source-tree.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2018 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | Source tree organization 7 | ======================== 8 | 9 | This page is intended to give you a quick look of the overall organization of 10 | the CLIP OS source tree as managed by the `repo 11 | `_ tool. 12 | 13 | .. sidebar:: Non-exhaustive representation of the source tree 14 | 15 | This document has a structure that reflects the CLIP OS source tree but is 16 | not intended to be exhaustive. Some directories and files are intentionally 17 | missing as they do not matter to understand the organizational logic of the 18 | CLIP OS source tree. 19 | 20 | .. contents:: Source tree contents 21 | :local: 22 | 23 | .. admonition:: About the nomenclature of the underlying Git repositories 24 | :class: note 25 | 26 | The Git repositories behind each sub-directory of the CLIP OS source tree 27 | have a specific nomenclature intended to reflect the location of the Git 28 | repository "check-out" in the CLIP OS source tree. 29 | 30 | However, due to a limitation of GitHub-hosted repositories, we could not use 31 | forward slashes (``/``) in the Git repository names. Folder separators are 32 | therefore representated by underscores (``_``) in those repository names. If 33 | a sub-directory path already contains an underscore character, (e.g., for a 34 | third-party project under ``src/external/``), then the underlying Git 35 | repository name should have the problematic underscores stripped. 36 | 37 | .. csv-table:: Example of Git nomenclature 38 | :header: "Sub-directory path", "Underlying Git repository name" 39 | 40 | "``manifest/``", "``manifest``" 41 | "``products/clipos/``", "``products_clipos``" 42 | "``src/external/super_tool-linux/`` *(hypothetical)*", "``src_external_supertool-linux``" 43 | 44 | ``.repo/`` 45 | ---------- 46 | 47 | The ``.repo`` directory holds the internal objects and files of the *repo* 48 | tool. 49 | 50 | .. admonition:: Do not mess with the contents of this directory 51 | :class: warning 52 | 53 | This ``.repo`` directory should not be messed with as it holds all the 54 | ``.git`` directories (i.e., the internal Git working directories) of all the 55 | sub-projects of this source tree managed by *repo*. 56 | 57 | ``assets/`` 58 | ----------- 59 | 60 | The sub-directories of this folder enclose all kinds of binaries or archive 61 | files that are required either to build CLIP OS or to make the CLIP OS toolkit 62 | work on a development environment that meets the :ref:`minimal environment 63 | requirements `. 64 | 65 | Providing those assets in the source tree also allows the usage of the CLIP OS 66 | toolkit on an offline development setup (e.g., a build environment in a 67 | security constrained infrastructure) and thus the lack of dependency on any 68 | remote resource. 69 | 70 | .. admonition:: Git LFS-backed repositories 71 | :class: warning 72 | 73 | As most of the underlying directories store large (and often binary) files, 74 | most of them rely on Git LFS for the revision of those large files to avoid 75 | cluttering their Git repository internal objects. 76 | 77 | ``assets/distfiles/`` 78 | ~~~~~~~~~~~~~~~~~~~~~ 79 | 80 | This directory holds the *distfiles* from Gentoo which serve for the Gentoo 81 | **ebuild** files. 82 | 83 | ``assets/gentoo/`` 84 | ~~~~~~~~~~~~~~~~~~ 85 | 86 | This directory contains the Gentoo *stage3* image that serves to bootstrap the 87 | CLIP OS SDK. 88 | 89 | ``cache/`` 90 | ---------- 91 | 92 | This directory encloses all the build by-products that are not required to 93 | build CLIP OS from scratch. This directory and its contents can be safely 94 | erased from a building machine. In this case, the toolkit will then build 95 | entirely from scratch. 96 | 97 | The subdirectories in this folder will reflect the 98 | ``out////`` tree. 99 | 100 | ``cache////binpkgs/`` 101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 | 103 | The binary packages produced by Portage/emerge during each *build* step and 104 | that serve to build the target root images populated only with 105 | runtime-dependencies (since the only way to deploy Portage packages without any 106 | build-dependency is to emerge them only from binary packages, otherwise emerge 107 | may need to emerge build-dependencies that may not be required or wanted in the 108 | target root). 109 | 110 | Another purpose of this directory is to provide emerge with a complete set of 111 | the packages already compiled to speed up builds and image construction by 112 | avoiding pointless identical package rebuilds (``emerge`` is configured to 113 | properly manage the comparison between the compilation settings, the USE flag 114 | sets of the binary packages and the packages to be deployed in a specified 115 | target root and will trigger a rebuild if those do not match). Usually, on 116 | developers workstations, the contents of this directory are meant to be 117 | populated with the binary packages archive set produced by the continuous 118 | integration server during the nightly build. This will prevent annoying and 119 | time-consuming package builds on the developers' machines. 120 | 121 | ``docs-src/`` 122 | ------------- 123 | 124 | This directory encloses all the documentation related to the CLIP OS project. 125 | 126 | ``docs-src/clipos/`` 127 | ~~~~~~~~~~~~~~~~~~~~ 128 | 129 | Documentation of the CLIP OS product itself. 130 | 131 | ``docs-src/toolkit/`` 132 | ~~~~~~~~~~~~~~~~~~~~~ 133 | 134 | Documentation of the CLIP OS toolkit and build steps. 135 | 136 | ``manifest/`` 137 | ------------- 138 | 139 | This directory encloses all the repo manifest files in charge of constructing 140 | the whole CLIP OS source tree. 141 | 142 | .. admonition:: This is not the manifest check-out directory on which *repo* is 143 | working on. 144 | :class: warning 145 | 146 | *repo* does not work with the manifest files present in that specific 147 | directory but in the manifest files checked out in its internal directory 148 | (``.repo/manifests/``). Do not expect *repo* to take into account the 149 | changes you can introduce in that directory. 150 | 151 | The rationale behind this repository check-out is to serve only as a working 152 | directory for the developer to bring changes (before committing them) in the 153 | manifests files since it seems to be a bad practise to modify directly the 154 | manifests on which ``repo`` operates in ``.repo/manifests/``. This 155 | ``manifest/`` directory serves also as a working directory for the 156 | ``cosmk snapshot`` feature. 157 | 158 | 159 | ``out/`` 160 | -------- 161 | 162 | This directory encloses all the build results from commands run by the 163 | toolkit. 164 | 165 | .. admonition:: Watch out to the mount options of your current partition 166 | :class: warning 167 | 168 | Implementation detail: since the rootfs of the CLIP OS jails and targets are 169 | built within this directory, it must not be located on a filesystem mount 170 | point with options restricting filesystem features such as the creation of 171 | device nodes or the usage of executable files. In other words, options such 172 | as ``nodev``, ``noexec`` or ``nosuid`` **MUST NOT** be set on the underlying 173 | mount point of this directory. 174 | 175 | The sub-directories in this folder will reflect the ``//`` 176 | tree with separation with the version number. 177 | 178 | ``out////`` 179 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 180 | 181 | The output results for a given ```` of a specific ```` at 182 | version ````. 183 | 184 | .. admonition:: About the subdirectory ``root/`` below directories for the 185 | *build*, *image* and *configure* recipe actions 186 | :class: tip 187 | 188 | A specific ``root`` directory can be found under the directories dedicated 189 | to the *build*, *image* and *configure* recipe actions. This ``root`` 190 | directory is the location where the respective recipe actions are working to 191 | build the rootfs. 192 | 193 | You need to be careful not to change any file or folder (including modes or 194 | ownerships) under that directory because those changes may end up in the 195 | final built image for the corresponding recipe. It might not be a good idea 196 | to apply changes directly in these ``root`` directories except for 197 | experimenting tweaks while debugging. 198 | 199 | ``out////bundle/`` 200 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 201 | 202 | The output result of the ```` recipe form ```` version 203 | ```` product. *Bundle* recipe action is often the last recipe action 204 | and the only one to produce the tangible products (*e.g.* disk images, EFI 205 | binary) rather than a complete rootfs directory. 206 | 207 | ``products/`` 208 | ------------- 209 | 210 | This directory holds the project main build and configuration steps in the 211 | ``clipos`` subfolder. 212 | 213 | Each downstream project based on CLIP OS must create a directory here and 214 | mirror part of the CLIP OS directory hierarchy. 215 | 216 | .. admonition:: How to add a custom product? 217 | :class: tip 218 | 219 | Instructions on how to derive this project for your specific use case are 220 | available in the :ref:`derive` guide. 221 | 222 | ``products/clipos/`` 223 | ~~~~~~~~~~~~~~~~~~~~ 224 | 225 | The recipes files in charge of spawning SDK containers making use of the 226 | scripts below to build the sub-parts of CLIP OS and bundling them together in a 227 | final image or set of installable images. 228 | 229 | ``products/clipos/sdk/`` 230 | ^^^^^^^^^^^^^^^^^^^^^^^^ 231 | 232 | The recipe describing the CLIP OS SDK used by all CLIP OS recipes. 233 | 234 | ``products/clipos/core/`` 235 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 236 | 237 | The recipe describing the CLIP OS *core* root filesystem. 238 | 239 | ``products/clipos/efiboot/`` 240 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 241 | 242 | The recipe describing the CLIP OS *EFI boot* items. 243 | 244 | ``run/`` 245 | -------- 246 | 247 | Runtime working directory storing the ``cosmk`` binary and temporary QEMU 248 | images for testbed virtual machines. 249 | 250 | ``src/`` 251 | -------- 252 | 253 | Anything under this directory is source code of third-party or in-house 254 | projects. 255 | 256 | ``src/external/`` 257 | ~~~~~~~~~~~~~~~~~ 258 | 259 | This directory encloses all the repositories of external upstream sources that 260 | may receive patches specific to CLIP OS. 261 | 262 | ``src/external/linux/`` 263 | ^^^^^^^^^^^^^^^^^^^^^^^ 264 | 265 | Upstream Linux kernel sources with our sets of patches in dedicated branches. 266 | 267 | ``src/external/systemd/`` 268 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 269 | 270 | Upstream systemd source code with both `systemd 271 | `_ and `systemd-stable 272 | `_ code branches. 273 | 274 | ``src/platform/`` 275 | ~~~~~~~~~~~~~~~~~ 276 | 277 | This directory encloses all repositories of the in-house sub-projects that are 278 | part of CLIP OS. 279 | 280 | ``src/portage/`` 281 | ~~~~~~~~~~~~~~~~ 282 | 283 | This directory encloses all the Portage tree overlays exposed in the SDK. 284 | 285 | .. admonition:: Third-party Portage tree overlays 286 | :class: tip 287 | 288 | Any potential third-party Portage tree overlays must be added here. 289 | 290 | ``src/portage/gentoo/`` 291 | ^^^^^^^^^^^^^^^^^^^^^^^ 292 | 293 | The upstream Gentoo Portage tree. 294 | 295 | ``src/portage/clipos/`` 296 | ^^^^^^^^^^^^^^^^^^^^^^^ 297 | 298 | The CLIP OS Portage tree overlay containing ``ebuild`` files, *eclasses*, and 299 | Portage profiles that are specific to CLIP OS. 300 | 301 | ``toolkit/`` 302 | ------------ 303 | 304 | The CLIP OS toolkit (``cosmk``) and various helper scripts usefull for 305 | development. 306 | 307 | ``toolkit/cosmk/`` 308 | ~~~~~~~~~~~~~~~~~~ 309 | 310 | The ``cosmk`` tool written in Go with vendored dependencies. 311 | 312 | ``toolkit/helpers/`` 313 | ~~~~~~~~~~~~~~~~~~~~ 314 | 315 | This directory contains all the helpers scripts that are of particular interest 316 | for the project development common tasks. These tasks include (but are not 317 | limited to) the ability to process annotations in *repo* manifest files, e.g. 318 | for fetching or synchronizing upstream branches of downstream projects that are 319 | part of the CLIP OS source tree or for verifying OpenPGP signatures of Git 320 | commits. 321 | 322 | .. admonition:: Scripts under this directory are available in the ``PATH`` for 323 | easier access 324 | :class: tip 325 | 326 | When the CLIP OS toolkit environment is activated (see the ``activate`` 327 | script), the scripts under this directory are exposed in the environment 328 | ``PATH`` thanks to symbolic links in the CLIP OS toolkit virtualenv. 329 | 330 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 331 | -------------------------------------------------------------------------------- /_sources/toolkit/test.rst.txt: -------------------------------------------------------------------------------- 1 | .. Copyright © 2020 ANSSI. 2 | CLIP OS is a trademark of the French Republic. 3 | Content licensed under the Open License version 2.0 as published by Etalab 4 | (French task force for Open Data). 5 | 6 | .. _test: 7 | 8 | Testing 9 | ======= 10 | 11 | .. admonition:: Prerequisite steps 12 | :class: important 13 | 14 | You must complete the :ref:`environment setup ` and the :ref:`project 15 | build ` before executing any command from this page. 16 | 17 | Virtual testbed setup 18 | --------------------- 19 | 20 | In order to test some functionalities of a CLIP OS system, you will need a 21 | virtual infrastructure acting as testbed. To setup this infrastructure, use: 22 | 23 | .. code-block:: shell-session 24 | 25 | $ cosmk test --setup 26 | 27 | This will setup virtual networks using ``Vagrant`` with ``libvirt`` and create 28 | a Debian virtual machine running the following services: 29 | 30 | * IPsec gateway (``strongSwan``) 31 | * Update server (``nginx``) 32 | * Time synchronisation (``chrony``) 33 | * Log forwarding (``rsyslog``) 34 | 35 | Building a QEMU image and running using QEMU/KVM 36 | ------------------------------------------------ 37 | 38 | .. admonition:: TPM emulation support 39 | :class: important 40 | 41 | TPM emulation support (see `libtpms 42 | `_ and `swtpm 43 | `_ setup in :ref:`Environment setup 44 | `) is required to test the project under QEMU in the test 45 | environment. 46 | 47 | Alternatively, you may enable the ``initramfs-no-require-tpm`` 48 | instrumentation feature which will allow the initramfs to ask for a 49 | passphrase at bootup if TPM support is not available: 50 | 51 | .. code-block:: shell-session 52 | 53 | $ sed -i '/#"initramfs-no-require-tpm"/s/#//g' config.toml 54 | 55 | The default passphrase is ``clipos`` (for old builds, it used to be 56 | ``core_state_key``). 57 | 58 | Any change of instrumentation features requires a full project rebuild. 59 | 60 | To build a QCOW2 QEMU disk image and to setup a EFI & QEMU/KVM enabled virtual 61 | machine with ``libvirt``, use: 62 | 63 | .. code-block:: shell-session 64 | 65 | $ cosmk test --qemu 66 | 67 | .. admonition:: Local login disabled by default 68 | :class: important 69 | 70 | The default build configuration will create production images with root 71 | access disabled. To enable local passwordless root login, enable the 72 | ``passwordless-root-login`` instrumentation feature: 73 | 74 | .. code-block:: shell-session 75 | 76 | $ sed -i '/#"passwordless-root-login"/s/#//g' config.toml 77 | 78 | Any change of instrumentation features requires a full project rebuild. 79 | 80 | .. admonition:: Workaround for SELinux on Fedora, CentOS and RHEL 81 | :class: important 82 | 83 | To allow QEMU virtual machines access to files in your home directory, you 84 | need to turn SELinux into permissive mode for the ``svirt_t`` domain: 85 | 86 | .. code-block:: shell-session 87 | 88 | $ sudo semanage permissive --add svirt_t 89 | 90 | This change can be revert with: 91 | 92 | .. code-block:: shell-session 93 | 94 | $ sudo semanage permissive --delete svirt_t 95 | 96 | .. admonition:: Access to ``testbed/synced_folders`` for QEMU virtual machines 97 | :class: important 98 | 99 | Make sure that the directory ``testbed/synced_folders`` used by Vagrant is 100 | also accessible for everybody: 101 | 102 | .. code-block:: shell-session 103 | 104 | $ chmod o+x ~user{,/clipos{,/testbed{,/synced_folders}}} 105 | 106 | Access to QEMU virtual machine over SSH 107 | --------------------------------------- 108 | 109 | .. admonition:: Access disabled by default 110 | :class: important 111 | 112 | The default build configuration will create production images with SSH 113 | access available only over the IPsec tunnel. To enable SSH access from 114 | outside the IPsec tunnel, enable the ``allow-ssh-root-login`` 115 | instrumentation feature: 116 | 117 | .. code-block:: shell-session 118 | 119 | $ sed -i '/#"allow-ssh-root-login"/s/#//g' config.toml 120 | 121 | Any change of instrumentation features requires a full project rebuild. 122 | 123 | To access a QEMU virtual machine over SSH, retrieve the IP address using 124 | ``virsh`` and use the SSH keys stored in the cache directory: 125 | 126 | .. code-block:: shell-session 127 | 128 | $ virsh --connect qemu:///system domifaddr clipos-testbed_clipos-qemu 129 | Name MAC address Protocol Address 130 | ------------------------------------------------------------------------------- 131 | vnet2 XX:XX:XX:XX:XX:XX ipv4 172.27.1.XX/24 132 | $ ssh -i cache/clipos/5.0.0-alpha.1/qemu/bundle/ssh_root \ 133 | -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \ 134 | root@172.27.1.XX 135 | $ ssh -i cache/clipos/5.0.0-alpha.1/qemu/bundle/ssh_audit \ 136 | -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \ 137 | audit@172.27.1.XX 138 | $ ssh -i cache/clipos/5.0.0-alpha.1/qemu/bundle/ssh_admin \ 139 | -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \ 140 | admin@172.27.1.XX 141 | 142 | Access to vagrant virtual machine over SSH 143 | ------------------------------------------ 144 | 145 | To access a Vagrant virtual machine over SSH, you can use the ``vagrant ssh`` 146 | command in the testbed directory: 147 | 148 | .. code-block:: shell-session 149 | 150 | $ vagrant ssh ipsec-gw 151 | $ sudo -i 152 | 153 | Testing updates 154 | --------------- 155 | 156 | .. admonition:: Test updates disabled by default 157 | :class: important 158 | 159 | The default build configuration will create production images that do not 160 | include the insecure key used to verify the integrity of test updates. This 161 | key must not be used in production as the private one is public (included in 162 | the testbed repository). To include this key in system images and build test 163 | updates, enable the ``test-update`` instrumentation feature: 164 | 165 | .. code-block:: shell-session 166 | 167 | $ sed -i '/#"test-update"/s/#//g' config.toml 168 | 169 | Any change of instrumentation features requires a full project rebuild. 170 | 171 | Log in as ``root`` and start the update process with the following command: 172 | 173 | .. code-block:: shell-session 174 | 175 | $ systemctl start updater 176 | 177 | Testing chrony 178 | -------------- 179 | 180 | In order to test the NTP communication between CLIP OS and the IPsec gateway, 181 | log in as ``root`` in the Vagrant ipsec-gw virtual machine and list the clients connected to 182 | the IPsec side chrony server: 183 | 184 | .. code-block:: shell-session 185 | 186 | # chronyc -h /var/run/chrony-ipsec/chrony-ipsec.sock 187 | chronyc> clients 188 | Hostname NTP Drop Int IntL Last Cmd Drop Int Last 189 | =============================================================================== 190 | foo.example.net 12 0 6 - 23 0 0 - - 191 | 192 | Testing rsyslog 193 | --------------- 194 | 195 | To test journal forwarding between CLIP OS and the IPsec gateway, log in as 196 | ``root`` in the CLIP OS virtual machine and create a test log using the 197 | ``logger`` command: 198 | 199 | .. code-block:: shell-session 200 | 201 | $ logger -p local0.error "Test error log" && journalctl -n10 202 | 203 | Next, log in as ``root`` in the Vagrant ipsec-gw virtual machine and look for 204 | the log message we have just created. Logs are stored as json in the 205 | /var/log/remote folder: 206 | 207 | .. code-block:: shell-session 208 | 209 | $ grep 'Test error log' /var/log/remote//journal 210 | 211 | .. vim: set tw=79 ts=2 sts=2 sw=2 et: 212 | -------------------------------------------------------------------------------- /_static/ajax-loader.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/ajax-loader.gif -------------------------------------------------------------------------------- /_static/clipos_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/clipos_logo.png -------------------------------------------------------------------------------- /_static/comment-bright.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/comment-bright.png -------------------------------------------------------------------------------- /_static/comment-close.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/comment-close.png -------------------------------------------------------------------------------- /_static/comment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/comment.png -------------------------------------------------------------------------------- /_static/css/badge_only.css: -------------------------------------------------------------------------------- 1 | .fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-weight:normal;font-style:normal;src:url("../fonts/fontawesome-webfont.eot");src:url("../fonts/fontawesome-webfont.eot?#iefix") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff") format("woff"),url("../fonts/fontawesome-webfont.ttf") format("truetype"),url("../fonts/fontawesome-webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .icon-book{float:none}.rst-versions.rst-badge .fa-book{float:none}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} 2 | -------------------------------------------------------------------------------- /_static/css/colors.css: -------------------------------------------------------------------------------- 1 | /* 2 | * SPDX-License-Identifier: LGPL-2.1-or-later 3 | * Copyright © 2017 ANSSI. All rights reserved. 4 | */ 5 | 6 | /* Color profiles */ 7 | 8 | .green { 9 | color: green; 10 | } 11 | 12 | .orange { 13 | color: orange; 14 | } 15 | 16 | .red { 17 | color: red; 18 | } 19 | 20 | .olive { 21 | color: olive; 22 | } 23 | 24 | .navy { 25 | color: navy; 26 | } 27 | 28 | .darkviolet { 29 | color: darkviolet; 30 | } 31 | 32 | /* vim: set ts=2 sts=2 sw=2 et: */ 33 | -------------------------------------------------------------------------------- /_static/doctools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * doctools.js 3 | * ~~~~~~~~~~~ 4 | * 5 | * Sphinx JavaScript utilities for all documentation. 6 | * 7 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | 12 | /** 13 | * select a different prefix for underscore 14 | */ 15 | $u = _.noConflict(); 16 | 17 | /** 18 | * make the code below compatible with browsers without 19 | * an installed firebug like debugger 20 | if (!window.console || !console.firebug) { 21 | var names = ["log", "debug", "info", "warn", "error", "assert", "dir", 22 | "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", 23 | "profile", "profileEnd"]; 24 | window.console = {}; 25 | for (var i = 0; i < names.length; ++i) 26 | window.console[names[i]] = function() {}; 27 | } 28 | */ 29 | 30 | /** 31 | * small helper function to urldecode strings 32 | */ 33 | jQuery.urldecode = function(x) { 34 | return decodeURIComponent(x).replace(/\+/g, ' '); 35 | }; 36 | 37 | /** 38 | * small helper function to urlencode strings 39 | */ 40 | jQuery.urlencode = encodeURIComponent; 41 | 42 | /** 43 | * This function returns the parsed url parameters of the 44 | * current request. Multiple values per key are supported, 45 | * it will always return arrays of strings for the value parts. 46 | */ 47 | jQuery.getQueryParameters = function(s) { 48 | if (typeof s === 'undefined') 49 | s = document.location.search; 50 | var parts = s.substr(s.indexOf('?') + 1).split('&'); 51 | var result = {}; 52 | for (var i = 0; i < parts.length; i++) { 53 | var tmp = parts[i].split('=', 2); 54 | var key = jQuery.urldecode(tmp[0]); 55 | var value = jQuery.urldecode(tmp[1]); 56 | if (key in result) 57 | result[key].push(value); 58 | else 59 | result[key] = [value]; 60 | } 61 | return result; 62 | }; 63 | 64 | /** 65 | * highlight a given string on a jquery object by wrapping it in 66 | * span elements with the given class name. 67 | */ 68 | jQuery.fn.highlightText = function(text, className) { 69 | function highlight(node, addItems) { 70 | if (node.nodeType === 3) { 71 | var val = node.nodeValue; 72 | var pos = val.toLowerCase().indexOf(text); 73 | if (pos >= 0 && 74 | !jQuery(node.parentNode).hasClass(className) && 75 | !jQuery(node.parentNode).hasClass("nohighlight")) { 76 | var span; 77 | var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); 78 | if (isInSVG) { 79 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 80 | } else { 81 | span = document.createElement("span"); 82 | span.className = className; 83 | } 84 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 85 | node.parentNode.insertBefore(span, node.parentNode.insertBefore( 86 | document.createTextNode(val.substr(pos + text.length)), 87 | node.nextSibling)); 88 | node.nodeValue = val.substr(0, pos); 89 | if (isInSVG) { 90 | var bbox = span.getBBox(); 91 | var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); 92 | rect.x.baseVal.value = bbox.x; 93 | rect.y.baseVal.value = bbox.y; 94 | rect.width.baseVal.value = bbox.width; 95 | rect.height.baseVal.value = bbox.height; 96 | rect.setAttribute('class', className); 97 | var parentOfText = node.parentNode.parentNode; 98 | addItems.push({ 99 | "parent": node.parentNode, 100 | "target": rect}); 101 | } 102 | } 103 | } 104 | else if (!jQuery(node).is("button, select, textarea")) { 105 | jQuery.each(node.childNodes, function() { 106 | highlight(this, addItems); 107 | }); 108 | } 109 | } 110 | var addItems = []; 111 | var result = this.each(function() { 112 | highlight(this, addItems); 113 | }); 114 | for (var i = 0; i < addItems.length; ++i) { 115 | jQuery(addItems[i].parent).before(addItems[i].target); 116 | } 117 | return result; 118 | }; 119 | 120 | /* 121 | * backward compatibility for jQuery.browser 122 | * This will be supported until firefox bug is fixed. 123 | */ 124 | if (!jQuery.browser) { 125 | jQuery.uaMatch = function(ua) { 126 | ua = ua.toLowerCase(); 127 | 128 | var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || 129 | /(webkit)[ \/]([\w.]+)/.exec(ua) || 130 | /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || 131 | /(msie) ([\w.]+)/.exec(ua) || 132 | ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || 133 | []; 134 | 135 | return { 136 | browser: match[ 1 ] || "", 137 | version: match[ 2 ] || "0" 138 | }; 139 | }; 140 | jQuery.browser = {}; 141 | jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; 142 | } 143 | 144 | /** 145 | * Small JavaScript module for the documentation. 146 | */ 147 | var Documentation = { 148 | 149 | init : function() { 150 | this.fixFirefoxAnchorBug(); 151 | this.highlightSearchWords(); 152 | this.initIndexTable(); 153 | if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) { 154 | this.initOnKeyListeners(); 155 | } 156 | }, 157 | 158 | /** 159 | * i18n support 160 | */ 161 | TRANSLATIONS : {}, 162 | PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, 163 | LOCALE : 'unknown', 164 | 165 | // gettext and ngettext don't access this so that the functions 166 | // can safely bound to a different name (_ = Documentation.gettext) 167 | gettext : function(string) { 168 | var translated = Documentation.TRANSLATIONS[string]; 169 | if (typeof translated === 'undefined') 170 | return string; 171 | return (typeof translated === 'string') ? translated : translated[0]; 172 | }, 173 | 174 | ngettext : function(singular, plural, n) { 175 | var translated = Documentation.TRANSLATIONS[singular]; 176 | if (typeof translated === 'undefined') 177 | return (n == 1) ? singular : plural; 178 | return translated[Documentation.PLURALEXPR(n)]; 179 | }, 180 | 181 | addTranslations : function(catalog) { 182 | for (var key in catalog.messages) 183 | this.TRANSLATIONS[key] = catalog.messages[key]; 184 | this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); 185 | this.LOCALE = catalog.locale; 186 | }, 187 | 188 | /** 189 | * add context elements like header anchor links 190 | */ 191 | addContextElements : function() { 192 | $('div[id] > :header:first').each(function() { 193 | $('\u00B6'). 194 | attr('href', '#' + this.id). 195 | attr('title', _('Permalink to this headline')). 196 | appendTo(this); 197 | }); 198 | $('dt[id]').each(function() { 199 | $('\u00B6'). 200 | attr('href', '#' + this.id). 201 | attr('title', _('Permalink to this definition')). 202 | appendTo(this); 203 | }); 204 | }, 205 | 206 | /** 207 | * workaround a firefox stupidity 208 | * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 209 | */ 210 | fixFirefoxAnchorBug : function() { 211 | if (document.location.hash && $.browser.mozilla) 212 | window.setTimeout(function() { 213 | document.location.href += ''; 214 | }, 10); 215 | }, 216 | 217 | /** 218 | * highlight the search words provided in the url in the text 219 | */ 220 | highlightSearchWords : function() { 221 | var params = $.getQueryParameters(); 222 | var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; 223 | if (terms.length) { 224 | var body = $('div.body'); 225 | if (!body.length) { 226 | body = $('body'); 227 | } 228 | window.setTimeout(function() { 229 | $.each(terms, function() { 230 | body.highlightText(this.toLowerCase(), 'highlighted'); 231 | }); 232 | }, 10); 233 | $('

' + _('Hide Search Matches') + '

') 235 | .appendTo($('#searchbox')); 236 | } 237 | }, 238 | 239 | /** 240 | * init the domain index toggle buttons 241 | */ 242 | initIndexTable : function() { 243 | var togglers = $('img.toggler').click(function() { 244 | var src = $(this).attr('src'); 245 | var idnum = $(this).attr('id').substr(7); 246 | $('tr.cg-' + idnum).toggle(); 247 | if (src.substr(-9) === 'minus.png') 248 | $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); 249 | else 250 | $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); 251 | }).css('display', ''); 252 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { 253 | togglers.click(); 254 | } 255 | }, 256 | 257 | /** 258 | * helper function to hide the search marks again 259 | */ 260 | hideSearchWords : function() { 261 | $('#searchbox .highlight-link').fadeOut(300); 262 | $('span.highlighted').removeClass('highlighted'); 263 | }, 264 | 265 | /** 266 | * make the url absolute 267 | */ 268 | makeURL : function(relativeURL) { 269 | return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; 270 | }, 271 | 272 | /** 273 | * get the current relative url 274 | */ 275 | getCurrentURL : function() { 276 | var path = document.location.pathname; 277 | var parts = path.split(/\//); 278 | $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { 279 | if (this === '..') 280 | parts.pop(); 281 | }); 282 | var url = parts.join('/'); 283 | return path.substring(url.lastIndexOf('/') + 1, path.length - 1); 284 | }, 285 | 286 | initOnKeyListeners: function() { 287 | $(document).keyup(function(event) { 288 | var activeElementType = document.activeElement.tagName; 289 | // don't navigate when in search box or textarea 290 | if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') { 291 | switch (event.keyCode) { 292 | case 37: // left 293 | var prevHref = $('link[rel="prev"]').prop('href'); 294 | if (prevHref) { 295 | window.location.href = prevHref; 296 | return false; 297 | } 298 | case 39: // right 299 | var nextHref = $('link[rel="next"]').prop('href'); 300 | if (nextHref) { 301 | window.location.href = nextHref; 302 | return false; 303 | } 304 | } 305 | } 306 | }); 307 | } 308 | }; 309 | 310 | // quick alias for translations 311 | _ = Documentation.gettext; 312 | 313 | $(document).ready(function() { 314 | Documentation.init(); 315 | }); 316 | -------------------------------------------------------------------------------- /_static/documentation_options.js: -------------------------------------------------------------------------------- 1 | var DOCUMENTATION_OPTIONS = { 2 | URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), 3 | VERSION: '5.0.0_beta3', 4 | LANGUAGE: 'None', 5 | COLLAPSE_INDEX: false, 6 | FILE_SUFFIX: '.html', 7 | HAS_SOURCE: true, 8 | SOURCELINK_SUFFIX: '.txt', 9 | NAVIGATION_WITH_KEYS: false, 10 | }; -------------------------------------------------------------------------------- /_static/down-pressed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/down-pressed.png -------------------------------------------------------------------------------- /_static/down.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/down.png -------------------------------------------------------------------------------- /_static/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/favicon.ico -------------------------------------------------------------------------------- /_static/file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/file.png -------------------------------------------------------------------------------- /_static/fonts/Lato-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Bold.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Bold.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-BoldItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-BoldItalic.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-BoldItalic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-BoldItalic.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-Italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Italic.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Italic.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Regular.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/Lato-Regular.woff2 -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/RobotoSlab-Bold.ttf -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/RobotoSlab-Bold.woff2 -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/RobotoSlab-Regular.ttf -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/RobotoSlab-Regular.woff2 -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/fontawesome-webfont.eot -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/fontawesome-webfont.ttf -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/fontawesome-webfont.woff -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/fonts/fontawesome-webfont.woff2 -------------------------------------------------------------------------------- /_static/graphviz.css: -------------------------------------------------------------------------------- 1 | /* 2 | * graphviz.css 3 | * ~~~~~~~~~~~~ 4 | * 5 | * Sphinx stylesheet -- graphviz extension. 6 | * 7 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | 12 | img.graphviz { 13 | border: 0; 14 | max-width: 100%; 15 | } 16 | 17 | object.graphviz { 18 | max-width: 100%; 19 | } 20 | -------------------------------------------------------------------------------- /_static/js/theme.js: -------------------------------------------------------------------------------- 1 | var jQuery = (typeof(window) != 'undefined') ? window.jQuery : require('jquery'); 2 | 3 | // Sphinx theme nav state 4 | function ThemeNav () { 5 | 6 | var nav = { 7 | navBar: null, 8 | win: null, 9 | winScroll: false, 10 | winResize: false, 11 | linkScroll: false, 12 | winPosition: 0, 13 | winHeight: null, 14 | docHeight: null, 15 | isRunning: false 16 | }; 17 | 18 | nav.enable = function (withStickyNav) { 19 | var self = this; 20 | 21 | // TODO this can likely be removed once the theme javascript is broken 22 | // out from the RTD assets. This just ensures old projects that are 23 | // calling `enable()` get the sticky menu on by default. All other cals 24 | // to `enable` should include an argument for enabling the sticky menu. 25 | if (typeof(withStickyNav) == 'undefined') { 26 | withStickyNav = true; 27 | } 28 | 29 | if (self.isRunning) { 30 | // Only allow enabling nav logic once 31 | return; 32 | } 33 | 34 | self.isRunning = true; 35 | jQuery(function ($) { 36 | self.init($); 37 | 38 | self.reset(); 39 | self.win.on('hashchange', self.reset); 40 | 41 | if (withStickyNav) { 42 | // Set scroll monitor 43 | self.win.on('scroll', function () { 44 | if (!self.linkScroll) { 45 | if (!self.winScroll) { 46 | self.winScroll = true; 47 | requestAnimationFrame(function() { self.onScroll(); }); 48 | } 49 | } 50 | }); 51 | } 52 | 53 | // Set resize monitor 54 | self.win.on('resize', function () { 55 | if (!self.winResize) { 56 | self.winResize = true; 57 | requestAnimationFrame(function() { self.onResize(); }); 58 | } 59 | }); 60 | 61 | self.onResize(); 62 | }); 63 | 64 | }; 65 | 66 | // TODO remove this with a split in theme and Read the Docs JS logic as 67 | // well, it's only here to support 0.3.0 installs of our theme. 68 | nav.enableSticky = function() { 69 | this.enable(true); 70 | }; 71 | 72 | nav.init = function ($) { 73 | var doc = $(document), 74 | self = this; 75 | 76 | this.navBar = $('div.wy-side-scroll:first'); 77 | this.win = $(window); 78 | 79 | // Set up javascript UX bits 80 | $(document) 81 | // Shift nav in mobile when clicking the menu. 82 | .on('click', "[data-toggle='wy-nav-top']", function() { 83 | $("[data-toggle='wy-nav-shift']").toggleClass("shift"); 84 | $("[data-toggle='rst-versions']").toggleClass("shift"); 85 | }) 86 | 87 | // Nav menu link click operations 88 | .on('click', ".wy-menu-vertical .current ul li a", function() { 89 | var target = $(this); 90 | // Close menu when you click a link. 91 | $("[data-toggle='wy-nav-shift']").removeClass("shift"); 92 | $("[data-toggle='rst-versions']").toggleClass("shift"); 93 | // Handle dynamic display of l3 and l4 nav lists 94 | self.toggleCurrent(target); 95 | self.hashChange(); 96 | }) 97 | .on('click', "[data-toggle='rst-current-version']", function() { 98 | $("[data-toggle='rst-versions']").toggleClass("shift-up"); 99 | }) 100 | 101 | // Make tables responsive 102 | $("table.docutils:not(.field-list,.footnote,.citation)") 103 | .wrap("
"); 104 | 105 | // Add extra class to responsive tables that contain 106 | // footnotes or citations so that we can target them for styling 107 | $("table.docutils.footnote") 108 | .wrap("
"); 109 | $("table.docutils.citation") 110 | .wrap("
"); 111 | 112 | // Add expand links to all parents of nested ul 113 | $('.wy-menu-vertical ul').not('.simple').siblings('a').each(function () { 114 | var link = $(this); 115 | expand = $(''); 116 | expand.on('click', function (ev) { 117 | self.toggleCurrent(link); 118 | ev.stopPropagation(); 119 | return false; 120 | }); 121 | link.prepend(expand); 122 | }); 123 | }; 124 | 125 | nav.reset = function () { 126 | // Get anchor from URL and open up nested nav 127 | var anchor = encodeURI(window.location.hash) || '#'; 128 | 129 | try { 130 | var vmenu = $('.wy-menu-vertical'); 131 | var link = vmenu.find('[href="' + anchor + '"]'); 132 | if (link.length === 0) { 133 | // this link was not found in the sidebar. 134 | // Find associated id element, then its closest section 135 | // in the document and try with that one. 136 | var id_elt = $('.document [id="' + anchor.substring(1) + '"]'); 137 | var closest_section = id_elt.closest('div.section'); 138 | link = vmenu.find('[href="#' + closest_section.attr("id") + '"]'); 139 | if (link.length === 0) { 140 | // still not found in the sidebar. fall back to main section 141 | link = vmenu.find('[href="#"]'); 142 | } 143 | } 144 | // If we found a matching link then reset current and re-apply 145 | // otherwise retain the existing match 146 | if (link.length > 0) { 147 | $('.wy-menu-vertical .current').removeClass('current'); 148 | link.addClass('current'); 149 | link.closest('li.toctree-l1').addClass('current'); 150 | link.closest('li.toctree-l1').parent().addClass('current'); 151 | link.closest('li.toctree-l1').addClass('current'); 152 | link.closest('li.toctree-l2').addClass('current'); 153 | link.closest('li.toctree-l3').addClass('current'); 154 | link.closest('li.toctree-l4').addClass('current'); 155 | link[0].scrollIntoView(); 156 | } 157 | } 158 | catch (err) { 159 | console.log("Error expanding nav for anchor", err); 160 | } 161 | 162 | }; 163 | 164 | nav.onScroll = function () { 165 | this.winScroll = false; 166 | var newWinPosition = this.win.scrollTop(), 167 | winBottom = newWinPosition + this.winHeight, 168 | navPosition = this.navBar.scrollTop(), 169 | newNavPosition = navPosition + (newWinPosition - this.winPosition); 170 | if (newWinPosition < 0 || winBottom > this.docHeight) { 171 | return; 172 | } 173 | this.navBar.scrollTop(newNavPosition); 174 | this.winPosition = newWinPosition; 175 | }; 176 | 177 | nav.onResize = function () { 178 | this.winResize = false; 179 | this.winHeight = this.win.height(); 180 | this.docHeight = $(document).height(); 181 | }; 182 | 183 | nav.hashChange = function () { 184 | this.linkScroll = true; 185 | this.win.one('hashchange', function () { 186 | this.linkScroll = false; 187 | }); 188 | }; 189 | 190 | nav.toggleCurrent = function (elem) { 191 | var parent_li = elem.closest('li'); 192 | parent_li.siblings('li.current').removeClass('current'); 193 | parent_li.siblings().find('li.current').removeClass('current'); 194 | parent_li.find('> ul li.current').removeClass('current'); 195 | parent_li.toggleClass('current'); 196 | } 197 | 198 | return nav; 199 | }; 200 | 201 | _ThemeNav = ThemeNav(); 202 | 203 | if (typeof(window) != 'undefined') { 204 | window.SphinxRtdTheme = { 205 | Navigation: _ThemeNav, 206 | // TODO remove this once static assets are split up between the theme 207 | // and Read the Docs. For now, this patches 0.3.0 to be backwards 208 | // compatible with a pre-0.3.0 layout.html 209 | StickyNav: _ThemeNav, 210 | }; 211 | } 212 | 213 | 214 | // requestAnimationFrame polyfill by Erik Möller. fixes from Paul Irish and Tino Zijdel 215 | // https://gist.github.com/paulirish/1579671 216 | // MIT license 217 | 218 | (function() { 219 | var lastTime = 0; 220 | var vendors = ['ms', 'moz', 'webkit', 'o']; 221 | for(var x = 0; x < vendors.length && !window.requestAnimationFrame; ++x) { 222 | window.requestAnimationFrame = window[vendors[x]+'RequestAnimationFrame']; 223 | window.cancelAnimationFrame = window[vendors[x]+'CancelAnimationFrame'] 224 | || window[vendors[x]+'CancelRequestAnimationFrame']; 225 | } 226 | 227 | if (!window.requestAnimationFrame) 228 | window.requestAnimationFrame = function(callback, element) { 229 | var currTime = new Date().getTime(); 230 | var timeToCall = Math.max(0, 16 - (currTime - lastTime)); 231 | var id = window.setTimeout(function() { callback(currTime + timeToCall); }, 232 | timeToCall); 233 | lastTime = currTime + timeToCall; 234 | return id; 235 | }; 236 | 237 | if (!window.cancelAnimationFrame) 238 | window.cancelAnimationFrame = function(id) { 239 | clearTimeout(id); 240 | }; 241 | }()); 242 | -------------------------------------------------------------------------------- /_static/language_data.js: -------------------------------------------------------------------------------- 1 | /* 2 | * language_data.js 3 | * ~~~~~~~~~~~~~~~~ 4 | * 5 | * This script contains the language-specific data used by searchtools.js, 6 | * namely the list of stopwords, stemmer, scorer and splitter. 7 | * 8 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 9 | * :license: BSD, see LICENSE for details. 10 | * 11 | */ 12 | 13 | var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; 14 | 15 | 16 | /* Non-minified version JS is _stemmer.js if file is provided */ 17 | /** 18 | * Porter Stemmer 19 | */ 20 | var Stemmer = function() { 21 | 22 | var step2list = { 23 | ational: 'ate', 24 | tional: 'tion', 25 | enci: 'ence', 26 | anci: 'ance', 27 | izer: 'ize', 28 | bli: 'ble', 29 | alli: 'al', 30 | entli: 'ent', 31 | eli: 'e', 32 | ousli: 'ous', 33 | ization: 'ize', 34 | ation: 'ate', 35 | ator: 'ate', 36 | alism: 'al', 37 | iveness: 'ive', 38 | fulness: 'ful', 39 | ousness: 'ous', 40 | aliti: 'al', 41 | iviti: 'ive', 42 | biliti: 'ble', 43 | logi: 'log' 44 | }; 45 | 46 | var step3list = { 47 | icate: 'ic', 48 | ative: '', 49 | alize: 'al', 50 | iciti: 'ic', 51 | ical: 'ic', 52 | ful: '', 53 | ness: '' 54 | }; 55 | 56 | var c = "[^aeiou]"; // consonant 57 | var v = "[aeiouy]"; // vowel 58 | var C = c + "[^aeiouy]*"; // consonant sequence 59 | var V = v + "[aeiou]*"; // vowel sequence 60 | 61 | var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 62 | var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 63 | var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 64 | var s_v = "^(" + C + ")?" + v; // vowel in stem 65 | 66 | this.stemWord = function (w) { 67 | var stem; 68 | var suffix; 69 | var firstch; 70 | var origword = w; 71 | 72 | if (w.length < 3) 73 | return w; 74 | 75 | var re; 76 | var re2; 77 | var re3; 78 | var re4; 79 | 80 | firstch = w.substr(0,1); 81 | if (firstch == "y") 82 | w = firstch.toUpperCase() + w.substr(1); 83 | 84 | // Step 1a 85 | re = /^(.+?)(ss|i)es$/; 86 | re2 = /^(.+?)([^s])s$/; 87 | 88 | if (re.test(w)) 89 | w = w.replace(re,"$1$2"); 90 | else if (re2.test(w)) 91 | w = w.replace(re2,"$1$2"); 92 | 93 | // Step 1b 94 | re = /^(.+?)eed$/; 95 | re2 = /^(.+?)(ed|ing)$/; 96 | if (re.test(w)) { 97 | var fp = re.exec(w); 98 | re = new RegExp(mgr0); 99 | if (re.test(fp[1])) { 100 | re = /.$/; 101 | w = w.replace(re,""); 102 | } 103 | } 104 | else if (re2.test(w)) { 105 | var fp = re2.exec(w); 106 | stem = fp[1]; 107 | re2 = new RegExp(s_v); 108 | if (re2.test(stem)) { 109 | w = stem; 110 | re2 = /(at|bl|iz)$/; 111 | re3 = new RegExp("([^aeiouylsz])\\1$"); 112 | re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 113 | if (re2.test(w)) 114 | w = w + "e"; 115 | else if (re3.test(w)) { 116 | re = /.$/; 117 | w = w.replace(re,""); 118 | } 119 | else if (re4.test(w)) 120 | w = w + "e"; 121 | } 122 | } 123 | 124 | // Step 1c 125 | re = /^(.+?)y$/; 126 | if (re.test(w)) { 127 | var fp = re.exec(w); 128 | stem = fp[1]; 129 | re = new RegExp(s_v); 130 | if (re.test(stem)) 131 | w = stem + "i"; 132 | } 133 | 134 | // Step 2 135 | re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; 136 | if (re.test(w)) { 137 | var fp = re.exec(w); 138 | stem = fp[1]; 139 | suffix = fp[2]; 140 | re = new RegExp(mgr0); 141 | if (re.test(stem)) 142 | w = stem + step2list[suffix]; 143 | } 144 | 145 | // Step 3 146 | re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; 147 | if (re.test(w)) { 148 | var fp = re.exec(w); 149 | stem = fp[1]; 150 | suffix = fp[2]; 151 | re = new RegExp(mgr0); 152 | if (re.test(stem)) 153 | w = stem + step3list[suffix]; 154 | } 155 | 156 | // Step 4 157 | re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; 158 | re2 = /^(.+?)(s|t)(ion)$/; 159 | if (re.test(w)) { 160 | var fp = re.exec(w); 161 | stem = fp[1]; 162 | re = new RegExp(mgr1); 163 | if (re.test(stem)) 164 | w = stem; 165 | } 166 | else if (re2.test(w)) { 167 | var fp = re2.exec(w); 168 | stem = fp[1] + fp[2]; 169 | re2 = new RegExp(mgr1); 170 | if (re2.test(stem)) 171 | w = stem; 172 | } 173 | 174 | // Step 5 175 | re = /^(.+?)e$/; 176 | if (re.test(w)) { 177 | var fp = re.exec(w); 178 | stem = fp[1]; 179 | re = new RegExp(mgr1); 180 | re2 = new RegExp(meq1); 181 | re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 182 | if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) 183 | w = stem; 184 | } 185 | re = /ll$/; 186 | re2 = new RegExp(mgr1); 187 | if (re.test(w) && re2.test(w)) { 188 | re = /.$/; 189 | w = w.replace(re,""); 190 | } 191 | 192 | // and turn initial Y back to y 193 | if (firstch == "y") 194 | w = firstch.toLowerCase() + w.substr(1); 195 | return w; 196 | } 197 | } 198 | 199 | 200 | 201 | 202 | 203 | var splitChars = (function() { 204 | var result = {}; 205 | var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, 206 | 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, 207 | 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, 208 | 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, 209 | 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, 210 | 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, 211 | 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, 212 | 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, 213 | 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, 214 | 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; 215 | var i, j, start, end; 216 | for (i = 0; i < singles.length; i++) { 217 | result[singles[i]] = true; 218 | } 219 | var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], 220 | [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], 221 | [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], 222 | [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], 223 | [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], 224 | [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], 225 | [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], 226 | [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], 227 | [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], 228 | [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], 229 | [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], 230 | [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], 231 | [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], 232 | [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], 233 | [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], 234 | [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], 235 | [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], 236 | [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], 237 | [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], 238 | [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], 239 | [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], 240 | [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], 241 | [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], 242 | [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], 243 | [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], 244 | [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], 245 | [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], 246 | [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], 247 | [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], 248 | [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], 249 | [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], 250 | [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], 251 | [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], 252 | [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], 253 | [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], 254 | [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], 255 | [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], 256 | [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], 257 | [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], 258 | [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], 259 | [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], 260 | [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], 261 | [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], 262 | [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], 263 | [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], 264 | [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], 265 | [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], 266 | [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], 267 | [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; 268 | for (i = 0; i < ranges.length; i++) { 269 | start = ranges[i][0]; 270 | end = ranges[i][1]; 271 | for (j = start; j <= end; j++) { 272 | result[j] = true; 273 | } 274 | } 275 | return result; 276 | })(); 277 | 278 | function splitQuery(query) { 279 | var result = []; 280 | var start = -1; 281 | for (var i = 0; i < query.length; i++) { 282 | if (splitChars[query.charCodeAt(i)]) { 283 | if (start !== -1) { 284 | result.push(query.slice(start, i)); 285 | start = -1; 286 | } 287 | } else if (start === -1) { 288 | start = i; 289 | } 290 | } 291 | if (start !== -1) { 292 | result.push(query.slice(start)); 293 | } 294 | return result; 295 | } 296 | 297 | 298 | -------------------------------------------------------------------------------- /_static/minus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/minus.png -------------------------------------------------------------------------------- /_static/plus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/plus.png -------------------------------------------------------------------------------- /_static/pygments.css: -------------------------------------------------------------------------------- 1 | .highlight .hll { background-color: #ffffcc } 2 | .highlight { background: #eeffcc; } 3 | .highlight .c { color: #408090; font-style: italic } /* Comment */ 4 | .highlight .err { border: 1px solid #FF0000 } /* Error */ 5 | .highlight .k { color: #007020; font-weight: bold } /* Keyword */ 6 | .highlight .o { color: #666666 } /* Operator */ 7 | .highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ 8 | .highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ 9 | .highlight .cp { color: #007020 } /* Comment.Preproc */ 10 | .highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ 11 | .highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ 12 | .highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ 13 | .highlight .gd { color: #A00000 } /* Generic.Deleted */ 14 | .highlight .ge { font-style: italic } /* Generic.Emph */ 15 | .highlight .gr { color: #FF0000 } /* Generic.Error */ 16 | .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ 17 | .highlight .gi { color: #00A000 } /* Generic.Inserted */ 18 | .highlight .go { color: #333333 } /* Generic.Output */ 19 | .highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ 20 | .highlight .gs { font-weight: bold } /* Generic.Strong */ 21 | .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 22 | .highlight .gt { color: #0044DD } /* Generic.Traceback */ 23 | .highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ 24 | .highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ 25 | .highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ 26 | .highlight .kp { color: #007020 } /* Keyword.Pseudo */ 27 | .highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ 28 | .highlight .kt { color: #902000 } /* Keyword.Type */ 29 | .highlight .m { color: #208050 } /* Literal.Number */ 30 | .highlight .s { color: #4070a0 } /* Literal.String */ 31 | .highlight .na { color: #4070a0 } /* Name.Attribute */ 32 | .highlight .nb { color: #007020 } /* Name.Builtin */ 33 | .highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ 34 | .highlight .no { color: #60add5 } /* Name.Constant */ 35 | .highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ 36 | .highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ 37 | .highlight .ne { color: #007020 } /* Name.Exception */ 38 | .highlight .nf { color: #06287e } /* Name.Function */ 39 | .highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ 40 | .highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ 41 | .highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ 42 | .highlight .nv { color: #bb60d5 } /* Name.Variable */ 43 | .highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ 44 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */ 45 | .highlight .mb { color: #208050 } /* Literal.Number.Bin */ 46 | .highlight .mf { color: #208050 } /* Literal.Number.Float */ 47 | .highlight .mh { color: #208050 } /* Literal.Number.Hex */ 48 | .highlight .mi { color: #208050 } /* Literal.Number.Integer */ 49 | .highlight .mo { color: #208050 } /* Literal.Number.Oct */ 50 | .highlight .sa { color: #4070a0 } /* Literal.String.Affix */ 51 | .highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ 52 | .highlight .sc { color: #4070a0 } /* Literal.String.Char */ 53 | .highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ 54 | .highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ 55 | .highlight .s2 { color: #4070a0 } /* Literal.String.Double */ 56 | .highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ 57 | .highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ 58 | .highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ 59 | .highlight .sx { color: #c65d09 } /* Literal.String.Other */ 60 | .highlight .sr { color: #235388 } /* Literal.String.Regex */ 61 | .highlight .s1 { color: #4070a0 } /* Literal.String.Single */ 62 | .highlight .ss { color: #517918 } /* Literal.String.Symbol */ 63 | .highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ 64 | .highlight .fm { color: #06287e } /* Name.Function.Magic */ 65 | .highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ 66 | .highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ 67 | .highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ 68 | .highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ 69 | .highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ -------------------------------------------------------------------------------- /_static/up-pressed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/up-pressed.png -------------------------------------------------------------------------------- /_static/up.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/_static/up.png -------------------------------------------------------------------------------- /clipos/architecture.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | Architecture — CLIP OS 5.0.0_beta3 documentation 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 |
50 | 51 | 129 | 130 |
131 | 132 | 133 | 139 | 140 | 141 |
142 | 143 |
144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 |
162 | 163 |
    164 | 165 |
  • Docs »
    • 166 | 167 |
  • Architecture
    • 168 | 169 | 170 |
  • 171 | 172 | 173 | View page source 174 | 175 | 176 |
    • 177 | 178 |
179 | 180 | 181 |
182 |
183 |
184 |
185 | 186 |
187 |

Architecture

188 |
189 |

System components and their interactions

190 |

A CLIP OS system is split into several logically separated entities:

191 |
192 |
    193 |
  • A bootloader and an initial EFI binary responsible for the system 194 | start-up.
    • 195 |
  • A Core responsible for system service hosting and sub environments 196 | (called Cages from now on) start-up. The Core is also responsible for 197 | the isolation and control of all interactions between those Cages.
    • 198 |
  • One or several Cages usually available as graphical sessions for users. 199 | Each Cage may host applications and documents from a specific 200 | confidentiality level.
    • 201 |
202 |
203 |
204 | ../_images/clipos-high-level-architecture.svg

Fig. 1 High level overview of CLIP OS components

205 |
206 |

The execution environment of each Cage is logically isolated from the Core and 207 | from all the other Cages. Interactions between a Cage and the Core is carefully 208 | controlled and goes through confined and unprivileged services as shown in 209 | Fig. 2.

210 |
211 | ../_images/clipos-cage-and-service-isolation.svg

Fig. 2 Communication channels between a Cage, the Core and the hardware

212 |
213 |

Direct communication between Cages is forbidden. All inter-Cage interaction is 214 | mediated by services running in the Core.

215 |
216 | ../_images/clipos-inter-level-interactions.svg

Fig. 3 Flow of interaction required for inter-level communications

217 |
218 |
219 |
220 | 221 | 222 |
223 | 224 |
225 |
226 | 227 | 235 | 236 | 237 |
238 | 239 |
240 |

241 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 242 | 243 |

244 |
245 | Built with Sphinx using a theme provided by Read the Docs. 246 | 247 |
248 | 249 |
250 |
251 | 252 |
253 | 254 |
255 | 256 | 257 | 258 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | -------------------------------------------------------------------------------- /genindex.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | Index — CLIP OS 5.0.0_beta3 documentation 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
49 | 50 | 125 | 126 |
127 | 128 | 129 | 135 | 136 | 137 |
138 | 139 |
140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 |
158 | 159 |
    160 | 161 |
  • Docs »
    • 162 | 163 |
  • Index
    • 164 | 165 | 166 |
  • 167 | 168 | 169 | 170 |
    • 171 | 172 |
173 | 174 | 175 |
176 |
177 |
178 |
179 | 180 | 181 |

Index

182 | 183 |
184 | 185 |
186 | 187 | 188 |
189 | 190 |
191 |
192 | 193 | 194 |
195 | 196 |
197 |

198 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 199 | 200 |

201 |
202 | Built with Sphinx using a theme provided by Read the Docs. 203 | 204 |
205 | 206 |
207 |
208 | 209 |
210 | 211 |
212 | 213 | 214 | 215 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | -------------------------------------------------------------------------------- /objects.inv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clipos/docs/867a980f1acf6df77253443c81adc8a948409b91/objects.inv -------------------------------------------------------------------------------- /search.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | Search — CLIP OS 5.0.0_beta3 documentation 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
49 | 50 | 125 | 126 |
127 | 128 | 129 | 135 | 136 | 137 |
138 | 139 |
140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 |
158 | 159 |
    160 | 161 |
  • Docs »
    • 162 | 163 |
  • Search
    • 164 | 165 | 166 |
  • 167 | 168 | 169 | 170 |
    • 171 | 172 |
173 | 174 | 175 |
176 |
177 |
178 |
179 | 180 | 188 | 189 | 190 |
191 | 192 |
193 | 194 |
195 | 196 |
197 |
198 | 199 | 200 |
201 | 202 |
203 |

204 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 205 | 206 |

207 |
208 | Built with Sphinx using a theme provided by Read the Docs. 209 | 210 |
211 | 212 |
213 |
214 | 215 |
216 | 217 |
218 | 219 | 220 | 221 | 226 | 227 | 228 | 229 | 230 | 231 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | -------------------------------------------------------------------------------- /toolkit/derive.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | How to derive this project — CLIP OS 5.0.0_beta3 documentation 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
49 | 50 | 125 | 126 |
127 | 128 | 129 | 135 | 136 | 137 |
138 | 139 |
140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 |
158 | 159 |
    160 | 161 |
  • Docs »
    • 162 | 163 |
  • How to derive this project
    • 164 | 165 | 166 |
  • 167 | 168 | 169 | View page source 170 | 171 | 172 |
    • 173 | 174 |
175 | 176 | 177 |
178 |
179 |
180 |
181 | 182 |
183 |

How to derive this project

184 |

We designed the project to be extensible and maintainable over time for 185 | downstream derivative projects.

186 |
187 |

Work in progress

188 |

We will add more information about the way you may extend the CLIP OS 189 | project with your own changes in a near future.

190 |
191 |
192 |

CLIP OS trademark

193 |

CLIP OS is a trademark of the French Republic. As a consequence, any use of 194 | the name “CLIP OS” has to be first authorized by the ANSSI. This does not 195 | preclude changes to the software posted online and their republication or 196 | quotation from identifying the original software under the terms of the LGPL 197 | v2.1+ license. Regardless, no use of the name “CLIP OS” on a modified 198 | version should suggest that this version is the original work published by 199 | the ANSSI.

200 |
201 |
202 | 203 | 204 |
205 | 206 |
207 |
208 | 209 | 215 | 216 | 217 |
218 | 219 |
220 |

221 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 222 | 223 |

224 |
225 | Built with Sphinx using a theme provided by Read the Docs. 226 | 227 |
228 | 229 |
230 |
231 | 232 |
233 | 234 |
235 | 236 | 237 | 238 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | -------------------------------------------------------------------------------- /toolkit/maintaining_sdk.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | Maintaining the SDK — CLIP OS 5.0.0_beta3 documentation 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 |
50 | 51 | 131 | 132 |
133 | 134 | 135 | 141 | 142 | 143 |
144 | 145 |
146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 |
164 | 165 |
    166 | 167 |
  • Docs »
    • 168 | 169 |
  • Maintaining the SDK
    • 170 | 171 | 172 |
  • 173 | 174 | 175 | View page source 176 | 177 | 178 |
    • 179 | 180 |
181 | 182 | 183 |
184 |
185 |
186 |
187 | 188 |
189 |

Maintaining the SDK

190 |
191 |

Before going further, make sure to update the Portage tree

192 |

You should complete the Portage tree update 193 | steps before executing any command from this page.

194 |
195 |
196 |

Grabbing a new Gentoo stage 3 tarball

197 |

In order to obtain the latest Gentoo stage 3 tarball, use the vendor-gentoo-stage3 198 | helper script, which shall store it in assets/gentoo:

199 | 
$ toolkit/helpers/vendor-gentoo-stage3.sh
200 |
201 |
202 |
203 |
204 |

Updating the SDK recipe

205 |

The SDK recipe then needs to be updated:

206 | 
# product/clipos/sdk/sdk.toml
207 | tag = <portage tree tag>
208 | rootfs = "assets/gentoo/stage3-amd64-hardened+nomultilib-<portage tree tag>.tar.xz"
209 |
210 |
211 |
212 |
213 |

Rebuilding the SDK from scratch

214 |
    215 |
  • Remove all distfiles from the assets/distfiles directory (and only 216 | distfiles, do not delete README.md nor hidden configuration files)
    • 217 |
  • Delete the out/sdk and cache/sdk directories.
    • 218 |
  • Disable all instrumentation features for the SDK build and rebuild the 219 | SDK:
    • 220 |
221 | 
$ cosmk bootstrap sdk
222 |
223 |
224 |

The resulting SDK can then be employed, for instance, to launch a full project 225 | rebuild with the up-to-date Portage tree and the desired instrumentation 226 | features.

227 |
228 |
229 | 230 | 231 |
232 | 233 |
234 |
235 | 236 | 244 | 245 | 246 |
247 | 248 |
249 |

250 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 251 | 252 |

253 |
254 | Built with Sphinx using a theme provided by Read the Docs. 255 | 256 |
257 | 258 |
259 |
260 | 261 |
262 | 263 |
264 | 265 | 266 | 267 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | -------------------------------------------------------------------------------- /toolkit/quick-try.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | Quick try guide — CLIP OS 5.0.0_beta3 documentation 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 |
50 | 51 | 126 | 127 |
128 | 129 | 130 | 136 | 137 | 138 |
139 | 140 |
141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 |
159 | 160 |
    161 | 162 |
  • Docs »
    • 163 | 164 |
  • Quick try guide
    • 165 | 166 | 167 |
  • 168 | 169 | 170 | View page source 171 | 172 | 173 |
    • 174 | 175 |
176 | 177 | 178 |
179 |
180 |
181 |
182 | 183 |
184 |

Quick try guide

185 |
186 |

Important

187 |

Those files are provided AS IS for TESTING PURPOSES ONLY and MUST NOT be 188 | used in a PRODUCTION CONTEXT.

189 |
190 |

To easily try the latest version (nightly build) of CLIP OS 5, you may download 191 | pre-built packages, SDK and pre-installed QEMU images from files.clip-os.org.

192 |

Be aware that those packages and QEMU images are instrumented, which means they 193 | allow full root access without any password on the system.

194 |

To run the CLIP OS system in a virtual machine, you will have to install QEMU. 195 | It is also strongly recommended to have KVM support enabled for your current 196 | user (i.e. your current user is part of the kvm group).

197 | 
# For Debian & Ubuntu
198 | $ sudo apt-get install qemu-system-x86
199 | 
200 | # For Fedora & CentOS
201 | $ sudo dnf install -y qemu-system-x86
202 | 
203 | # For Arch Linux
204 | $ sudo pacman -Syu qemu
205 |
206 |
207 |

Then, you can download and start a CLIP OS QEMU virtual machine with the 208 | following commands:

209 | 
# Pick the latest successful build from https://gitlab.com/CLIPOS/ci/pipelines
210 | $ BUILD="$(curl 'https://gitlab.com/api/v4/projects/14752889/pipelines?scope=finished&status=success' | jq '.[0].id')"
211 | 
212 | # Retrieve the QEMU image
213 | $ wget https://files.clip-os.org/$BUILD/qemu.tar.zst
214 | 
215 | # Extract and enter directory
216 | $ tar xf qemu.tar.zst && cd clipos_*_qemu
217 | 
218 | # Read the README
219 | $ cat README.md
220 | 
221 | # Start CLIP OS with QEMU
222 | $ ./qemu.sh
223 | 
224 | # Start CLIP OS with QEMU without KVM support (not supported, may have issues)
225 | # See: https://discuss.clip-os.org/t/qemu-system-x86-64-overcommit-invalid-option-at-boot/76/12
226 | $ ./qemu-nokvm.sh
227 |
228 |
229 |

You can login as root with no password.

230 |
231 | 232 | 233 |
234 | 235 |
236 |
237 | 238 | 246 | 247 | 248 |
249 | 250 |
251 |

252 | © Copyright 2018, ANSSI. CLIP OS is a trademark of the French Republic. For more details, see the "How to derive this project" section. The contents of this documentation is available under the Open License version 2.0 as published by Etalab (French task force for Open Data) 253 | 254 |

255 |
256 | Built with Sphinx using a theme provided by Read the Docs. 257 | 258 |
259 | 260 |
261 |
262 | 263 |
264 | 265 |
266 | 267 | 268 | 269 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | --------------------------------------------------------------------------------