diff options
52 files changed, 1622 insertions, 1017 deletions
@@ -1,15 +1,20 @@ # agl-docs (master) -Revamping and restructuring Automotive Grade Linux's documentation site under GSoD'20. - --> [The working documentation site.](https://docs-agl.readthedocs.io) - --> [ReadTheDocs project page.](https://readthedocs.org/projects/docs-agl/) - -The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) contains AGL documentation website template and content, rendering is visible at [https://docs-agl.readthedocs.io/en/latest/](https://docs-agl.readthedocs.io/en/latest/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/docs-agl/) and corresponding builds are mentioned [here](https://readthedocs.org/projects/docs-agl/builds/). +Revamping and restructuring Automotive Grade Linux's documentation site under +GSoD'20. + +The [documentation gerrit +repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) +contains AGL documentation website template and content, rendering is visible at +[https://docs.automotivelinux.org/en/master/](hhttps://docs.automotivelinux.org/en/master/). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). ## Download Repository -Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook : +Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) +and clone with commit-msg hook : ```sh $ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" @@ -73,7 +78,8 @@ documentation ## Test Hyperlinks -[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site. +[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to +check all the hyperlinks in the site. For testing hyperlinks as soon as the local site is running, do: @@ -81,8 +87,8 @@ For testing hyperlinks as soon as the local site is running, do: linkchecker http://localhost:8000 ``` -The ```linkchecker``` output will display the broken link and there location -in the site. +The ```linkchecker``` output will display the broken link and there location in +the site. ## Submitting changes diff --git a/docs/2_Architecture_Guides/0_Build_Process.md b/docs/2_Architecture_Guides/0_Build_Process.md new file mode 100644 index 0000000..dba54c3 --- /dev/null +++ b/docs/2_Architecture_Guides/0_Build_Process.md @@ -0,0 +1,5 @@ +--- +title: Overview +--- + + diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/0_Introduction/Introduction.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/0_Introduction/Introduction.md index b77d7e0..b4ccf37 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/0_Introduction/Introduction.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/0_Introduction/Introduction.md @@ -1,33 +1,50 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/README.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Introduction -Modern cars have become a lot more technologically sophisticated and different than those of the past. We are seeing a wider range of new features and functionality, with a lot more complex software. It is fair to say that the cars being introduced to the market today have much more in common with computing devices like cell phones, than their predecessors did. Modern car manufacturers are also integrating support for a broad range of communication technologies for these “connected” cars. With the advent of such vehicles, Linux has become a natural choice for the software platform, with Automotive Grade Linux as a promising example. - -From a security point of view, the remote capabilities of a connected car results in a much larger attack surface. This opens a whole new world of security vulnerabilities that need to be considered during the architectural design. History shows that physical access to a device is sufficient for a hacker to gain root privileges. This makes the car a hostile environment. - -The Security Blueprint documents the security features that are included as part of Automotive Grade Linux (AGL) and identifies areas that need to be addressed from a security perspective as part of AGL. It also gives guidance around existing technologies and solutions. - -Security domains will allow us to create a set of tests verifying the security of Automotive Grade Linux. +Modern cars have become a lot more technologically sophisticated and different +than those of the past. We are seeing a wider range of new features and +functionality, with a lot more complex software. It is fair to say that the cars +being introduced to the market today have much more in common with computing +devices like cell phones, than their predecessors did. Modern car manufacturers +are also integrating support for a broad range of communication technologies for +these “connected” cars. With the advent of such vehicles, Linux has become a +natural choice for the software platform, with Automotive Grade Linux as a +promising example. + +From a security point of view, the remote capabilities of a connected car +results in a much larger attack surface. This opens a whole new world of +security vulnerabilities that need to be considered during the architectural +design. History shows that physical access to a device is sufficient for a +hacker to gain root privileges. This makes the car a hostile environment. + +The Security Blueprint documents the security features that are included as part +of Automotive Grade Linux (AGL) and identifies areas that need to be addressed +from a security perspective as part of AGL. It also gives guidance around +existing technologies and solutions. + +Security domains will allow us to create a set of tests verifying the security +of Automotive Grade Linux. This document is firstly based on an existing AGL security-blueprint. -**For security to be effective, the concepts must be simple. And by default, anything that is not allowed is forbidden.** +**For security to be effective, the concepts must be simple. And by default, +anything that is not allowed is forbidden.** -We will cover topics starting from the lowest level (_Hardware_) up to the highest levels (_Connectivity_ and _Application_). We will move quickly on _Hardware_ and _Connectivity_ because this is not supported at our level. Solutions of connectivity problems concern updates and secured settings while hardware securing is related to the manufacturers. +We will cover topics starting from the lowest level (_Hardware_) up to the +highest levels (_Connectivity_ and _Application_). We will move quickly on +_Hardware_ and _Connectivity_ because this is not supported at our level. +Solutions of connectivity problems concern updates and secured settings while +hardware securing is related to the manufacturers. The document is filled with tags to easily identify important points: <!-- section-config --> -- The _config_ tag quickly identifies the configurations and the recommendations to take. +- The _config_ tag quickly identifies the configurations and the recommendations + to take. <!-- end-section-config --><!-- section-note --> @@ -47,29 +64,62 @@ Adversaries and attackers within the Automotive space. - Enthusiast Attackers -Enthusiast attackers have physical access to the Engine Control Units (ECUs) at the circuit board level. They can solder ‘mod chips’ onto the board and have access to probing tools. They also have information on ECUs that have been previously compromised and have access to softwares and instructions developed by other members of car modification forums. The goal of the enthusiast hacker could be, but is not limited to, adding extra horse power to the car or hacking it just for fun. +Enthusiast attackers have physical access to the Engine Control Units (ECUs) at +the circuit board level. They can solder ‘mod chips’ onto the board and have +access to probing tools. They also have information on ECUs that have been +previously compromised and have access to softwares and instructions developed +by other members of car modification forums. The goal of the enthusiast hacker +could be, but is not limited to, adding extra horse power to the car or hacking +it just for fun. - Corrupt Automotive Dealers -Corrupt automotive dealers are attackers that have access to the same capabilities as enthusiasts, but also have access to the car manufacturer’s (OEM) dealer network. They may also have access to standard debugging tools provided by the car manufacturer. Their goal may be to support local car theft gangs or organized criminals. +Corrupt automotive dealers are attackers that have access to the same +capabilities as enthusiasts, but also have access to the car manufacturer’s +(OEM) dealer network. They may also have access to standard debugging tools +provided by the car manufacturer. Their goal may be to support local car theft +gangs or organized criminals. - Organized Criminals -Organized criminals have access to all of the above tools but may also have some level of control over the internal network at many dealerships. They may have hacked and gained temporary control of the Over-The-Air (OTA) servers or the In-Vehicle Infotainment (IVI) systems. This is very much like the role of organized criminals in other industries such as paid media today. Their goal is to extort money from OEMs and/or governments by threatening to disable multiple vehicles. +Organized criminals have access to all of the above tools but may also have some +level of control over the internal network at many dealerships. They may have +hacked and gained temporary control of the Over-The-Air (OTA) servers or the +In-Vehicle Infotainment (IVI) systems. This is very much like the role of +organized criminals in other industries such as paid media today. Their goal is +to extort money from OEMs and/or governments by threatening to disable multiple +vehicles. - Malware Developers -Malware developers have developed malicious software to attack and compromise a large number of vehicles. The malicious software is usually designed to spread from one vehicle to another. Usually, the goal is to take control of multiple machines and then sell access to them for malicious purposes like denial-of-service (DoS) attacks or theft of private information and data. +Malware developers have developed malicious software to attack and compromise a +large number of vehicles. The malicious software is usually designed to spread +from one vehicle to another. Usually, the goal is to take control of multiple +machines and then sell access to them for malicious purposes like +denial-of-service (DoS) attacks or theft of private information and data. - Security Researchers -Security researchers are ‘self-publicized’ security consultants trying to make a name for themselves. They have access to standard tools for software security analysis. They also have physical access to the vehicle and standard hardware debugging tools (Logic Analyzers, Oscilloscopes, etc). Their goal is to publicize attacks for personal gain or just to gain personal understanding with a sense of helping make things more secure. +Security researchers are ‘self-publicized’ security consultants trying to make a +name for themselves. They have access to standard tools for software security +analysis. They also have physical access to the vehicle and standard hardware +debugging tools (Logic Analyzers, Oscilloscopes, etc). Their goal is to +publicize attacks for personal gain or just to gain personal understanding with +a sense of helping make things more secure. ## Attack Goals -In today’s connected vehicle, more and more functionality is moving to software control, meaning that the threat of attack becomes greater and greater. We see car features like navigation and summoning, car access/engine start, and motor/ECU upgrades all controlled through software and connections to the cloud. The risk of attack is high because there are high value targets in play. +In today’s connected vehicle, more and more functionality is moving to software +control, meaning that the threat of attack becomes greater and greater. We see +car features like navigation and summoning, car access/engine start, and +motor/ECU upgrades all controlled through software and connections to the cloud. +The risk of attack is high because there are high value targets in play. -Here, we outline some of the major threats categories along with some sample attackers, example attacks, and a relative importance. These threat categories are intended to be general examples. There can be many nuances to threat types. Additionally, there can be many sub-attacks that eventually lead to these higher level attack goals. +Here, we outline some of the major threats categories along with some sample +attackers, example attacks, and a relative importance. These threat categories +are intended to be general examples. There can be many nuances to threat types. +Additionally, there can be many sub-attacks that eventually lead to these higher +level attack goals. | Threat Category | Sample Attacker | Example Attacks | Relative Importance | |-------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| @@ -78,13 +128,39 @@ Here, we outline some of the major threats categories along with some sample att | Vehicle hacking | Vehicle owner, competitor | Get content without paying, modify DRM licenses, unlock of after-market features, theft of IP | Loss of sales for content and features (Profit Now), lawsuits from content owners (Profit Later), loss of competitive advantage (Profit Later) | | Sensitive asset theft | Organized criminals, blackmailers | Steal credit card numbers, health information, camera data, steal bandwidth | Bad press (Brand Integrity), lawsuits from vehicle owners (Profit Later) | -The Automotive Grade Linux (AGL) initiative builds upon open-source software including Linux and Tizen to offer a flexible application framework. However, the security provisions of the app framework, Cynara, and the security manager only go so far in keeping the biggest threats at bay. As experience has shown, providing a constrained app (like that in the Android Open Source Platform) and store development flow, signature verification, DAC sandboxing, and MAC (SMACK) controls over the platform can have a certain amount of success with the security of the system. However, the openness of the system invites many researchers, hobbyists and hackers and financially motivated attackers to compromise the system for their own gains. - -As AGL arrives on modern automobiles, this is inevitably inviting many capable actors to modify, attack, and compromise these well thought-out systems and their applications. With concerns like safety and security, the auto industry cannot afford to go the way of consumer devices like phones and tablets where security problems are encountered on a frequent basis. It is imperative to use a layered approach and defense-in-depth to protect the system from inevitable attack. +The Automotive Grade Linux (AGL) initiative builds upon open-source software +including Linux and Tizen to offer a flexible application framework. However, +the security provisions of the app framework, Cynara, and the security manager +only go so far in keeping the biggest threats at bay. As experience has shown, +providing a constrained app (like that in the Android Open Source Platform) and +store development flow, signature verification, DAC sandboxing, and MAC (SMACK) +controls over the platform can have a certain amount of success with the +security of the system. However, the openness of the system invites many +researchers, hobbyists and hackers and financially motivated attackers to +compromise the system for their own gains. + +As AGL arrives on modern automobiles, this is inevitably inviting many capable +actors to modify, attack, and compromise these well thought-out systems and +their applications. With concerns like safety and security, the auto industry +cannot afford to go the way of consumer devices like phones and tablets where +security problems are encountered on a frequent basis. It is imperative to use a +layered approach and defense-in-depth to protect the system from inevitable +attack. ## Assets and Security Categorization -This section outlines some of the assets that are likely to be found in the vehicle and their relative sensitivity from an attack point of view. Additionally, the final column on the right lists some of the recommended protection types that can be applied to these types of assets (Note that the empty cells refer to the cells above them). A good protection approach will give priority to the most sensitive assets, using a defense-in-depth approach to cover these assets. Less sensitive assets are treated at a lower priority, typically protected with fewer protection techniques. A more fine-grained prioritization of the the assets in a concrete vehicle network can be achieved with detailed threat analysis which considers the topology of the vehicle network and access-controls that are in-place. e.g. the EVITA framework for attack trees. +This section outlines some of the assets that are likely to be found in the +vehicle and their relative sensitivity from an attack point of view. +Additionally, the final column on the right lists some of the recommended +protection types that can be applied to these types of assets (Note that the +empty cells refer to the cells above them). A good protection approach will give +priority to the most sensitive assets, using a defense-in-depth approach to +cover these assets. Less sensitive assets are treated at a lower priority, +typically protected with fewer protection techniques. A more fine-grained +prioritization of the the assets in a concrete vehicle network can be achieved +with detailed threat analysis which considers the topology of the vehicle +network and access-controls that are in-place. e.g. the EVITA framework for +attack trees. | Asset Category | Examples | Sensitivity | Recommended Protection Types | |-------------------|--------------------------------------------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -102,13 +178,18 @@ This section outlines some of the assets that are likely to be found in the vehi ## Hardening term -The term Hardening refers to the tools, techniques and processes required in order to reduce the attack surface on an embedded system, such as an embedded control unit (**ECU**) or other managed devices. The target for all hardening activities is to prevent the execution of invalid binaries on the device, and to prevent copying of security related data from the device. +The term Hardening refers to the tools, techniques and processes required in +order to reduce the attack surface on an embedded system, such as an embedded +control unit (**ECU**) or other managed devices. The target for all hardening +activities is to prevent the execution of invalid binaries on the device, and to +prevent copying of security related data from the device. <!-- pagebreak --> ## AGL security overview -AGL roots are based on security concepts. Those concepts are implemented by the security framework as shown in this picture: +AGL roots are based on security concepts. Those concepts are implemented by the +security framework as shown in this picture:  @@ -130,38 +211,65 @@ The following table lists the strongest terms utilized within all this document. # References - [security-blueprint](http://docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html). - - _http:// docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html_ -- **[2017]** - [kernel security](https://www.kernel.org/doc/Documentation/security/). + - _http:// + docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html_ +- **[2017]** - [kernel + security](https://www.kernel.org/doc/Documentation/security/). - _https:// www.kernel.org/doc/Documentation/security/_ -- **[2017]** - [Systemd integration and user management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf). +- **[2017]** - [Systemd integration and user + management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf). - _http:// iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf_ -- **[2017]** - [AGL - Application Framework Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf). +- **[2017]** - [AGL - Application Framework + Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf). - _http:// iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf_ -- **[2017]** - [Improving Vehicle Cybersecurity](https://access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf). - - _https:// access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf_ -- **[2016]** - [AGL framework overview](http://docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html). - - _http:// docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html_ -- **[2016]** - [SecureBoot-SecureSoftwareUpdates](http://iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf). - - _http:// iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf_ -- **[2016]** - [Linux Automotive Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf). - - _http:// iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf_ -- **[2016]** - [Automotive Security Best Practices](https://www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf). - - _https:// www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf_ -- **[2016]** - [Gattacking Bluetooth Smart Devices](http://gattack.io/whitepaper.pdf). +- **[2017]** - [Improving Vehicle + Cybersecurity](https://access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf). + - _https:// + access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf_ +- **[2016]** - [AGL framework + overview](http://docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html). + - _http:// + docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html_ +- **[2016]** - + [SecureBoot-SecureSoftwareUpdates](http://iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf). + - _http:// + iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf_ +- **[2016]** - [Linux Automotive + Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf). + - _http:// + iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf_ +- **[2016]** - [Automotive Security Best + Practices](https://www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf). + - _https:// + www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf_ +- **[2016]** - [Gattacking Bluetooth Smart + Devices](http://gattack.io/whitepaper.pdf). - _http:// gattack.io/whitepaper.pdf_ -- **[2015]** - [Comprehensive Experimental Analysis of Automotive Attack Surfaces](http://www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf). - - _http:// www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf_ -- **[2015]** - [Security in Automotive Bus Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf). - - _http:// citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf_ -- **[2014]** - [IOActive Remote Attack Surface](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf). +- **[2015]** - [Comprehensive Experimental Analysis of Automotive Attack + Surfaces](http://www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf). + - _http:// + www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf_ +- **[2015]** - [Security in Automotive Bus + Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf). + - _http:// + citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf_ +- **[2014]** - [IOActive Remote Attack + Surface](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf). - _https:// www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf_ -- **[2011]** - [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf). - - _https:// media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf_ -- **[2011]** - [Comprehensive Experimental Analyses of Automotive Attack Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf). +- **[2011]** - [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data + communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf). + - _https:// + media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf_ +- **[2011]** - [Comprehensive Experimental Analyses of Automotive Attack + Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf). - _http:// www.autosec.org/pubs/cars-usenixsec2011.pdf_ -- **[2010]** - [Relay Attacks on Passive Keyless Entry and Start Systems in Modern Cars](https://eprint.iacr.org/2010/332.pdf). +- **[2010]** - [Relay Attacks on Passive Keyless Entry and Start Systems in + Modern Cars](https://eprint.iacr.org/2010/332.pdf). - _https:// eprint.iacr.org/2010/332.pdf_ -- **[2010]** - [Wifi attacks wep wpa](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf). +- **[2010]** - [Wifi attacks wep + wpa](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf). - _https:// matthieu.io/dl/wifi-attacks-wep-wpa.pdf_ -- **[2008]** - [SMACK](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf). - - _http:// schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf_ +- **[2008]** - + [SMACK](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf). + - _http:// + schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf_ diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.0_Abstract.md index 5cad4d9..bf4e936 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.0_Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Annexes -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/annexes/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Annexes The first part resumed all the configurations you must implement without any diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.1_Config_Notes.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.1_Config_Notes.md index 3b403ea..293b6f3 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.1_Config_Notes.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.1_Config_Notes.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Config notes -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/annexes/ConfigNotes.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Config notes <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.2_To_Do_Notes.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.2_To_Do_Notes.md index 23482a9..2f68994 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.2_To_Do_Notes.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/10_Annexes/1.2.10.2_To_Do_Notes.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Todo notes -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/annexes/todoNotes.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Todo notes <!-- section-todo --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/1_Hardware/Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/1_Hardware/Abstract.md index d9aeefb..7fe806f 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/1_Hardware/Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/1_Hardware/Abstract.md @@ -1,18 +1,14 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-1/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 1 - Hardware ## Abstract -The Automotive Grade Linux platform is a Linux distribution with **AGL** compliant applications and services. -The platform includes the following hardware: +The Automotive Grade Linux platform is a Linux distribution with **AGL** +compliant applications and services. The platform includes the following +hardware: - SoC (System-on-Chip). - Memory (RAM, ROM, storage, etc.). @@ -21,9 +17,9 @@ The platform includes the following hardware: You will find in this first part everything that concerns the hardware security. The goal is to protect system against all attacks that are trying to gain additional privileges by recovering and/or changing cryptographic keys in order -to alter the integrity of the boot. We should also prevent hardware modifications -in order to achieve this goal. We will expose below some examples of possible -configurations. +to alter the integrity of the boot. We should also prevent hardware +modifications in order to achieve this goal. We will expose below some examples +of possible configurations. -------------------------------------------------------------------------------- @@ -41,9 +37,9 @@ _SHE_ | **S**ecure **H**ardware **E**xtensions ## Integrity -The board must store hardcoded cryptographic keys in order to verify among others -the _integrity_ of the _bootloader_. Manufacturers can use **HSM** and **SHE** to -enhance the security of their board. +The board must store hardcoded cryptographic keys in order to verify among +others the _integrity_ of the _bootloader_. Manufacturers can use **HSM** and +**SHE** to enhance the security of their board. <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.0_Abstract.md index 9095b62..73a0cab 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.0_Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-2/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 2 - Secure boot ## Abstract @@ -20,9 +15,10 @@ Boot-Abstract-1 | More generic and add examples (The chain of trust). <!-- end-section-todo --> Secure boot refers to preventing malicious software applications and -“unauthorized” operating systems from loading during the system start-up process. -The goal is to protect users from rootkits and other low-level malware attacks. -Modern bootloaders come with features that can be used to enable secure boot in the system. +“unauthorized” operating systems from loading during the system start-up +process. The goal is to protect users from rootkits and other low-level malware +attacks. Modern bootloaders come with features that can be used to enable secure +boot in the system. **Boot Hardening**: Steps/requirements to configure the boot sequence, in order to restrict the device from executing anything other than the approved software @@ -51,14 +47,14 @@ Boot-Abstract-1 | Review the definition of the "boot loader". <!-- end-section-todo --> -**Boot loader**: The boot loader consists of the Primary boot loader residing -in **OTP** memory, sboot, U-Boot and Secure loader residing in external flash -(NAND or SPI/NOR flash memory). The CPU on power on or reset executes the -primary boot loader. The **OTP** primary boot loader makes the necessary initial -system configuration and then loads the secondary boot loader sboot from -external flash memory to ram memory. The sboot then loads the U-Boot along with -the Secure loader. U-Boot then verifies the Kernel/system image integrity, then -loads the Kernel/system image before passing control to it. +**Boot loader**: The boot loader consists of the Primary boot loader residing in +**OTP** memory, sboot, U-Boot and Secure loader residing in external flash (NAND +or SPI/NOR flash memory). The CPU on power on or reset executes the primary boot +loader. The **OTP** primary boot loader makes the necessary initial system +configuration and then loads the secondary boot loader sboot from external flash +memory to ram memory. The sboot then loads the U-Boot along with the Secure +loader. U-Boot then verifies the Kernel/system image integrity, then loads the +Kernel/system image before passing control to it. -------------------------------------------------------------------------------- diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.1_Image.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.1_Image.md index 998c514..ad9b577 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.1_Image.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.1_Image.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Image -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-2/1-Image.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Image ## Image selection diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.2_Communication-modes.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.2_Communication-modes.md index 3381324..fc3ea47 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.2_Communication-modes.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.2_Communication-modes.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Communication modes -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-2/2-Communication-modes.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Communication modes ## Disable USB, Serial and DOCSIS Support @@ -56,8 +51,8 @@ Boot-Communication-USB-5 | `CONFIG_USB_HOST_ETHER` | _Not defined_ ## Disable all unused Network Interfaces -Only used network interfaces should be enabled. -Where possible, services should also be limited to those necessary. +Only used network interfaces should be enabled. Where possible, services should +also be limited to those necessary. <!-- section-config --> @@ -85,7 +80,8 @@ Boot-Communication-1 | `Services`, `ports` and `devices` | Restrict the `service In U-Boot following flash memory commands shall be disabled: -**NAND**: Support for nand flash access available through `do_nand` has to be disabled. +**NAND**: Support for nand flash access available through `do_nand` has to be +disabled. <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.3_Consoles.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.3_Consoles.md index e578acd..0afb6f6 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.3_Consoles.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/2_Secure_Boot/1.2.2.3_Consoles.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Consoles -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-2/3-Consoles.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Consoles ## Disable serial console diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/3_Hypervisor/Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/3_Hypervisor/Abstract.md index 61d62c8..7cc3017 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/3_Hypervisor/Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/3_Hypervisor/Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-3/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 3 - Hypervisor Definition: "A hypervisor or virtual machine monitor (VMM) is computer software, @@ -24,4 +19,5 @@ Hypervisor-Abstract-1 | Complete Hypervisor part ([jailhouse](https://github.com ## Native or Bare-metal hypervisors -These hypervisors run directly on the host's hardware to control the hardware and to manage guest operating systems. Those are the ones we're interested in. +These hypervisors run directly on the host's hardware to control the hardware +and to manage guest operating systems. Those are the ones we're interested in. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.0_Abstract.md index cff791b..4f23b13 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.0_Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 4 - Kernel ## Abstract @@ -32,38 +27,39 @@ configurations that shall be required for deployment. The choice of kernel version for the AGL system is essential to its security. Depending on the type of board and eventual production system, different kernel -versions are used. For example, one of the systems under study uses the -Linux kernel version 3.10, while another uses the Linux kernel version 4.4. -For the Linux kernel version 3.10.31, there are 25 known vulnerabilities. -These vulnerabilities would allow an attacker to gain privileges, -bypass access restrictions, allow memory to be corrupted, or cause denial of service. -In contrast, the Linux kernel version of 4.4 has many fewer known vulnerabilities. -For this reason, we would in general recommend the later kernel version as a basis -for the platform. +versions are used. For example, one of the systems under study uses the Linux +kernel version 3.10, while another uses the Linux kernel version 4.4. For the +Linux kernel version 3.10.31, there are 25 known vulnerabilities. These +vulnerabilities would allow an attacker to gain privileges, bypass access +restrictions, allow memory to be corrupted, or cause denial of service. In +contrast, the Linux kernel version of 4.4 has many fewer known vulnerabilities. +For this reason, we would in general recommend the later kernel version as a +basis for the platform. -Note that, although there are fewer known vulnerabilities in the most recent kernel -versions there may be many unknown vulnerabilities underlying. -A rule of thumb is to update the kernel as much as possible to avoid the problems -you do know, but you should not be complacent in the trust that you place in it. -A defense-in-depth approach would then apply. +Note that, although there are fewer known vulnerabilities in the most recent +kernel versions there may be many unknown vulnerabilities underlying. A rule of +thumb is to update the kernel as much as possible to avoid the problems you do +know, but you should not be complacent in the trust that you place in it. A +defense-in-depth approach would then apply. If there are constraints and dependencies in upgrading to a newer kernel version (e.g. device drivers, board support providers) and you are forced to an older -Linux kernel version, there need to be additional provisions made to reduce -the risk of kernel exploits, which can include memory monitoring, watch-dog services, -and system call hooking. In this case, further defense-in-depth techniques -may be required to mitigate the risk of attacks to known vulnerabilities, -which can also include runtime integrity verification of components -that are vulnerable to tampering. +Linux kernel version, there need to be additional provisions made to reduce the +risk of kernel exploits, which can include memory monitoring, watch-dog +services, and system call hooking. In this case, further defense-in-depth +techniques may be required to mitigate the risk of attacks to known +vulnerabilities, which can also include runtime integrity verification of +components that are vulnerable to tampering. ## Kernel Build Configuration The kernel build configuration is extremely important for determining the level -of access to services and to reduce the breadth of the attack surface. -Linux contains a great and flexible number of capabilities and this is only controlled +of access to services and to reduce the breadth of the attack surface. Linux +contains a great and flexible number of capabilities and this is only controlled through the build configuration. For example, the `CONFIG_MODULES` parameter -allows kernel modules to be loaded at runtime extending the capabilities of the kernel. -This capability needs to be either inhibited or controlled at runtime through -other configuration parameters. For example, `CONFIG_MODULE_SIG_FORCE=y` ensures -that only signed modules are loaded. There is a very large number of kernel -configuration parameters, and these are discussed in detail in this section. +allows kernel modules to be loaded at runtime extending the capabilities of the +kernel. This capability needs to be either inhibited or controlled at runtime +through other configuration parameters. For example, `CONFIG_MODULE_SIG_FORCE=y` +ensures that only signed modules are loaded. There is a very large number of +kernel configuration parameters, and these are discussed in detail in this +section. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.1_General.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.1_General.md index 3d7fae0..dc685bf 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.1_General.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.1_General.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: General -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/1-General.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # General configuration ## Mandatory Access Control @@ -28,15 +23,19 @@ Kernel-General-MAC-8 | CONFIG_TMPFS_XATTR | y <!-- end-section-config --> -Please also refer to the [**Mandatory Access Control** documentation in Platform](../part-5/1-MAC.html) part. -You can also find useful documentation and links on wikipedia about [**MAC**](https://en.wikipedia.org/wiki/Mandatory_access_control) -and about [**SMACK**](https://en.wikipedia.org/wiki/Simplified_Mandatory_Access_Control_Kernel). +Please also refer to the [**Mandatory Access Control** documentation in +Platform](../part-5/1-MAC.html) part. You can also find useful documentation and +links on wikipedia about +[**MAC**](https://en.wikipedia.org/wiki/Mandatory_access_control) and about +[**SMACK**](https://en.wikipedia.org/wiki/Simplified_Mandatory_Access_Control_Kernel). -------------------------------------------------------------------------------- ## Disable kexec -**Kexec** is a system call that enables you to load and boot into another kernel from the currently running kernel. This feature is not required in a production environment. +**Kexec** is a system call that enables you to load and boot into another kernel +from the currently running kernel. This feature is not required in a production +environment. <!-- section-config --> @@ -48,7 +47,8 @@ Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` <!-- section-note --> -**kexec** can load arbitrary kernels but signing of new kernel can be enforced like it is can be enforced for new modules. +**kexec** can load arbitrary kernels but signing of new kernel can be enforced +like it is can be enforced for new modules. <!-- end-section-note --> @@ -56,7 +56,9 @@ Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` ## Disable kernel IP auto-configuration -It is preferable to have an IP configuration performed using a user-space tool as these tend to have more validation. We do not want the network interface coming up until the system has come up properly. +It is preferable to have an IP configuration performed using a user-space tool +as these tend to have more validation. We do not want the network interface +coming up until the system has come up properly. <!-- section-config --> @@ -70,7 +72,8 @@ Kernel-General-IPAutoConf-1 | `CONFIG_IP_PNP` | `n` ## Disable Sysctl syscall support -Enabling this will result in code being included that is hard to maintain and not well tested. +Enabling this will result in code being included that is hard to maintain and +not well tested. <!-- section-config --> @@ -84,7 +87,11 @@ Kernel-General-SysCtl_SysCall-1 | `CONFIG_SYSCTL_SYSCALL` | `n` ## Disable Legacy Linux Support -There are some Kernel Configs which are present only to support legacy binaries. See also "Consoles" part in order to disabling support for legacy binary formats. The `uselib` system call, in particular, has no valid use in any `libc6` or `uclibc` system in recent times. This configuration is supported in **Linux 3.15 and greater** and thus should only be disabled for such versions. +There are some Kernel Configs which are present only to support legacy binaries. +See also "Consoles" part in order to disabling support for legacy binary +formats. The `uselib` system call, in particular, has no valid use in any +`libc6` or `uclibc` system in recent times. This configuration is supported in +**Linux 3.15 and greater** and thus should only be disabled for such versions. <!-- section-config --> @@ -98,7 +105,11 @@ Kernel-General-LegacyLinux-1 | `CONFIG_USELIB` | `n` ## Disable firmware auto-loading user mode helper -The firmware auto loading helper, which is a utility executed by the kernel on `hotplug` events requiring firmware, can to be set `setuid`. As a result of this, the helper utility is an attractive target for attackers with control of physical ports on the device. Disabling this configuration that is supported in **Linux 3.9 and greater**. +The firmware auto loading helper, which is a utility executed by the kernel on +`hotplug` events requiring firmware, can to be set `setuid`. As a result of +this, the helper utility is an attractive target for attackers with control of +physical ports on the device. Disabling this configuration that is supported in +**Linux 3.9 and greater**. <!-- section-config --> @@ -110,7 +121,8 @@ Kernel-General-FirmHelper-1 | `CONFIG_FW_LOADER_USER_HELPER` | `n` <!-- section-note --> -It doesn't strictly need to be `setuid`, there is an option of shipping firmware builtin into kernel without initrd/filesystem. +It doesn't strictly need to be `setuid`, there is an option of shipping firmware +builtin into kernel without initrd/filesystem. <!-- end-section-note --> @@ -118,9 +130,12 @@ It doesn't strictly need to be `setuid`, there is an option of shipping firmware ## Enable Kernel Panic on OOPS -When fuzzing the kernel or attempting kernel exploits attackers are likely to trigger kernel OOPSes. Setting the behavior on OOPS to PANIC can impede their progress. +When fuzzing the kernel or attempting kernel exploits attackers are likely to +trigger kernel OOPSes. Setting the behavior on OOPS to PANIC can impede their +progress. -This configuration is supported in **Linux 3.5 and greater** and thus should only be enabled for such versions. +This configuration is supported in **Linux 3.5 and greater** and thus should +only be enabled for such versions. <!-- section-config --> @@ -136,11 +151,14 @@ Kernel-General-PanicOnOOPS-1 | `CONFIG_PANIC_ON_OOPS` | `y` ## Disable socket monitoring interface -These monitors can be used to inspect shared file descriptors on Unix Domain sockets or traffic on 'localhost' which is otherwise assumed to be confidential. +These monitors can be used to inspect shared file descriptors on Unix Domain +sockets or traffic on 'localhost' which is otherwise assumed to be confidential. -The `CONFIG_PACKET_DIAG` configuration is supported in **Linux 3.7 and greater** and thus should only be disabled for such versions. +The `CONFIG_PACKET_DIAG` configuration is supported in **Linux 3.7 and greater** +and thus should only be disabled for such versions. -The `CONFIG_UNIX_DIAG` configuration is supported in **Linux 3.3 and greater** and thus should only be disabled for such versions. +The `CONFIG_UNIX_DIAG` configuration is supported in **Linux 3.3 and greater** +and thus should only be disabled for such versions. <!-- section-config --> @@ -157,7 +175,8 @@ Kernel-General-SocketMon-2 | `CONFIG_UNIX_DIAG` | `n` The BPF JIT can be used to create kernel-payloads from firewall table rules. -This configuration for is supported in **Linux 3.16 and greater** and thus should only be disabled for such versions. +This configuration for is supported in **Linux 3.16 and greater** and thus +should only be disabled for such versions. <!-- section-config --> @@ -171,15 +190,17 @@ Kernel-General-BPF_JIT-1 | `CONFIG_BPF_JIT` | `n` ## Enable Enforced Module Signing -The kernel should never allow an unprivileged user the ability to load specific kernel modules, -since that would provide a facility to unexpectedly extend the available attack surface. +The kernel should never allow an unprivileged user the ability to load specific +kernel modules, since that would provide a facility to unexpectedly extend the +available attack surface. To protect against even privileged users, systems may need to either disable -module loading entirely, or provide signed modules -(e.g. `CONFIG_MODULE_SIG_FORCE`, or dm-crypt with LoadPin), to keep from having -root load arbitrary kernel code via the module loader interface. +module loading entirely, or provide signed modules (e.g. +`CONFIG_MODULE_SIG_FORCE`, or dm-crypt with LoadPin), to keep from having root +load arbitrary kernel code via the module loader interface. -This configuration is supported in **Linux 3.7 and greater** and thus should only be enabled for such versions. +This configuration is supported in **Linux 3.7 and greater** and thus should +only be enabled for such versions. <!-- section-config --> @@ -189,7 +210,8 @@ Kernel-General-ModuleSigning-1 | `CONFIG_MODULE_SIG_FORCE` | `y` <!-- end-section-config --> -It is also possible to block the loading of modules after startup with "kernel.modules_disabled". +It is also possible to block the loading of modules after startup with +"kernel.modules_disabled". <!-- section-config --> @@ -205,7 +227,9 @@ Kernel-General-ModuleSigning-2 | `kernel.modules_disabled` | `1` ## Disable all USB, PCMCIA (and other `hotplug` bus) drivers that aren't needed -To reduce the attack surface, the driver enumeration, probe, and operation happen in the kernel. The driver data is parsed by the kernel, so any logic bugs in these drivers can become kernel exploits. +To reduce the attack surface, the driver enumeration, probe, and operation +happen in the kernel. The driver data is parsed by the kernel, so any logic bugs +in these drivers can become kernel exploits. <!-- section-config --> @@ -243,7 +267,10 @@ Produce a position independent executable on targets which supports it. ## Prevent Overwrite Attacks -`-z,relro` linking option helps during program load, several ELF memory sections need to be written by the linker, but can be turned read-only before turning over control to the program. This prevents some Global Offset Table GOT overwrite attacks, or in the dtors section of the ELF binary. +`-z,relro` linking option helps during program load, several ELF memory sections +need to be written by the linker, but can be turned read-only before turning +over control to the program. This prevents some Global Offset Table GOT +overwrite attacks, or in the dtors section of the ELF binary. <!-- section-config --> @@ -254,7 +281,11 @@ Kernel-General-OverwriteAttacks-2 | `-z,now` | _Enable_ <!-- end-section-config --> -During program load, all dynamic symbols are resolved, allowing for the complete GOT to be marked read-only (due to `-z relro` above). This prevents GOT overwrite attacks. For very large application, this can incur some performance loss during initial load while symbols are resolved, but this shouldn't be an issue for daemons. +During program load, all dynamic symbols are resolved, allowing for the complete +GOT to be marked read-only (due to `-z relro` above). This prevents GOT +overwrite attacks. For very large application, this can incur some performance +loss during initial load while symbols are resolved, but this shouldn't be an +issue for daemons. -------------------------------------------------------------------------------- @@ -270,7 +301,8 @@ Kernel-General-LibraryLinking-1 | Keep this part? <!-- end-section-todo --> -It is recommended that dynamic linking should generally not be allowed. This will avoid the user from replacing a library with malicious library. +It is recommended that dynamic linking should generally not be allowed. This +will avoid the user from replacing a library with malicious library. <!-- section-config --> @@ -282,6 +314,9 @@ Kernel-General-LibraryLinking-1 | Dynamic linking | Should generally not be allo <!-- section-note --> -Linking everything statically doesn't change anything wrt security as binaries will live under same user:group as libraries and setuid executables ignore `LD_PRELOAD/LD_LIBRARY_PATH`. It also increases RSS footprint and creates problems with upgrading. +Linking everything statically doesn't change anything wrt security as binaries +will live under same user:group as libraries and setuid executables ignore +`LD_PRELOAD/LD_LIBRARY_PATH`. It also increases RSS footprint and creates +problems with upgrading. <!-- end-section-note --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.2_Memory.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.2_Memory.md index 9c3fdb1..57cd9a3 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.2_Memory.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.2_Memory.md @@ -1,19 +1,18 @@ --- -edit_link: '' title: Memory -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/2-Memory.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Memory ## Restrict access to kernel memory -The /dev/kmem file in Linux systems is directly mapped to kernel virtual memory. This can be disastrous if an attacker gains root access, as the attacker would have direct access to kernel virtual memory. +The /dev/kmem file in Linux systems is directly mapped to kernel virtual memory. +This can be disastrous if an attacker gains root access, as the attacker would +have direct access to kernel virtual memory. -To disable the /dev/kmem file, which is very infrequently used by applications, the following kernel option should be set in the compile-time kernel configuration: +To disable the /dev/kmem file, which is very infrequently used by applications, +the following kernel option should be set in the compile-time kernel +configuration: <!-- section-config --> @@ -23,13 +22,15 @@ Kernel-Memory-RestrictAccess-1 | `CONFIG_DEVKMEM` | `n` <!-- end-section-config --> -In case applications in userspace need /dev/kmem support, it should be available only for authenticated applications. +In case applications in userspace need /dev/kmem support, it should be available +only for authenticated applications. -------------------------------------------------------------------------------- ## Disable access to a kernel core dump -This kernel configuration disables access to a kernel core dump from user space. If enabled, it gives attackers a useful view into kernel memory. +This kernel configuration disables access to a kernel core dump from user space. +If enabled, it gives attackers a useful view into kernel memory. <!-- section-config --> @@ -43,7 +44,9 @@ Kernel-Memory-CoreDump-1 | `CONFIG_PROC_KCORE` | `n` ## Disable swap -If not disabled, attackers can enable swap at runtime, add pressure to the memory subsystem and then scour the pages written to swap for useful information. +If not disabled, attackers can enable swap at runtime, add pressure to the +memory subsystem and then scour the pages written to swap for useful +information. <!-- section-config --> @@ -68,7 +71,10 @@ Kernel-Memory-Swap-1 | `CONFIG_SWAP` | `n` ## Disable "Load All Symbols" -There is a /proc/kallsyms file which exposes the kernel memory space address of many kernel symbols (functions, variables, etc...). This information is useful to attackers in identifying kernel versions/configurations and in preparing payloads for the exploits of kernel space. +There is a /proc/kallsyms file which exposes the kernel memory space address of +many kernel symbols (functions, variables, etc...). This information is useful +to attackers in identifying kernel versions/configurations and in preparing +payloads for the exploits of kernel space. Both `KALLSYMS_ALL` and `KALLSYMS` shall be disabled; @@ -85,11 +91,14 @@ Kernel-Memory-LoadAllSymbols-2 | `CONFIG_KALLSYMS_ALL` | `n` ## Stack protection -To prevent stack-smashing, similar to the stack protector used for ELF programs in user-space, the kernel can protect its internal stacks as well. +To prevent stack-smashing, similar to the stack protector used for ELF programs +in user-space, the kernel can protect its internal stacks as well. -This configuration is supported in **Linux 3.11 and greater** and thus should only be enabled for such versions. +This configuration is supported in **Linux 3.11 and greater** and thus should +only be enabled for such versions. -This configuration also requires building the kernel with the **gcc compiler 4.2 or greater**. +This configuration also requires building the kernel with the **gcc compiler 4.2 +or greater**. <!-- section-config --> @@ -105,9 +114,15 @@ Other defenses include things like shadow stacks. ## Disable access to /dev/mem -The /dev/mem file in Linux systems is directly mapped to physical memory. This can be disastrous if an attacker gains root access, as the attacker would have direct access to physical memory through this convenient device file. It may not always be possible to disable such file, as some applications might need such support. In that case, then this device file should be available only for authenticated applications. +The /dev/mem file in Linux systems is directly mapped to physical memory. This +can be disastrous if an attacker gains root access, as the attacker would have +direct access to physical memory through this convenient device file. It may not +always be possible to disable such file, as some applications might need such +support. In that case, then this device file should be available only for +authenticated applications. -This configuration is supported in **Linux 4.0 and greater** and thus should only be disabled for such versions. +This configuration is supported in **Linux 4.0 and greater** and thus should +only be disabled for such versions. <!-- section-config --> @@ -123,9 +138,11 @@ Kernel-Memory-Access-1 | `CONFIG_DEVMEM` | `n` ## Disable cross-memory attach -Disable the process_vm_*v syscalls which allow one process to peek/poke the virtual memory of another. +Disable the process_vm_*v syscalls which allow one process to peek/poke the +virtual memory of another. -This configuration is supported in **Linux 3.5 and greater** and thus should only be disabled for such versions. +This configuration is supported in **Linux 3.5 and greater** and thus should +only be disabled for such versions. <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.3_Consoles.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.3_Consoles.md index 59ccaf1..297950d 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.3_Consoles.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.3_Consoles.md @@ -1,17 +1,13 @@ --- -edit_link: '' title: Consoles -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/3-Consoles.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Serial ## Disable serial console -The serial console should be disabled to prevent an attacker from accessing this powerful interface. +The serial console should be disabled to prevent an attacker from accessing this +powerful interface. <!-- section-config --> @@ -28,9 +24,14 @@ Kernel-Consoles-Serial-4 | `CONFIG_SERIAL_CORE_CONSOLE` | `n` ## Bake-in the kernel command-line -The kernel command-line is used to control many aspects of the booting kernel, and is prone to tampering as they are passed in RAM with little to no reverse validation on these parameters. To prevent this type of attack, the kernel shall be configured to ignore commands line arguments, and use pre-configured (compile time) options instead. +The kernel command-line is used to control many aspects of the booting kernel, +and is prone to tampering as they are passed in RAM with little to no reverse +validation on these parameters. To prevent this type of attack, the kernel shall +be configured to ignore commands line arguments, and use pre-configured (compile +time) options instead. -Set the kernel command line in the `CONFIG_CMDLINE KConfig` item and then pass no arguments from the bootloader. +Set the kernel command line in the `CONFIG_CMDLINE KConfig` item and then pass +no arguments from the bootloader. <!-- section-config --> @@ -42,13 +43,18 @@ Kernel-Consoles-CommandLine-3 | `CONFIG_CMDLINE_OVERRIDE` | `y` <!-- end-section-config --> -It is recommended that any per-device settings (e.g: MAC addresses, serial numbers, etc.) be stored and accessed from read-only memory (or files), and that any such parameters be verified (signature checking) prior to their use. +It is recommended that any per-device settings (e.g: MAC addresses, serial +numbers, etc.) be stored and accessed from read-only memory (or files), and that +any such parameters be verified (signature checking) prior to their use. -------------------------------------------------------------------------------- ## Disable KGDB -The Linux kernel supports KGDB over USB and console ports. These mechanisms are controlled by the `kgdbdbgp` and `kgdboc` kernel command-line parameters. It is important to ensure that no shipping product contains a kernel with KGDB compiled-in. +The Linux kernel supports KGDB over USB and console ports. These mechanisms are +controlled by the `kgdbdbgp` and `kgdboc` kernel command-line parameters. It is +important to ensure that no shipping product contains a kernel with KGDB +compiled-in. <!-- section-config --> @@ -62,7 +68,10 @@ Kernel-Consoles-KDBG-1 | `CONFIG_KGDB` | `n` ## Disable magic sysrq support -On a few architectures, you can access a powerful debugger interface from the keyboard. The same powerful interface can be present on the serial console (responding to serial break) of Linux on other architectures. Disable to avoid potentially exposing this powerful backdoor. +On a few architectures, you can access a powerful debugger interface from the +keyboard. The same powerful interface can be present on the serial console +(responding to serial break) of Linux on other architectures. Disable to avoid +potentially exposing this powerful backdoor. <!-- section-config --> @@ -76,7 +85,10 @@ Kernel-Consoles-SysRQ-1 | `CONFIG_MAGIC_SYSRQ` | `n` ## Disable support for binary formats other than ELF -This will make possible to plug wrapper-driven binary formats into the kernel. It enables support for binary formats other than ELF. Providing the ability to use alternate interpreters would assist an attacker in discovering attack vectors. +This will make possible to plug wrapper-driven binary formats into the kernel. +It enables support for binary formats other than ELF. Providing the ability to +use alternate interpreters would assist an attacker in discovering attack +vectors. <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.4_Debug.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.4_Debug.md index 52b2e6c..e34839f 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.4_Debug.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.4_Debug.md @@ -1,19 +1,21 @@ --- -edit_link: '' title: Debug -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/4-Debug.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Debug -No debuggers shall be present on the file system. This includes, but is not limited to, the GNU Debugger client/server (commonly known in their short form names such as the `gdb` and `gdbserver` executable binaries respectively), the `LLDB` next generation debugger or the `TCF` (Target Communications Framework) agnostic framework. Including these binaries as part of the file system will facilitate an attacker's ability to reverse engineer and debug (either locally or remotely) any process that is currently executing on the device. +No debuggers shall be present on the file system. This includes, but is not +limited to, the GNU Debugger client/server (commonly known in their short form +names such as the `gdb` and `gdbserver` executable binaries respectively), the +`LLDB` next generation debugger or the `TCF` (Target Communications Framework) +agnostic framework. Including these binaries as part of the file system will +facilitate an attacker's ability to reverse engineer and debug (either locally +or remotely) any process that is currently executing on the device. ## Kernel debug symbols -Debug symbols should always be removed from production kernels as they provide a lot of information to attackers. +Debug symbols should always be removed from production kernels as they provide a +lot of information to attackers. <!-- section-config --> @@ -23,11 +25,14 @@ Kernel-Debug-Symbols-1 | `CONFIG_DEBUG_INFO` | `n` <!-- end-section-config --> -These kernel debug symbols are enabled by other config items in the kernel. Care should be taken to disable those also. If `CONFIG_DEBUG_INFO` cannot be disabled, then enabling `CONFIG_DEBUG_INFO_REDUCED` is second best. +These kernel debug symbols are enabled by other config items in the kernel. Care +should be taken to disable those also. If `CONFIG_DEBUG_INFO` cannot be +disabled, then enabling `CONFIG_DEBUG_INFO_REDUCED` is second best. <!-- section-note --> -At least `CONFIG_DEBUG_INFO_REDUCED` should be always enabled for developers to convert addresses in oops messages to line numbers. +At least `CONFIG_DEBUG_INFO_REDUCED` should be always enabled for developers to +convert addresses in oops messages to line numbers. <!-- end-section-note --> @@ -35,7 +40,10 @@ At least `CONFIG_DEBUG_INFO_REDUCED` should be always enabled for developers to ## Disable Kprobes -Kprobes enables you to dynamically break into any kernel routine and collect debugging and performance information non-disruptively. You can trap at almost any kernel code address, specifying a handler routine to be invoked when the breakpoint is hit. +Kprobes enables you to dynamically break into any kernel routine and collect +debugging and performance information non-disruptively. You can trap at almost +any kernel code address, specifying a handler routine to be invoked when the +breakpoint is hit. <!-- section-config --> @@ -49,7 +57,8 @@ Kernel-Debug-Kprobes-1 | `CONFIG_KPROBES` | `n` ## Disable Tracing -FTrace enables the kernel to trace every kernel function. Providing kernel trace functionality would assist an attacker in discovering attack vectors. +FTrace enables the kernel to trace every kernel function. Providing kernel trace +functionality would assist an attacker in discovering attack vectors. <!-- section-config --> @@ -63,7 +72,9 @@ Kernel-Debug-Tracing-1 | `CONFIG_FTRACE` | `n` ## Disable Profiling -Profiling and OProfile enables profiling the whole system, include the kernel, kernel modules, libraries, and applications. Providing profiling functionality would assist an attacker in discovering attack vectors. +Profiling and OProfile enables profiling the whole system, include the kernel, +kernel modules, libraries, and applications. Providing profiling functionality +would assist an attacker in discovering attack vectors. <!-- section-config --> @@ -78,7 +89,8 @@ Kernel-Debug-Profiling-2 | `CONFIG_PROFILING` | `n` ## Disable OOPS print on BUG() -The output from OOPS print can be helpful in Return Oriented Programming (ROP) when trying to determine the effectiveness of an exploit. +The output from OOPS print can be helpful in Return Oriented Programming (ROP) +when trying to determine the effectiveness of an exploit. <!-- section-config --> @@ -92,7 +104,8 @@ Kernel-Debug-OOPSOnBUG-1 | `CONFIG_DEBUG_BUGVERBOSE` | `n` ## Disable Kernel Debugging -There are development-only branches of code in the kernel enabled by the `DEBUG_KERNEL` conf. This should be disabled to compile-out these branches. +There are development-only branches of code in the kernel enabled by the +`DEBUG_KERNEL` conf. This should be disabled to compile-out these branches. <!-- section-config --> @@ -103,7 +116,11 @@ Kernel-Debug-Dev-2 | `CONFIG_EMBEDDED` | `n` <!-- end-section-config --> -In some kernel versions, disabling this requires also disabling `CONFIG_EMBEDDED`, and `CONFIG_EXPERT`. Disabling `CONFIG_EXPERT` makes it impossible to disable `COREDUMP`, `DEBUG_BUGVERBOSE`, `NAMESPACES`, `KALLSYMS` and `BUG`. In which case it is better to leave this enabled than enable the others. +In some kernel versions, disabling this requires also disabling +`CONFIG_EMBEDDED`, and `CONFIG_EXPERT`. Disabling `CONFIG_EXPERT` makes it +impossible to disable `COREDUMP`, `DEBUG_BUGVERBOSE`, `NAMESPACES`, `KALLSYMS` +and `BUG`. In which case it is better to leave this enabled than enable the +others. -------------------------------------------------------------------------------- @@ -111,7 +128,8 @@ In some kernel versions, disabling this requires also disabling `CONFIG_EMBEDDED ## Disable the kernel debug filesystem -The kernel debug filesystem presents a lot of useful information and means of manipulation of the kernel to an attacker. +The kernel debug filesystem presents a lot of useful information and means of +manipulation of the kernel to an attacker. <!-- section-config --> @@ -125,7 +143,8 @@ Kernel-Debug-FileSystem-1 | `CONFIG_DEBUG_FS` | `n` ## Disable BUG() support -The kernel will display backtrace and register information for BUGs and WARNs in kernel space, making it easier for attackers to develop exploits. +The kernel will display backtrace and register information for BUGs and WARNs in +kernel space, making it easier for attackers to develop exploits. <!-- section-config --> @@ -139,9 +158,11 @@ Kernel-Debug-BUG-1 | `CONFIG_BUG` | `n` ## Disable core dumps -Core dumps provide a lot of debug information for hackers. So disabling core dumps are recommended in production builds. +Core dumps provide a lot of debug information for hackers. So disabling core +dumps are recommended in production builds. -This configuration is supported in **Linux 3.7 and greater** and thus should only be disabled for such versions. +This configuration is supported in **Linux 3.7 and greater** and thus should +only be disabled for such versions. <!-- section-config --> @@ -157,9 +178,13 @@ Kernel-Debug-CoreDumps-1 | `CONFIG_COREDUMP` | `n` ## Kernel Address Display Restriction -When attackers try to develop "run anywhere" exploits for kernel vulnerabilities, they frequently need to know the location of internal kernel structures. By treating kernel addresses as sensitive information, those locations are not visible to regular local users. +When attackers try to develop "run anywhere" exploits for kernel +vulnerabilities, they frequently need to know the location of internal kernel +structures. By treating kernel addresses as sensitive information, those +locations are not visible to regular local users. -**/proc/sys/kernel/kptr_restrict is set to "1"** to block the reporting of known kernel address leaks. +**/proc/sys/kernel/kptr_restrict is set to "1"** to block the reporting of known +kernel address leaks. <!-- section-config --> @@ -169,7 +194,9 @@ Kernel-Debug-AdressDisplay-1 | `/proc/sys/kernel/kptr_restrict` | `1` <!-- end-section-config --> -Additionally, various files and directories should be readable only by the root user: `/boot/vmlinuz*`, `/boot/System.map*`, `/sys/kernel/debug/`, `/proc/slabinfo` +Additionally, various files and directories should be readable only by the root +user: `/boot/vmlinuz*`, `/boot/System.map*`, `/sys/kernel/debug/`, +`/proc/slabinfo` <!-- section-config --> @@ -186,9 +213,12 @@ Kernel-Debug-AdressDisplay-4 | `/proc/slabinfo` | _Readable Only for ## DMESG Restrictions -When attackers try to develop "run anywhere" exploits for vulnerabilities, they frequently will use `dmesg` output. By treating `dmesg` output as sensitive information, this output is not available to the attacker. +When attackers try to develop "run anywhere" exploits for vulnerabilities, they +frequently will use `dmesg` output. By treating `dmesg` output as sensitive +information, this output is not available to the attacker. -**/proc/sys/kernel/dmesg_restrict can be set to "1"** to treat dmesg output as sensitive. +**/proc/sys/kernel/dmesg_restrict can be set to "1"** to treat dmesg output as +sensitive. <!-- section-config --> @@ -198,7 +228,8 @@ Kernel-Debug-DMESG-1 | `/proc/sys/kernel/dmesg_restrict` | `1` <!-- end-section-config --> -Enable the below compiler and linker options when building user-space applications to avoid stack smashing, buffer overflow attacks. +Enable the below compiler and linker options when building user-space +applications to avoid stack smashing, buffer overflow attacks. -------------------------------------------------------------------------------- @@ -206,7 +237,10 @@ Enable the below compiler and linker options when building user-space applicatio ## Disable /proc/config.gz -It is extremely important to not expose the kernel configuration used on a production device to a potential attacker. With access to the kernel config, it could be possible for an attacker to build a custom kernel for the device that may disable critical security features. +It is extremely important to not expose the kernel configuration used on a +production device to a potential attacker. With access to the kernel config, it +could be possible for an attacker to build a custom kernel for the device that +may disable critical security features. <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.5_FileSystems.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.5_FileSystems.md index 0d60d9d..14f8c53 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.5_FileSystems.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/4_Kernel/1.2.4.5_FileSystems.md @@ -1,21 +1,19 @@ --- -edit_link: '' title: File Systems -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-4/5-FileSystems.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # File System ## Disable all file systems not needed -To reduce the attack surface, file system data is parsed by the kernel, so any logic bugs in file system drivers can become kernel exploits. +To reduce the attack surface, file system data is parsed by the kernel, so any +logic bugs in file system drivers can become kernel exploits. ### Disable NFS file system -NFS FileSystems are useful during development phases, but this can be a very helpful way for an attacker to get files when you are in production mode, so we must disable them. +NFS FileSystems are useful during development phases, but this can be a very +helpful way for an attacker to get files when you are in production mode, so we +must disable them. <!-- section-config --> @@ -32,9 +30,11 @@ Kernel-FileSystems-NFS-2 | `CONFIG_NFS_FS` | `n` ## Partition Mount Options -There are several security restrictions that can be set on a filesystem when it is mounted. Some common security options include, but are not limited to: +There are several security restrictions that can be set on a filesystem when it +is mounted. Some common security options include, but are not limited to: -`nosuid` - Do not allow set-user-identifier or set-group-identifier bits to take effect. +`nosuid` - Do not allow set-user-identifier or set-group-identifier bits to take +effect. `nodev` - Do not interpret character or block special devices on the filesystem. @@ -58,7 +58,9 @@ Kernel-FileSystems-Mount-7 | `/dev` | Add `nosuid` and `noexec`. <!-- end-section-config --> <!-- section-note --> -If `CONFIG_DEVTMPFS_MOUNT` is set, then the kernel will mount /dev and will not apply the `nosuid`, `noexec` options. Either disable `CONFIG_DEVTMPFS_MOUNT` or add a remount with `noexec` and `nosuid` options to system startup. +If `CONFIG_DEVTMPFS_MOUNT` is set, then the kernel will mount /dev and will not +apply the `nosuid`, `noexec` options. Either disable `CONFIG_DEVTMPFS_MOUNT` or +add a remount with `noexec` and `nosuid` options to system startup. <!-- end-section-note --> <!-- section-config --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.0_Abstract.md index db911d2..4074b6f 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.0_Abstract.md @@ -1,18 +1,14 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 5 - Platform ## Abstract -The Automotive Grade Linux platform is a Linux distribution with **AGL** compliant applications and services. -The platform includes the following software: +The Automotive Grade Linux platform is a Linux distribution with **AGL** +compliant applications and services. The platform includes the following +software: - Linux **BSP** configured for reference boards. - Proprietary device drivers for common peripherals on reference boards. @@ -34,19 +30,20 @@ This part focuses on the AGL platform including all tools and techniques used to upgrade the security and downgrade the danger. It must be possible to apply the two fundamental principles written at the very beginning of the document. First of all, security management must remain simple. You must also prohibit -everything by default, and then define a set of authorization rules. As cases -to deal with, we must: +everything by default, and then define a set of authorization rules. As cases to +deal with, we must: - Implement a **MAC** for processes and files. - Limit communication between applications (_SystemBus_ and _SystemD_ part). -- Prohibit all tools used during development mode (_Utilities_ and _Services_ part). +- Prohibit all tools used during development mode (_Utilities_ and _Services_ + part). - Manage user capabilities (_Users_ part). - Manage application permissions and policies (_AGLFw_ part). <!-- section-note --> -The tools and concepts used to meet these needs are only examples. -Any other tool that meets the need can be used. +The tools and concepts used to meet these needs are only examples. Any other +tool that meets the need can be used. <!-- end-section-note --> @@ -61,31 +58,33 @@ permissions are granted. ## Discretionary Access Control -**D**iscretionary **A**ccess **C**ontrol (**DAC**) is the traditional Linux method of separating -users and groups from one another. In a shared environment where multiple users -have access to a computer or network, Unix IDs have offered a way to contain access -within privilege areas for individuals, or shared among the group or system. -The Android system took this one step further, assigning new user IDs for each App. -This was never the original intention of Linux UIDs, but was able to provide -Android’s initial security element: the ability to sandbox applications. +**D**iscretionary **A**ccess **C**ontrol (**DAC**) is the traditional Linux +method of separating users and groups from one another. In a shared environment +where multiple users have access to a computer or network, Unix IDs have offered +a way to contain access within privilege areas for individuals, or shared among +the group or system. The Android system took this one step further, assigning +new user IDs for each App. This was never the original intention of Linux UIDs, +but was able to provide Android’s initial security element: the ability to +sandbox applications. Although AGL mentions use of **DAC** for security isolation, the weight of the -security responsibility lies in the **M**andatory **A**ccess **C**ontrol (**MAC**) and **Cynara**. -Furthermore, there are system services with unique UIDs. however,the system -does not go to the extreme of Android, where every application has its own UID. -All sandboxing (app isolation) in AGL is handled in the **MAC** contexts. +security responsibility lies in the **M**andatory **A**ccess **C**ontrol +(**MAC**) and **Cynara**. Furthermore, there are system services with unique +UIDs. however,the system does not go to the extreme of Android, where every +application has its own UID. All sandboxing (app isolation) in AGL is handled in +the **MAC** contexts. ## Mandatory Access Control **M**andatory **A**ccess **C**ontrol (**MAC**) is an extension to **DAC**, -whereby extended attributes (xattr) are associated with the filesystem. -In the case of AGL, the smackfs filesystem allows files and directories -to be associated with a SMACK label, providing the ability of further -discrimination on access control. A SMACK label is a simple null terminated -character string with a maximum of 255 bytes. While it doesn’t offer the -richness of an SELinux label, which provides a user, role,type, and level, -the simplicity of a single value makes the overall design far less complex. -There is arguably less chance of the security author making mistakes in the policies set forth. +whereby extended attributes (xattr) are associated with the filesystem. In the +case of AGL, the smackfs filesystem allows files and directories to be +associated with a SMACK label, providing the ability of further discrimination +on access control. A SMACK label is a simple null terminated character string +with a maximum of 255 bytes. While it doesn’t offer the richness of an SELinux +label, which provides a user, role,type, and level, the simplicity of a single +value makes the overall design far less complex. There is arguably less chance +of the security author making mistakes in the policies set forth. -------------------------------------------------------------------------------- diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.1_Mandatory_Access_Control.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.1_Mandatory_Access_Control.md index 4b027f6..a8226dd 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.1_Mandatory_Access_Control.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.1_Mandatory_Access_Control.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Mandatory Access Control -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/1-MAC.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Mandatory Access Control <!-- section-note --> @@ -24,9 +19,9 @@ uses an **LSM** called **S**implified **M**andatory **A**ccess **C**ontrol labels as part of the extended attributes **SMACK** labels to the file extended attributes. And a policy is also created to define the behaviour of each label. -The kernel access controls is based on these labels and this policy. If there -is no rule, no access will be granted and as a consequence, what is not -explicitly authorized is forbidden. +The kernel access controls is based on these labels and this policy. If there is +no rule, no access will be granted and as a consequence, what is not explicitly +authorized is forbidden. There are two types of **SMACK** labels: @@ -45,7 +40,10 @@ into the following domains: - System. - Applications, Services and User. -See [AGL security framework review](http://iot.bzh/download/public/2017/AMMQ1Tokyo/AGL-security-framework-review.pdf) and [Smack White Paper](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf) +See [AGL security framework +review](http://iot.bzh/download/public/2017/AMMQ1Tokyo/AGL-security-framework-review.pdf) +and [Smack White +Paper](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf) for more information. -------------------------------------------------------------------------------- @@ -153,22 +151,26 @@ There are 4 major components to the system: - Basic utilities for policy management and checking. - The policy/configuration data. -As with any mandatory access system, the policy management needs to be carefully separated -from the checking, as the management utilities can become a convenient point of attack. -Dynamic additions to the policy system need to be carefully verified, as the ability to -update the policies is often needed, but introduces a possible threat. Finally, -even if the policy management is well secured, the policy checking and failure response -to that checking is also of vital importance to the smooth operation of the system. +As with any mandatory access system, the policy management needs to be carefully +separated from the checking, as the management utilities can become a convenient +point of attack. Dynamic additions to the policy system need to be carefully +verified, as the ability to update the policies is often needed, but introduces +a possible threat. Finally, even if the policy management is well secured, the +policy checking and failure response to that checking is also of vital +importance to the smooth operation of the system. -While **MAC** is a certainly a step up in security when compared to DAC, there are still -many ways to compromise a SMACK-enabled Linux system. Some of these ways are as follows: +While **MAC** is a certainly a step up in security when compared to DAC, there +are still many ways to compromise a SMACK-enabled Linux system. Some of these +ways are as follows: -- Disabling SMACK at invocation of the kernel (with command-line: security=none). +- Disabling SMACK at invocation of the kernel (with command-line: + security=none). - Disabling SMACK in the kernel build and redeploying the kernel. - Changing a SMACK attribute of a file or directory at install time. - Tampering with a process with the CAP_MAC_ADMIN privilege. - Setting/Re-setting the SMACK label of a file. -- Tampering with the default domains (i.e. /etc/smack/accesses.d/default-access-domains). +- Tampering with the default domains (i.e. + /etc/smack/accesses.d/default-access-domains). - Disabling or tampering with the SMACK filesystem (i.e. /smackfs). - Adding policies with `smackload` (adding the utility if not present). - Changing labels with `chsmack` (adding the utility if not present). diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.2_SystemD.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.2_SystemD.md index 739ffcb..0ccd4e4 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.2_SystemD.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.2_SystemD.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: SystemD -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/2-SystemD.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # SystemD `afm-system-daemon` is used to: diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.3_SystemBus.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.3_SystemBus.md index 0e37e20..71a2212 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.3_SystemBus.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.3_SystemBus.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: SystemBus -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/3-SystemBus.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # D-Bus D-Bus is a well-known **IPC** (Inter-Process Communication) protocol (and @@ -14,12 +9,14 @@ daemon) that helps applications to talk to each other. The use of D-Bus is great because it allows to implement discovery and signaling. The D-Bus session is by default addressed by environment variable -`DBUS_SESSION_BUS_ADDRESS`. Using **systemd** variable `DBUS_SESSION_BUS_ADDRESS` -is automatically set for user sessions. D-Bus usage is linked to permissions. - -D-Bus has already had several [security issues](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) -(mostly **DoS** issues), to allow applications to keep talking to each other. -It is important to protect against this type of attack to keep the system more +`DBUS_SESSION_BUS_ADDRESS`. Using **systemd** variable +`DBUS_SESSION_BUS_ADDRESS` is automatically set for user sessions. D-Bus usage +is linked to permissions. + +D-Bus has already had several [security +issues](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) +(mostly **DoS** issues), to allow applications to keep talking to each other. It +is important to protect against this type of attack to keep the system more stable. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.4_Services.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.4_Services.md index 426ce52..c3aec00 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.4_Services.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.4_Services.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: System services and daemons -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/4-Services.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # System services and daemons <!-- section-todo --> @@ -24,13 +19,13 @@ Platform-Services-2 | Secure daemon ? few resources as possible. It is a fully modular system that can be extended, through plug-ins, to support all kinds of wired or wireless technologies. - **bluez** is a Bluetooth stack. Its goal is to program an implementation of - the Bluetooth wireless standards specifications. In addition to the basic stack, - the `bluez-utils` and `bluez-firmware` packages contain low level utilities such - as `dfutool` which can interrogate the Bluetooth adapter chipset in order to - determine whether its firmware can be upgraded. -- **gstreamer** is a pipeline-based multimedia framework. It can be used to build - a system that reads files in one format, processes them, and exports them in - another format. + the Bluetooth wireless standards specifications. In addition to the basic + stack, the `bluez-utils` and `bluez-firmware` packages contain low level + utilities such as `dfutool` which can interrogate the Bluetooth adapter + chipset in order to determine whether its firmware can be upgraded. +- **gstreamer** is a pipeline-based multimedia framework. It can be used to + build a system that reads files in one format, processes them, and exports + them in another format. - **alsa** is a software framework and part of the Linux kernel that provides an **API** for sound card device drivers. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.5_Application_framework.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.5_Application_framework.md index d491801..3ce894d 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.5_Application_framework.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.5_Application_framework.md @@ -1,24 +1,24 @@ --- -edit_link: '' title: Application Framework -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/5-AppFw.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Application framework/model (**AppFw**) The AGL application framework consists of several inter-working parts: -- **SMACK**: The kernel level **LSM** (**L**inux **S**ecurity **M**odule) that performs extended access control of the system. -- **Cynara**: the native gatekeeper daemon used for policy handling, updating to the database and policy checking. -- Security Manager: a master service, through which all security events are intended to take place. -- Several native application framework utilities: `afm-main-binding`, `afm-user-daemon`, `afm-system-daemon`. +- **SMACK**: The kernel level **LSM** (**L**inux **S**ecurity **M**odule) that + performs extended access control of the system. +- **Cynara**: the native gatekeeper daemon used for policy handling, updating to + the database and policy checking. +- Security Manager: a master service, through which all security events are + intended to take place. +- Several native application framework utilities: `afm-main-binding`, + `afm-user-daemon`, `afm-system-daemon`. The application framework manages: -- The applications and services management: Installing, Uninstalling, Listing, ... +- The applications and services management: Installing, Uninstalling, Listing, + ... - The life cycle of applications: Start -> (Pause, Resume) -> Stop. - Events and signals propagation. - Privileges granting and checking. @@ -31,10 +31,10 @@ The application framework manages: implementation detail that should not impact the layers above the application framework. -- The **security model** refers to how **DAC** (**D**iscretionary **A**ccess **C**ontrol), - **MAC** (Mandatory Access Control) and `Capabilities` are used by the system to - ensure security and privacy. It also includes features of reporting using - audit features and by managing logs and alerts. +- The **security model** refers to how **DAC** (**D**iscretionary **A**ccess + **C**ontrol), **MAC** (Mandatory Access Control) and `Capabilities` are used + by the system to ensure security and privacy. It also includes features of + reporting using audit features and by managing logs and alerts. <!-- end-section-note --> @@ -50,21 +50,24 @@ Platform-AGLFw-AppFw-1 | Security model | Use the AppFw as Security model. <!-- end-section-config --> -See [AGL AppFw Privileges Management](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/iotbzh2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) and [AGL - Application Framework Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf) for more -information. +See [AGL AppFw Privileges +Management](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/iotbzh2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) +and [AGL - Application Framework +Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf) +for more information. <!-- pagebreak --> -The Security Manager communicates policy information to **Cynara**, -which retains information in its own database in the format of a text -file with comma-separated values (CSV). There are provisions to retain -a copy of the CSV text file when the file is being updated. +The Security Manager communicates policy information to **Cynara**, which +retains information in its own database in the format of a text file with +comma-separated values (CSV). There are provisions to retain a copy of the CSV +text file when the file is being updated. -Runtime checking occurs through **Cynara**. Each application that is -added to the framework has its own instantiation of a SMACK context -and D-bus bindings. The afb_daemon and Binder form a web-service that -is communicated to through http or a websocket from the application-proper. -This http or websocket interface uses a standard unique web token for API communication. +Runtime checking occurs through **Cynara**. Each application that is added to +the framework has its own instantiation of a SMACK context and D-bus bindings. +The afb_daemon and Binder form a web-service that is communicated to through +http or a websocket from the application-proper. This http or websocket +interface uses a standard unique web token for API communication.  @@ -81,14 +84,16 @@ Cynara interact with **D-Bus** in order to deliver this information. Cynara consists of several parts: -- Cynara: a daemon for controlling policies and responding to access control requests. +- Cynara: a daemon for controlling policies and responding to access control + requests. - Database: a spot to hold policies. - Libraries: several static and dynamic libraries for communicating with Cynara. -The daemon communicates to the libraries over Unix domain sockets. -The database storage format is a series of CSV-like files with an index file. +The daemon communicates to the libraries over Unix domain sockets. The database +storage format is a series of CSV-like files with an index file. -There are several ways that an attacker can manipulate policies of the Cynara system: +There are several ways that an attacker can manipulate policies of the Cynara +system: - Disable Cynara by killing the process. - Tamper with the Cynara binary on-disk or in-memory. @@ -96,9 +101,9 @@ There are several ways that an attacker can manipulate policies of the Cynara sy - Tamper with the database controlled by Cynara. - Highjack the communication between Cynara and the database. -The text-based database is the weakest part of the system and although there are some -consistency mechanisms in place (i.e. the backup guard), these mechanisms are weak at best -and can be countered by an attacker very easily. +The text-based database is the weakest part of the system and although there are +some consistency mechanisms in place (i.e. the backup guard), these mechanisms +are weak at best and can be countered by an attacker very easily. <!-- section-config --> @@ -127,36 +132,39 @@ Platform-AGLFw-Cynara-1 | Permissions | Use Cynara as policy-checker service. Policies are kept in buckets. Buckets are set of policies which have additional a property of default answer, the default answer is yielded if no policy matches -searched key. Buckets have names which might be used in policies (for directions). +searched key. Buckets have names which might be used in policies (for +directions). ## Attack Vectors The following attack vectors are not completely independent. While attackers may -have varying levels of access to an AGL system, experience has shown that a typical -attack can start with direct access to a system, find the vulnerabilities, -then proceed to automate the attack such that it can be invoked from less accessible -standpoint (e.g. remotely). Therefore, it is important to assess all threat levels, -and protect the system appropriately understanding that direct access attacks -are the door-way into remote attacks. +have varying levels of access to an AGL system, experience has shown that a +typical attack can start with direct access to a system, find the +vulnerabilities, then proceed to automate the attack such that it can be invoked +from less accessible standpoint (e.g. remotely). Therefore, it is important to +assess all threat levels, and protect the system appropriately understanding +that direct access attacks are the door-way into remote attacks. ### Remote Attacks -The local web server interface used for applications is the first point of attack, -as web service APIs are well understood and easily intercepted. The local web server -could potentially be exploited by redirecting web requests through the local service -and exploiting the APIs. While there is the use of a security token on the web -service API, this is weak textual matching at best. This will not be difficult to spoof. -It is well known that [API Keys do not provide any real security](http://nordicapis.com/why-api-keys-are-not-enough/). +The local web server interface used for applications is the first point of +attack, as web service APIs are well understood and easily intercepted. The +local web server could potentially be exploited by redirecting web requests +through the local service and exploiting the APIs. While there is the use of a +security token on the web service API, this is weak textual matching at best. +This will not be difficult to spoof. It is well known that [API Keys do not +provide any real security](http://nordicapis.com/why-api-keys-are-not-enough/). It is likely that the architectural inclusion of an http / web-service interface -provided the most flexibility for applications to be written natively or in HTML5. -However, this flexibility may trade-off with security concerns. For example, -if a native application were linked directly to the underlying framework services, -there would be fewer concerns over remote attacks coming through the web-service interface. +provided the most flexibility for applications to be written natively or in +HTML5. However, this flexibility may trade-off with security concerns. For +example, if a native application were linked directly to the underlying +framework services, there would be fewer concerns over remote attacks coming +through the web-service interface. Leaving the interface as designed, mitigations to attacks could include further -securing the interface layer with cryptographic protocols: -e.g. encrypted information passing, key exchange (e.g. Elliptic-Curve Diffie-Hellman). +securing the interface layer with cryptographic protocols: e.g. encrypted +information passing, key exchange (e.g. Elliptic-Curve Diffie-Hellman). ### User-level Native Attacks @@ -167,49 +175,55 @@ e.g. encrypted information passing, key exchange (e.g. Elliptic-Curve Diffie-Hel - Spoofing the D-bus Interface - Adding executables/libraries -With direct access to the device, there are many security concerns on the native level. -For example, as **Cynara** uses a text file data-base with comma-separated values (CSV), -an attacker could simply modify the data-base to escalate privileges of an application. -Once a single application has all the privileges possible on the system, exploits can -come through in this manner. Similarly the SQLite database used by the Security Manager -is not much different than a simple text file. There are many tools available to add, -remove, modify entries in an SQLite data-base. - -On the next level, a common point of attack is to modify binaries or daemons for exploiting -functionality. There are many Linux tools available to aid in this regard, -including: [IDA Pro](https://www.hex-rays.com/products/ida/index.shtml), -and [radare2](https://rada.re/r/). With the ability to modify binaries, -an attacker can do any number of activities including: removing calls to security checks, -redirecting control to bypass verification functionality, ignoring security policy handling, -escalating privileges, etc. - -Additionally, another attack vector would be to spoof the D-bus interface. D-bus is a -message passing system built upon Inter-Process Communication (IPC), where structured -messages are passed based upon a protocol. The interface is generic and well documented. -Therefore, modifying or adding binaries/libraries to spoof this interface is a relatively -straight-forward process. Once the interface has been spoofed, the attacker can issue any -number of commands that lead into control of low-level functionality. - -Protecting a system from native attacks requires a methodical approach. First, the system -should reject processes that are not sanctioned to run. Signature-level verification at -installation time will help in this regard, but run-time integrity verification is much better. -Signatures need to originate from authorized parties, which is discussed further -in a later section on the Application Store. - -On the next level, executables should not be allowed to do things where they have not been -granted permission. DAC and SMACK policies can help in this regard. On the other hand, -there remain concerns with memory accesses, system calls, and other process activity -that may go undetected. For this reason, a secure environment which monitors all activity -can give indication of all unauthorized activity on the system. +With direct access to the device, there are many security concerns on the native +level. For example, as **Cynara** uses a text file data-base with +comma-separated values (CSV), an attacker could simply modify the data-base to +escalate privileges of an application. Once a single application has all the +privileges possible on the system, exploits can come through in this manner. +Similarly the SQLite database used by the Security Manager is not much different +than a simple text file. There are many tools available to add, remove, modify +entries in an SQLite data-base. + +On the next level, a common point of attack is to modify binaries or daemons for +exploiting functionality. There are many Linux tools available to aid in this +regard, including: [IDA Pro](https://www.hex-rays.com/products/ida/index.shtml), +and [radare2](https://rada.re/r/). With the ability to modify binaries, an +attacker can do any number of activities including: removing calls to security +checks, redirecting control to bypass verification functionality, ignoring +security policy handling, escalating privileges, etc. + +Additionally, another attack vector would be to spoof the D-bus interface. D-bus +is a message passing system built upon Inter-Process Communication (IPC), where +structured messages are passed based upon a protocol. The interface is generic +and well documented. Therefore, modifying or adding binaries/libraries to spoof +this interface is a relatively straight-forward process. Once the interface has +been spoofed, the attacker can issue any number of commands that lead into +control of low-level functionality. + +Protecting a system from native attacks requires a methodical approach. First, +the system should reject processes that are not sanctioned to run. +Signature-level verification at installation time will help in this regard, but +run-time integrity verification is much better. Signatures need to originate +from authorized parties, which is discussed further in a later section on the +Application Store. + +On the next level, executables should not be allowed to do things where they +have not been granted permission. DAC and SMACK policies can help in this +regard. On the other hand, there remain concerns with memory accesses, system +calls, and other process activity that may go undetected. For this reason, a +secure environment which monitors all activity can give indication of all +unauthorized activity on the system. Finally, it is very difficult to catch attacks of direct tampering in a system. -These types of attacks require a defense-in-depth approach, where complementary software -protection and hardening techniques are needed. Tamper-resistance and anti-reverse-engineering -technologies include program transformations/obfuscation, integrity verification, -and white-box cryptography. If applied in a mutually-dependent fashion and considering -performance/security tradeoffs, the approach can provide an effective barrier -to direct attacks to the system. Furthermore, the use of threat monitoring provides a -valuable telemetry/analytics capability and the ability to react and renew a system under attack. +These types of attacks require a defense-in-depth approach, where complementary +software protection and hardening techniques are needed. Tamper-resistance and +anti-reverse-engineering technologies include program +transformations/obfuscation, integrity verification, and white-box cryptography. +If applied in a mutually-dependent fashion and considering performance/security +tradeoffs, the approach can provide an effective barrier to direct attacks to +the system. Furthermore, the use of threat monitoring provides a valuable +telemetry/analytics capability and the ability to react and renew a system under +attack. ### Root-level Native Attacks @@ -219,58 +233,70 @@ valuable telemetry/analytics capability and the ability to react and renew a sys - Disabling SMACK - Tampering the kernel -Once root-level access (i.e. su) has been achieved on the device, there are many ways -to compromise the system. The system daemon, **Cynara**, and the security manager are -vulnerable to tampering attacks. For example, an executable can be modified in memory -to jam a branch, jump to an address, or disregard a check. This can be as simple as replacing -a branch instruction with a NOP, changing a memory value, or using a debugger (e.g. gdb, IDA) -to change an instruction. Tampering these executables would mean that policies can be -ignored and verification checks can be bypassed. - -Without going so far as to tamper an executable, the **SMACK** system is also vulnerable to attack. -For example, if the kernel is stopped and restarted with the *security=none* flag, -then SMACK is not enabled. Furthermore, `systemd` starts the loading of **SMACK** rules during -start-up. If this start-up process is interfered with, then **SMACK** will not run. -Alternatively, new policies can be added with `smackload` allowing unforseen privileges -to alternative applications/executables. - -Another intrusion on the kernel level is to rebuild the kernel (as it is open-source) -and replace it with a copy that has **SMACK** disabled, or even just the **SMACK** filesystem -(`smackfs`) disabled. Without the extended label attributes, the **SMACK** system is disabled. - -Root-level access to the device has ultimate power, where the entire system can be compromised. -More so, a system with this level access allows an attacker to craft a simpler *point-attack* -which can operate on a level requiring fewer privileges (e.g. remote access, user-level access). +Once root-level access (i.e. su) has been achieved on the device, there are many +ways to compromise the system. The system daemon, **Cynara**, and the security +manager are vulnerable to tampering attacks. For example, an executable can be +modified in memory to jam a branch, jump to an address, or disregard a check. +This can be as simple as replacing a branch instruction with a NOP, changing a +memory value, or using a debugger (e.g. gdb, IDA) to change an instruction. +Tampering these executables would mean that policies can be ignored and +verification checks can be bypassed. + +Without going so far as to tamper an executable, the **SMACK** system is also +vulnerable to attack. For example, if the kernel is stopped and restarted with +the *security=none* flag, then SMACK is not enabled. Furthermore, `systemd` +starts the loading of **SMACK** rules during start-up. If this start-up process +is interfered with, then **SMACK** will not run. Alternatively, new policies can +be added with `smackload` allowing unforseen privileges to alternative +applications/executables. + +Another intrusion on the kernel level is to rebuild the kernel (as it is +open-source) and replace it with a copy that has **SMACK** disabled, or even +just the **SMACK** filesystem (`smackfs`) disabled. Without the extended label +attributes, the **SMACK** system is disabled. + +Root-level access to the device has ultimate power, where the entire system can +be compromised. More so, a system with this level access allows an attacker to +craft a simpler *point-attack* which can operate on a level requiring fewer +privileges (e.g. remote access, user-level access). ## Vulnerable Resources ### Resource: `afm-user-daemon` -The `afm-user-daemon` is in charge of handling applications on behalf of a user. Its main tasks are: +The `afm-user-daemon` is in charge of handling applications on behalf of a user. +Its main tasks are: -- Enumerate applications that the end user can run and keep this list available on demand. -- Start applications on behalf of the end user, set user running environment, set user security context. +- Enumerate applications that the end user can run and keep this list available + on demand. +- Start applications on behalf of the end user, set user running environment, + set user security context. - List current runnable or running applications. -- Stop (aka pause), continue (aka resume), terminate a running instance of a given application. -- Transfer requests for installation/uninstallation of applications to the corresponding system daemon afm-system-daemon. - -The `afm-user-daemon` launches applications. It builds a secure environment for the application -before starting it within that environment. Different kinds of applications can be launched, -based on a configuration file that describes how to launch an application of a given kind within -a given launching mode: local or remote. Launching an application locally means that -the application and its binder are launched together. Launching an application remotely -translates in only launching the application binder. - -The UI by itself has to be activated remotely by a request (i.e. HTML5 homescreen in a browser). -Once launched, running instances of the application receive a `runid` that identifies them. -`afm-user-daemon` manages the list of applications that it has launched. -When owning the right permissions, a client can get the list of running instances and details -about a specific running instance. It can also terminate, stop or continue a given application. -If the client owns the right permissions, `afm-user-daemon` delegates the task of +- Stop (aka pause), continue (aka resume), terminate a running instance of a + given application. +- Transfer requests for installation/uninstallation of applications to the + corresponding system daemon afm-system-daemon. + +The `afm-user-daemon` launches applications. It builds a secure environment for +the application before starting it within that environment. Different kinds of +applications can be launched, based on a configuration file that describes how +to launch an application of a given kind within a given launching mode: local or +remote. Launching an application locally means that the application and its +binder are launched together. Launching an application remotely translates in +only launching the application binder. + +The UI by itself has to be activated remotely by a request (i.e. HTML5 +homescreen in a browser). Once launched, running instances of the application +receive a `runid` that identifies them. `afm-user-daemon` manages the list of +applications that it has launched. When owning the right permissions, a client +can get the list of running instances and details about a specific running +instance. It can also terminate, stop or continue a given application. If the +client owns the right permissions, `afm-user-daemon` delegates the task of installing and uninstalling applications to `afm-system-daemon`. `afm-user-daemon` is launched as a `systemd` service attached to a user session. -Normally, the service file is located at /usr/lib/systemd/user/afm-user-daemon.service. +Normally, the service file is located at +/usr/lib/systemd/user/afm-user-daemon.service. Attacker goals: @@ -286,13 +312,16 @@ Attacker goals: ### Resource: `afm-system-daemon` -The `afm-system-daemon` is in charge of installing applications on the AGL system. Its main tasks are: +The `afm-system-daemon` is in charge of installing applications on the AGL +system. Its main tasks are: -- Install applications and setup security framework for newly installed applications. +- Install applications and setup security framework for newly installed + applications. - Uninstall applications. -`afm-system-daemon` is launched as a `systemd` service attached to system. Normally, -the service file is located at /lib/systemd/system/afm-systemdaemon.service. +`afm-system-daemon` is launched as a `systemd` service attached to system. +Normally, the service file is located at +/lib/systemd/system/afm-systemdaemon.service. Attacker goals: @@ -302,23 +331,27 @@ Attacker goals: ### Resource `afb-daemon` -`afb-binder` is in charge of serving resources and features through an HTTP interface. -`afb-daemon` is in charge of binding one instance of an application to the AGL framework -and AGL system. The application and its companion binder run in a secured and isolated -environment set for them. Applications are intended to access to AGL system through the binder. -`afb-daemon` binders serve files through HTTP protocol and offers developers the capability -to expose application API methods through HTTP or WebSocket protocol. +`afb-binder` is in charge of serving resources and features through an HTTP +interface. `afb-daemon` is in charge of binding one instance of an application +to the AGL framework and AGL system. The application and its companion binder +run in a secured and isolated environment set for them. Applications are +intended to access to AGL system through the binder. `afb-daemon` binders serve +files through HTTP protocol and offers developers the capability to expose +application API methods through HTTP or WebSocket protocol. -Binder bindings are used to add APIs to `afb-daemon`. The user can write a binding for `afb-daemon`. -The binder `afb-daemon` serves multiple purposes: +Binder bindings are used to add APIs to `afb-daemon`. The user can write a +binding for `afb-daemon`. The binder `afb-daemon` serves multiple purposes: 1. It acts as a gateway for the application to access the system. 2. It acts as an HTTP server for serving files to HTML5 applications. -3. It allows HTML5 applications to have native extensions subject to security enforcement for accessing hardware resources or for speeding up parts of algorithm. +3. It allows HTML5 applications to have native extensions subject to security + enforcement for accessing hardware resources or for speeding up parts of + algorithm. Attacker goals: - Break from isolation. - Disable `afb-daemon`. - Tamper `afb-demon` on disk or in memory. -- Tamper **capabilities** by creating/installing custom bindings for `afb-daemon`.
\ No newline at end of file +- Tamper **capabilities** by creating/installing custom bindings for + `afb-daemon`.
\ No newline at end of file diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.6_Utilities.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.6_Utilities.md index 8036a6f..6e69658 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.6_Utilities.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.6_Utilities.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Utilities -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/6-Utilities.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Utilities - **busybox**: Software that provides several stripped-down Unix tools in a diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.7_Users.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.7_Users.md index f520baa..c1a8506 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.7_Users.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/5_Platform/1.2.5.7_Users.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Users -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-5/7-Users.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Users The user policy can group users by function within the car. For example, we can @@ -83,4 +78,5 @@ a capability. These capabilities are divided into three groups: - e: Effective: This means the capability is “activated”. - p: Permitted: This means the capability can be used/is allowed. -- i: Inherited: The capability is kept by child/subprocesses upon execve() for example. +- i: Inherited: The capability is kept by child/subprocesses upon execve() for + example. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.0_Abstract.md index ae7b7dc..2925efb 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.0_Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-6/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 6 - Application ## Abstract @@ -38,35 +33,40 @@ AGL provides a framework for applications to be written in different forms: - Native application: in C While there is no harm in providing multiple types of applications, from a -security perspective this does increase the attack surface for an intruder. -The application framework (**AppFw**) consists of a number of utilities and -daemons which provide context for the applications. -Isolation is provided through **SMACK** labels. +security perspective this does increase the attack surface for an intruder. The +application framework (**AppFw**) consists of a number of utilities and daemons +which provide context for the applications. Isolation is provided through +**SMACK** labels. ## Application Store -Although the Tizen system has defined a [system of App signing and signing flow](https://wiki.tizen.org/Security/Tizen_3.X_Overview#Application_Singing_and_Certificates) -to avoid the spread of unauthorized Apps that might contain malware. -At this point, it is unclear how much of this flow AGL will adopt. -However, judging from the experience, it is an essential topic. For example, -the Google Play Store controls the authorization of Apps through signing, and still, -there are [many accounts of Apps containing malware on the store](http://www.eweek.com/mobile/researchers-find-132-malware-infected-android-apps-on-google-play). - -Tizen defines 5 levels of certificates and signing at each level, including an author, -testing distributor, public level store distributor, partner level store distributor, -and platform level store distributor. AGL may define a different number of third parties, -but at a minimum an author and store distributor should be defined. +Although the Tizen system has defined a [system of App signing and signing +flow](https://wiki.tizen.org/Security/Tizen_3.X_Overview#Application_Singing_and_Certificates) +to avoid the spread of unauthorized Apps that might contain malware. At this +point, it is unclear how much of this flow AGL will adopt. However, judging from +the experience, it is an essential topic. For example, the Google Play Store +controls the authorization of Apps through signing, and still, there are [many +accounts of Apps containing malware on the +store](http://www.eweek.com/mobile/researchers-find-132-malware-infected-android-apps-on-google-play). + +Tizen defines 5 levels of certificates and signing at each level, including an +author, testing distributor, public level store distributor, partner level store +distributor, and platform level store distributor. AGL may define a different +number of third parties, but at a minimum an author and store distributor should +be defined.  -Once the number of signatures has been established, verification of those signatures needs -to be done at a minimum at installation time on the AGL device. It is important to ensure -the robustness/integrity of the public key used for signature verification. If the public key is modified, -then this compromised key can be used to verify an attacker's private key signature. +Once the number of signatures has been established, verification of those +signatures needs to be done at a minimum at installation time on the AGL device. +It is important to ensure the robustness/integrity of the public key used for +signature verification. If the public key is modified, then this compromised key +can be used to verify an attacker's private key signature. -Further to this, installation-time verification is limited. Attacks can happen to apps in-memory -at runtime. Any modifications made after installation will be missed by installation-time verification. -Integrity verification that runs during execution makes for a more complete security story. +Further to this, installation-time verification is limited. Attacks can happen +to apps in-memory at runtime. Any modifications made after installation will be +missed by installation-time verification. Integrity verification that runs +during execution makes for a more complete security story. -------------------------------------------------------------------------------- diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.1_Installation.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.1_Installation.md index 70b572f..9279be8 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.1_Installation.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.1_Installation.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Installation -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-6/1-Installation.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Local <!-- section-todo --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.2_Privilege_Management.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.2_Privilege_Management.md index e085929..69445ac 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.2_Privilege_Management.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.2_Privilege_Management.md @@ -1,16 +1,11 @@ --- -edit_link: '' title: Privilege management -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-6/2-PrivilegeManagement.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Local ## Privilege Management -Application privileges are managed by **Cynara** and the security manager in -the **AppFw**. For more details, please refer to the **AppFw** documentation -in Platform part. +Application privileges are managed by **Cynara** and the security manager in the +**AppFw**. For more details, please refer to the **AppFw** documentation in +Platform part. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.3_Signature.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.3_Signature.md index 73c17f9..671de13 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.3_Signature.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.3_Signature.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Signature -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-6/3-Signature.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # App Signature <!-- section-todo --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.4_Services.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.4_Services.md index b9653a2..ccd809c 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.4_Services.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/6_Application/1.2.6.4_Services.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Services -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-6/4-Services.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Services <!-- section-todo --> diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.0_Abstract.md index ad11649..499d858 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.0_Abstract.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-7/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 7 - Connectivity ## Abstract diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.1_Bus_And_Connectors.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.1_Bus_And_Connectors.md index 4403d41..c7b577a 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.1_Bus_And_Connectors.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.1_Bus_And_Connectors.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Bus and connectors -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-7/1-BusAndConnectors.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Bus We only speak about the **CAN** bus to take an example, because the different @@ -15,8 +10,8 @@ engineering and the main argument to improve their security is to encrypt data packets. We just describe them a bit: - **CAN**: Controller Area Network, developed in the early 1980s, is an - event-triggered controller network for serial communication with data rates - up to one MBit/s. **CAN** messages are classified over their respective + event-triggered controller network for serial communication with data rates up + to one MBit/s. **CAN** messages are classified over their respective identifier. **CAN** controller broadcast their messages to all connected nodes and all receiving nodes decide independently if they process the message. - **FlewRay**: Is a deterministic and error-tolerant high-speed bus. With a data @@ -37,16 +32,17 @@ packets. We just describe them a bit: On just about every vehicle, **ECU**s (**E**lectronic **C**ontrol **U**nits) communicate over a CAN bus, which is a two-wire bus using hardware arbitration for messages sent on the shared medium. This is essentially a *trusted* network -where all traffic is visible to all controllers and any controller can send any message. +where all traffic is visible to all controllers and any controller can send any +message. A malicious **ECU** on the CAN bus can easily inject messages destined for any other device, including things like the instrument cluster and the head unit. -There are common ways for hardware to do USB to CAN and open source software to send -and receive messages. For example, there is a driver included in the Linux kernel -that can be used to send/receive CAN signals. A malicious device on the CAN bus can -cause a great number of harmful things to happen to the system, including: sending -bogus information to other devices, sending unintended commands to ECUs, -causing DOS (Denial Of Service) on the CAN bus, etc. +There are common ways for hardware to do USB to CAN and open source software to +send and receive messages. For example, there is a driver included in the Linux +kernel that can be used to send/receive CAN signals. A malicious device on the +CAN bus can cause a great number of harmful things to happen to the system, +including: sending bogus information to other devices, sending unintended +commands to ECUs, causing DOS (Denial Of Service) on the CAN bus, etc. <!-- section-config --> @@ -56,7 +52,9 @@ Connectivity-BusAndConnector-Bus-1 | CAN | Implement hardware solution in <!-- end-section-config --> -See [Security in Automotive Bus Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf) for more information. +See [Security in Automotive Bus +Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf) +for more information. # Connectors diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.2_Wireless.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.2_Wireless.md index 1be314d..ce0259e 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.2_Wireless.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.2_Wireless.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Wireless -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-7/2-Wireless.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Wireless In this part, we talk about possible remote attacks on a car, according to the @@ -46,16 +41,21 @@ Connectivity-Wireless-1 | Add communication channels (RFID, ZigBee?). -------------------------------------------------------------------------------- For existing automotive-specific means, we take examples of existing system -attacks from the _IOActive_ document ([A Survey of Remote Automotive Attack Surfaces](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf)) -and from the ETH document ([Relay Attacks on Passive Keyless Entry and Start Systems in Modern Cars](https://eprint.iacr.org/2010/332.pdf)). +attacks from the _IOActive_ document ([A Survey of Remote Automotive Attack +Surfaces](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf)) +and from the ETH document ([Relay Attacks on Passive Keyless Entry and Start +Systems in Modern Cars](https://eprint.iacr.org/2010/332.pdf)). - [Telematics](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A40%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) -- [Passive Anti-Theft System (PATS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A11%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C574%2C0%5D) +- [Passive Anti-Theft System + (PATS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A11%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C574%2C0%5D) -- [Tire Pressure Monitoring System (TPMS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A17%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) +- [Tire Pressure Monitoring System + (TPMS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A17%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) -- [Remote Keyless Entry/Start (RKE)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A26%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) +- [Remote Keyless Entry/Start + (RKE)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A26%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) - [Passive Keyless Entry (PKE)](https://eprint.iacr.org/2010/332.pdf) @@ -85,10 +85,11 @@ We can differentiate existing attacks on wifi in two categories: Those on - **WPA** attacks: - **Beck and Tews**: Exploit weakness in **TKIP**. "Allow the attacker to - decrypt **ARP** packets and to inject traffic into a network, even - allowing him to perform a **DoS** or an **ARP** poisoning". + decrypt **ARP** packets and to inject traffic into a network, even allowing + him to perform a **DoS** or an **ARP** poisoning". - [KRACK](https://github.com/kristate/krackinfo): (K)ey (R)einstallation - (A)tta(ck) ([jira AGL SPEC-1017](https://jira.automotivelinux.org/browse/SPEC-1017)). + (A)tta(ck) ([jira AGL + SPEC-1017](https://jira.automotivelinux.org/browse/SPEC-1017)). ### Recommendations @@ -110,9 +111,9 @@ Connectivity-Wireless-Wifi-5 | Device | Upgraded easily in software <!-- end-section-config --> -See [Wifi attacks WEP WPA](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf) -and [Breaking wep and wpa (Beck and Tews)](https://dl.aircrack-ng.org/breakingwepandwpa.pdf) -for more information. +See [Wifi attacks WEP WPA](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf) and +[Breaking wep and wpa (Beck and +Tews)](https://dl.aircrack-ng.org/breakingwepandwpa.pdf) for more information. -------------------------------------------------------------------------------- @@ -132,7 +133,8 @@ for more information. features but is limited by the transmitting power of class 2 Bluetooth radios, normally capping its range at 10-15 meters. - **Bluejacking** is the sending of unsolicited messages. -- **BLE**: **B**luetooth **L**ow **E**nergy [attacks](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf). +- **BLE**: **B**luetooth **L**ow **E**nergy + [attacks](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf). - **DoS**: Drain a device's battery or temporarily paralyze the phone. ### Recommendations @@ -142,8 +144,8 @@ for more information. - Monitoring. - Use **BLE** with caution. - For v2.1 and later devices using **S**ecure **S**imple **P**airing (**SSP**), - avoid using the "Just Works" association model. The device must verify that - an authenticated link key was generated during pairing. + avoid using the "Just Works" association model. The device must verify that an + authenticated link key was generated during pairing. <!-- section-config --> @@ -157,10 +159,13 @@ Connectivity-Wireless-Bluetooth-5 | Anti-scanning | Used, inter alia, to slow do <!-- end-section-config --> -See [Low energy and the automotive transformation](http://www.ti.com/lit/wp/sway008/sway008.pdf), -[Gattacking Bluetooth Smart Devices](http://gattack.io/whitepaper.pdf), -[Comprehensive Experimental Analyses of Automotive Attack Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf) -and [With Low Energy comes Low Security](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf) +See [Low energy and the automotive +transformation](http://www.ti.com/lit/wp/sway008/sway008.pdf), [Gattacking +Bluetooth Smart Devices](http://gattack.io/whitepaper.pdf), [Comprehensive +Experimental Analyses of Automotive Attack +Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf) and [With Low +Energy comes Low +Security](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf) for more information. -------------------------------------------------------------------------------- @@ -177,7 +182,8 @@ for more information. the service provider's real towers, it is considered a man-in-the-middle (**MITM**) attack. -- Lack of mutual authentication (**GPRS**/**EDGE**) and encryption with **GEA0**. +- Lack of mutual authentication (**GPRS**/**EDGE**) and encryption with + **GEA0**. - **Fall back** from **UMTS**/**HSPA** to **GPRS**/**EDGE** (Jamming against **UMTS**/**HSPA**). @@ -197,7 +203,8 @@ Connectivity-Wireless-Cellular-2 | UMTS/HSPA | Protected against Jamming. <!-- end-section-config --> -See [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf) +See [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data +communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf) for more information. -------------------------------------------------------------------------------- @@ -234,7 +241,8 @@ Connectivity-Wireless-Radio-1 | RDS | Only audio output and meta concernin ### Recommendations -- Should implements protection against relay and replay attacks (Tokens, etc...). +- Should implements protection against relay and replay attacks (Tokens, + etc...). - Disable unneeded and unapproved services and profiles. - NFC should be use encrypted link (secure channel). A standard key agreement protocol like Diffie-Hellmann based on RSA or Elliptic Curves could be applied diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.3_Cloud.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.3_Cloud.md index 36c4df8..d4112fc 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.3_Cloud.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/7_Connectivity/1.2.7.3_Cloud.md @@ -1,12 +1,7 @@ --- -edit_link: '' title: Cloud -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-7/3-Cloud.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Cloud ## Download @@ -16,8 +11,8 @@ origin_url: >- characteristics bound to that device, entity or person. - **Authorization**: Parses the network to allow access to some or all network -functionality by providing rules and allowing access or denying access based -on a subscriber's profile and services purchased. + functionality by providing rules and allowing access or denying access based + on a subscriber's profile and services purchased. <!-- section-config --> @@ -75,10 +70,10 @@ Application-Cloud-Infrastructure-5 | App integrity | Applications must be signed ## Transport -For data transport, it is necessary to **encrypt data end-to-end**. To prevent **MITM** attacks, -no third party should be able to interpret transported data. Another aspect -is the data anonymization in order to protect the leakage of private information -on the user or any other third party. +For data transport, it is necessary to **encrypt data end-to-end**. To prevent +**MITM** attacks, no third party should be able to interpret transported data. +Another aspect is the data anonymization in order to protect the leakage of +private information on the user or any other third party. The use of standards such as **IPSec** provides "_private and secure communications over IP networks, through the use of cryptographic security @@ -99,8 +94,8 @@ to configure each application to **IPSec** standards. - Integrity: A service that consists in ensuring that data has not been tampered with accidentally or fraudulently. - Replay Protection: A service that prevents attacks by re-sending a valid - intercepted packet to the network for the same authorization. - This service is provided by the presence of a sequence number. + intercepted packet to the network for the same authorization. This service is + provided by the presence of a sequence number. - Key management: Mechanism for negotiating the length of encryption keys between two **IPSec** elements and exchange of these keys. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.0_Abstract.md index f153ea9..cd47ed0 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.0_Abstract.md @@ -1,73 +1,82 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-8/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 8 - Update (**OTA**) ## Abstract Updating applications and firmware is essential for the development of new -features and even more to fix security bugs. -However, if a malicious third party manages to alter the content during -transport, it could -alter the functioning of the system and/or applications. The security of the -updates is therefore a critical point to evaluate in order to guarantee the -integrity, the confidentiality and the legitimacy of the transmitted data. +features and even more to fix security bugs. However, if a malicious third party +manages to alter the content during transport, it could alter the functioning of +the system and/or applications. The security of the updates is therefore a +critical point to evaluate in order to guarantee the integrity, the +confidentiality and the legitimacy of the transmitted data. ## Attack Vectors -Updates Over The Air are one of the most common points where an attacker -will penetrate. An OTA update mechanism is one of the highest threats in the system. +Updates Over The Air are one of the most common points where an attacker will +penetrate. An OTA update mechanism is one of the highest threats in the system. If an attacker is able to install his own application or firmware on the system, -he can get the same level of access that the original application or firmware had. -From that point, the intruder can get unfettered access to the rest of the system, -which might include making modifications, downloading other pieces of software, -and stealing assets. +he can get the same level of access that the original application or firmware +had. From that point, the intruder can get unfettered access to the rest of the +system, which might include making modifications, downloading other pieces of +software, and stealing assets. ### Man In The Middle (MITM) -The man-in-the-middle attack is the most classic example of an attack, where an adversary -inserts himself between two communicating entities and grabs whatever is being communicated. -In the case of OTA attacks, the connection in the network may be intercepted: +The man-in-the-middle attack is the most classic example of an attack, where an +adversary inserts himself between two communicating entities and grabs whatever +is being communicated. In the case of OTA attacks, the connection in the network +may be intercepted: * On the internet, before the cloud back-end. * At the base station, 3G,4G,5G connection to the internet. * At the receiving antenna, connection to the car. -* Between the receiving antenna and the gateway router (if present), connection within the car. -* Between the gateway router and the target component (IVI, In-Vehicle Infotainment unit). - -There are many ways to mount a MITM attack. For example, proxy tools like Burp Proxy can -be used to intercept web traffic as a man-in-the-middle. Under the guise of being a testing tool, -the proxy server is often used in attack scenarios. It runs on a variety of platforms. - -As another example, false base station attacks are known to be fairly easy to set-up. -The problem is apparently fairly prevalent in countries like China and in the UK. -These fake base stations are sometimes just eavesdropping on the communication, -but others have the potential to do serious harm. - -Defenses against MITM attacks include encrypted and signed data pipes. Furthermore, -architects and developers are also recommended to encrypt and sign the payloads that are -being passed over these pipes, to defend against perusal of the data. +* Between the receiving antenna and the gateway router (if present), connection + within the car. +* Between the gateway router and the target component (IVI, In-Vehicle + Infotainment unit). + +There are many ways to mount a MITM attack. For example, proxy tools like Burp +Proxy can be used to intercept web traffic as a man-in-the-middle. Under the +guise of being a testing tool, the proxy server is often used in attack +scenarios. It runs on a variety of platforms. + +As another example, false base station attacks are known to be fairly easy to +set-up. The problem is apparently fairly prevalent in countries like China and +in the UK. These fake base stations are sometimes just eavesdropping on the +communication, but others have the potential to do serious harm. + +Defenses against MITM attacks include encrypted and signed data pipes. +Furthermore, architects and developers are also recommended to encrypt and sign +the payloads that are being passed over these pipes, to defend against perusal +of the data. ### Man At The End (MATE) -The man-at-the-end attack is when an intruder analyzes the end-point of the communication when -software is accessing the data communication. This is a more severe attack type where the attacker can: +The man-at-the-end attack is when an intruder analyzes the end-point of the +communication when software is accessing the data communication. This is a more +severe attack type where the attacker can: * Steal keys. - * For example, a simple debugging session in running software could reveal a key used in memory. + * For example, a simple debugging session in running software could reveal a + key used in memory. * Tamper software. - * For example, replacing just one function call in software with a NOP (i.e. no operation) can drastically change the behavior of the program. + * For example, replacing just one function call in software with a NOP (i.e. + no operation) can drastically change the behavior of the program. * Jam branches of control. - * For example, making a program take one branch of control rather than the intended branch can mean the difference between an authorized and a non-authorized installation. + * For example, making a program take one branch of control rather than the + intended branch can mean the difference between an authorized and a + non-authorized installation. * Modify important data. - * For example, if the data changed is a key or data leading to a control path, then this attack can be severe. - * In the case of OTA updates, MATE attacks are particularly problematic for the system. One of the consequences of MATE attacks can be installed software that allows installation of any other software. For example, an attacker might install remote access software to control any part of the system. + * For example, if the data changed is a key or data leading to a control path, + then this attack can be severe. + * In the case of OTA updates, MATE attacks are particularly problematic for + the system. One of the consequences of MATE attacks can be installed + software that allows installation of any other software. For example, an + attacker might install remote access software to control any part of the + system. -------------------------------------------------------------------------------- diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.1_Firmware_Over_The_Air.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.1_Firmware_Over_The_Air.md index 0f7bed0..34761e3 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.1_Firmware_Over_The_Air.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.1_Firmware_Over_The_Air.md @@ -1,28 +1,26 @@ --- -edit_link: '' title: FOTA -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-8/1-FOTA.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Firmware Over The Air The firmware update is critical since its alteration back to compromise the -entire system. It is therefore necessary to take appropriate protective measures. - -AGL includes the _meta-updater_ Yocto layer that enables OTA software -updates via [Uptane](https://uptane.github.io), an automotive-specific extension -to [The Update Framework](https://theupdateframework.github.io/). Uptane and TUF -are open standards that define a secure protocol for delivering and verifying -updates even when the servers and network--internet and car-internal--aren't fully trusted. - -_meta-updater_ includes the application [`aktualizr`](https://github.com/advancedtelematic/aktualizr), -developed Advanced Telematic Systems (now part of HERE Technologies) that enables -OTA for an ECU. `aktualizr` combined with Uptane is suitable for updating the -firmware, software, and other packages on even functionally critical ECUs. -`aktualizr` can be enabled with the free, open souce backend +entire system. It is therefore necessary to take appropriate protective +measures. + +AGL includes the _meta-updater_ Yocto layer that enables OTA software updates +via [Uptane](https://uptane.github.io), an automotive-specific extension to [The +Update Framework](https://theupdateframework.github.io/). Uptane and TUF are +open standards that define a secure protocol for delivering and verifying +updates even when the servers and network--internet and car-internal--aren't +fully trusted. + +_meta-updater_ includes the application +[`aktualizr`](https://github.com/advancedtelematic/aktualizr), developed +Advanced Telematic Systems (now part of HERE Technologies) that enables OTA for +an ECU. `aktualizr` combined with Uptane is suitable for updating the firmware, +software, and other packages on even functionally critical ECUs. `aktualizr` can +be enabled with the free, open souce backend [`ota-community-edition`](https://github.com/advancedtelematic/ota-community-edition). This FOTA update mechanism can be enabled through the `agl-sota` feature. @@ -35,16 +33,17 @@ To build an AGL image that uses `aktualizr`, the following can be used. source meta-agl/scripts/aglsetup.sh -m <machine> agl-sota <other-features...> ``` -During the build, _meta-updater_ will use credentials downloaded from `ota-community-edition` -to sign metadata verifying the build as authentic. These signatures are part of the Uptane -framework and are used to verify FOTA updates. +During the build, _meta-updater_ will use credentials downloaded from +`ota-community-edition` to sign metadata verifying the build as authentic. These +signatures are part of the Uptane framework and are used to verify FOTA updates. ## Atomic Upgrades with Rollbacks -`aktualizr`'s primary method of updating firmware is to use `libostree` with binary diffs. -The binary diffs use the least amout of bandwidth, and by it's nature `libostree` stores -current and previous firmware versions on disk or in flash memory to allow for rollbacks. +`aktualizr`'s primary method of updating firmware is to use `libostree` with +binary diffs. The binary diffs use the least amout of bandwidth, and by it's +nature `libostree` stores current and previous firmware versions on disk or in +flash memory to allow for rollbacks. -`libostree` is a content addressable object store much like `git`. Versions are specified -via SHA2-256. These hashes are signed in the Uptane metadata and are robust against -cryptographic compromise. +`libostree` is a content addressable object store much like `git`. Versions are +specified via SHA2-256. These hashes are signed in the Uptane metadata and are +robust against cryptographic compromise. diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.2_Software_Over_The_Air.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.2_Software_Over_The_Air.md index 8004f52..bd4142f 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.2_Software_Over_The_Air.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/8_Update_(Over_The_Air)/1.2.8.2_Software_Over_The_Air.md @@ -1,21 +1,17 @@ --- -edit_link: '' title: SOTA -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-8/2-SOTA.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Software Over The Air Software updates in connected vehicles are a very useful feature, which can -deliver significant benefits. If not implemented with security in mind, -software updates can incur serious vulnerabilities. Any software update system -must ensure that not only are the software updates to devices done in a secure way, +deliver significant benefits. If not implemented with security in mind, software +updates can incur serious vulnerabilities. Any software update system must +ensure that not only are the software updates to devices done in a secure way, but also that the repositories and servers hosting these updates are adequately -protected. As the process of updating software migrates from a Dealership update model -towards an **OTA** update model, securing these processes becomes a high priority. +protected. As the process of updating software migrates from a Dealership update +model towards an **OTA** update model, securing these processes becomes a high +priority. **SOTA** is made possible by **AppFw** (See Platform part). It will be possible to manage in a simple way the packets (i.g. Android like). diff --git a/docs/2_Architecture_Guides/2.2_Security_Blueprint/9_Secure_development/1.2.9.0_Abstract.md b/docs/2_Architecture_Guides/2.2_Security_Blueprint/9_Secure_development/1.2.9.0_Abstract.md index ddc86a9..bfceefe 100644 --- a/docs/2_Architecture_Guides/2.2_Security_Blueprint/9_Secure_development/1.2.9.0_Abstract.md +++ b/docs/2_Architecture_Guides/2.2_Security_Blueprint/9_Secure_development/1.2.9.0_Abstract.md @@ -1,15 +1,11 @@ --- -edit_link: '' title: Introduction -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/security-blueprint/part-9/0_Abstract.md --- -<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/architecture/master/security_blueprint-security-blueprint-book.yml --> - # Part 9 - Secure development -In order to save a lot of time in code auditing, developers must follow coding guidelines. +In order to save a lot of time in code auditing, developers must follow coding +guidelines. ## Secure build @@ -18,7 +14,8 @@ In order to save a lot of time in code auditing, developers must follow coding g Tools like: - [Code optimisation](https://github.com/jduck/lk-reducer). -- [Kernel Drivers test](https://github.com/ucsb-seclab/dr_checker) with [docs](https://www.usenix.org/system/files/conference/usenixsecurity17/sec17-machiry.pdf). +- [Kernel Drivers test](https://github.com/ucsb-seclab/dr_checker) with + [docs](https://www.usenix.org/system/files/conference/usenixsecurity17/sec17-machiry.pdf). <!-- section-todo --> @@ -56,16 +53,20 @@ SecureDev-CodeAudit-2 | [OSSTMM](http://www.isecom.org/mirror/OSSTMM.3.pdf). ### SATS -- [RATS](https://github.com/andrew-d/rough-auditing-tool-for-security) (Maybe to old). +- [RATS](https://github.com/andrew-d/rough-auditing-tool-for-security) (Maybe to + old). - [Flaw Finder](https://www.dwheeler.com/flawfinder/). -- [wiki list](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis). +- [wiki + list](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis). -- [Mathematical approach](https://perso.univ-rennes1.fr/david.lubicz/planches/David_Pichardie.pdf). +- [Mathematical + approach](https://perso.univ-rennes1.fr/david.lubicz/planches/David_Pichardie.pdf). It is necessary to verify that the application code does not use functions that are depreciated and recognized as unsecured or cause problems. ### DATS -- [wiki list](https://en.wikipedia.org/wiki/Dynamic_program_analysis#Example_tools). +- [wiki + list](https://en.wikipedia.org/wiki/Dynamic_program_analysis#Example_tools). diff --git a/docs/3_Developer_Guides/1_AGL_Layers/1_Overview.md b/docs/3_Developer_Guides/1_AGL_Layers/1_Overview.md new file mode 100644 index 0000000..5df8217 --- /dev/null +++ b/docs/3_Developer_Guides/1_AGL_Layers/1_Overview.md @@ -0,0 +1,29 @@ +--- +title: Overview +--- + +Overview +======== + +The +[AGL Project](https://www.automotivelinux.org/) is an automotive-specific +development environment that provides a Linux distribution +[(AGL UCB](https://www.automotivelinux.org/software/unified-code-base)). + +AGL uses layers designed to be compatible with the +[Yocto Project](https://www.yoctoproject.org) and the +[OpenEmbedded Project (OE)](https://www.openembedded.org/wiki/Main_Page). + +This section provides information about the layers used by the AGL Project: + +* **`meta-agl`**: Minimal set of software needed to create an AGL distribution + used to boot a system. + AGL profiles are built on top of this minimal set of software. + +* **`meta-agl-demo`**: Provides a reference or demo platform and applications + for the AGL Distribution. + The reference UI is part of the `meta-agl-demo` layer. + +* **`meta-agl-devel`**: Contains components under development or being tested. + This layer also contains software packages that OEMs need but do not exist + in AGL. diff --git a/docs/3_Developer_Guides/1_AGL_Layers/2_meta-agl.md b/docs/3_Developer_Guides/1_AGL_Layers/2_meta-agl.md new file mode 100644 index 0000000..0a8ab83 --- /dev/null +++ b/docs/3_Developer_Guides/1_AGL_Layers/2_meta-agl.md @@ -0,0 +1,124 @@ +--- +title: meta-agl +--- + +## Introduction + +The `meta-agl` layer provides the minimal set of software +to boot an AGL Distribution system. +You use this layer as the minimal core on which to build AGL profiles. + +**NOTE:** The `meta-agl` layer does not include a reference UI. + The reference UI is included as part of the + [`meta-agl-demo`](./meta-agl-demo.html) layer. + Furthermore, `meta-agl` does not include additional components, such + as security, which are part of the + `meta-agl-extra` layer. + +## Sub-Layers + +The `meta-agl` layer itself contains many sub-layers and files. +Following is a "tree" look at the layer: + +``` +. +├── docs +├── meta-agl +├── meta-agl-bsp +├── meta-agl-distro +├── meta-agl-profile-cluster +├── meta-agl-profile-cluster-qt5 +├── meta-agl-profile-core +├── meta-agl-profile-graphical +├── meta-agl-profile-graphical-html5 +├── meta-agl-profile-graphical-qt5 +├── meta-agl-profile-hud +├── meta-agl-profile-telematics +├── meta-app-framework +├── meta-netboot +├── meta-security +├── README-AGL.md +├── README.md +├── scripts +├── templates +``` + +This list provides some overview information on the files and sub-layers +in `meta-agl`: + +* `docs`: Contains files that support AGL documentation. +* `meta-agl`: Contains layer configuration for the `meta-agl` layer. +* `meta-agl-bsp`: Contains adaptations for recipes and required packages + to boot an AGL distribution on targeted hardware and emulation (i.e. QEMU). +* `meta-agl-distro`: Contains distro configuration and supporting scripts. +* `meta-agl-profile-cluster`: The middleware for the AGL cluster profile. + The set of packages required for AGL Cluster Distribution. + Profiles include support for Wayland images. +* `meta-agl-profile-cluster-qt5`: The middleware for the AGL Qt5-based cluster profile. + The set of packages required for AGL Qt5-based Cluster Distribution. + Profiles include support for Wayland images with Qt5. +* `meta-agl-profile-core`: Configuration and recipes for the AGL core profiles. +* `meta-agl-profile-graphical`: Configuration and recipes supporting graphical user + interfaces. +* `meta-agl-profile-graphical-html5`: Configuration and recipes supporting profiles + with HTML user interface support. +* `meta-agl-profile-graphical-qt5`: Configuration and recipes supporting profiles + with Qt5-based user interface support. +* `meta-agl-profile-hud`: Configuration and recipes supporting profiles with + Head-Up-Display (HUD) support. +* `meta-agl-profile-telematics`: Configuration and recipes supporting profiles with + telematics support. +* `meta-app-framework`: Configuration and recipes supporting the AGL Application + Framework. +* `meta-netboot`: Contains recipes and configuration adjustments to allow network + boot through network block device (NBD) since network file system (NFS) does not + support security labels. +* `meta-security`: Configuration and recipes supporting security applications. +* `scripts`: AGL development setup and support scripts. +* `templates`: Base, feature, and machine templates used in the AGL development + environment. + +## Packagegroups + +This section describes the AGL +[packagegroup](https://yoctoproject.org/docs/ 3.1.2/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +design: + +* packagegroup-agl-image-minimal + + packagegroup-agl-core-automotive.bb + packagegroup-agl-core-connectivity.bb + packagegroup-agl-core-graphics.bb + packagegroup-agl-core-kernel.bb + packagegroup-agl-core-multimedia.bb + packagegroup-agl-core-navi-lbs.bb + packagegroup-agl-core-os-commonlibs.bb + packagegroup-agl-core-security.bb + packagegroup-agl-core-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-minimal` image, + which is a small image just capable of allowing a device to boot. + + Subsystem should maintain packagegroup-agl-core-[subsystem].bb which should + hold sufficient packages to build `agl-image-minimal`. + +* packagegroup-agl-image-ivi + + packagegroup-agl-ivi-automotive.bb + packagegroup-agl-ivi-connectivity.bb + packagegroup-agl-ivi-graphics.bb + packagegroup-agl-ivi-kernel.bb + packagegroup-agl-ivi-multimedia.bb + packagegroup-agl-ivi-navi-lbs.bb + packagegroup-agl-ivi-os-commonlibs.bb + packagegroup-agl-ivi-security.bb + packagegroup-agl-ivi-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-ivi` + image, which is a baseline image (i.e. Service Layer and Operating System + Layer defined in AGL Spec v1.0) for the AGL profiles. + +* packagegroup-agl-test.bb + + Additional tools used in QA tests (for agl-image*-qa). + diff --git a/docs/3_Developer_Guides/1_AGL_Layers/3_meta-agl-demo.md b/docs/3_Developer_Guides/1_AGL_Layers/3_meta-agl-demo.md new file mode 100644 index 0000000..df412ae --- /dev/null +++ b/docs/3_Developer_Guides/1_AGL_Layers/3_meta-agl-demo.md @@ -0,0 +1,166 @@ +--- +title: meta-agl-demo +--- + +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/meta-agl-demo-guides-devguides-book.yml --> + +## Introduction + +The `meta-agl-demo` layer is the reference user interface layer for the DEMO +platform of Automotive Grade Linux (AGL). +The layer provides a reference platform and applications. +The BitBake target name for the DEMO platform is `agl-demo-platform`, which is +the full DEMO platform image. + +## Layer Dependencies + +This section describes dependencies for the `meta-agl-demo` layer. +Dependencies are grouped into base, hardware, and feature dependencies. + +### Base Dependencies + +The `meta-agl-demo` layer has the following base dependencies: + +* Yocto Project Release: + + - URI: git://git.yoctoproject.org/poky + - Branch: "thud" + - Tested Revision: See the [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision + information.<br/><br/> + +* AGL `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl + - Branch: "master"<br/><br/> + +* OpenEmbedded `meta-openembedded` Layer: + + - Branch: "thud" + - Tested Revision: See the [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision + information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-oe` + - `meta-multimedia` + - `meta-networking` + - `meta-python`<br/><br/> + +* Yocto Project `meta-qt5` Layer from the + [OpenEmbedded Layer Index](https://layers.openembedded.org/layerindex/branch/master/layers/): + + - URI: https://github.com/meta-qt5/meta-qt5.git + - Branch: "thud" + - Tested Revision: See the [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision + information.<br/><br/> + +### Hardware Dependencies + +Aside from the previously listed base dependencies, if you are using a +[supported Renesas board](../getting_started/reference/getting-started/machines/renesas.html) +supported Renesas board, these dependencies exist: + +* AGL's `meta-renesas` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-renesas + +### Feature Dependencies + +The `meta-agl-demo` layer has the following AGL +[feature](../getting_started/reference/getting-started/image-workflow-initialize-build-environment.html#agl-features) +dependencies: + +* Yocto Project `meta-security` Layer: + + - URI: https://git.yoctoproject.org/cgit/cgit.cgi/meta-security + - Branch: "master" + - Tested Revision: See the [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision + information.<br/><br/> + +* AGL's `meta-app-framework` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master"<br/><br/> + +**The `agl-sota` Feature:** + +* Here Technologies' `meta-updater` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater/ + - Branch: "thud"<br/><br/> + +* Here Technologies' `meta-updater-qemux86-64` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater-qemux86-64/ + - Branch: "thud"<br/><br/> + +* OpenEmbedded's `meta-openembedded` Layer: + + - URI: https://github.com/openembedded/meta-openembedded + - Branch: "thud" + - Tested Revision: See the [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision + information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-filesystems` + - `meta-oe` + - `meta-python`<br/><br/> + +**The `agl-netboot` Feature:** + +* AGL's `meta-netboot` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master" + + +## Packagegroups + +AGL DEMO Platform's +[packagegroups](https://www.yoctoproject.org/docs/3.1.2/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +consist of the following: + +### packagegroup-agl-demo-platform + +This packagegroup is used for generating the `agl-demo-platform` image, +which is the full image for the AGL distributions IVI profile. +You can see the recipe (i.e. `agl-demo-platform.bb`) that installs +the `packagegroup-agl-demo-platform` packagegroup +[here](https://git.automotivelinux.org/AGL/meta-agl-demo/tree/recipes-platform/images/agl-demo-platform.bb). + +As meta-agl's design of packagegroups, the `agl-demo-platform.bb` recipe installs +only `packagegroup-agl-demo-platform` and the packages of the DEMO applications. + +``agl-demo-platform`` contains the following three packagegroups: + + * `packagegroup-agl-image-minimal` + * `packagegroup-agl-image-ivi` + * `packagegroup-agl-demo-platform` + +### packagegroup-agl-appfw* + +These packagegroups contain packages for the AGL distribution's +Application Framework. +Subsystem should maintain `packagegroup-agl-appfw-[subsystem].bb`, which +should hold sufficient packages for the Application Framework. + +Subsystems also can maintain their own packagegroups using appropriate +`recipes-*/`. +For example, Qt5 has two packagegroups in `meta-agl-demo`: +`packagegroup-agl-appfw-native-qt5` and `packagegroup-agl-demo-qt-examples`, +which are under `recipes-qt/`. + +The `packagegroup-agl-appfw-native-qt5` is included by +`packagegroup-agl-appfw-native` because Qt5 belongs to native application +framework of AGL Distro. + +Because the `packagegroup-agl-demo-qt-examples` is not mandatory for +the AGL Application Framework and the AGL DEMO, the packagegroup is added +to the layer's `local.conf` file only when needed. + diff --git a/docs/3_Developer_Guides/1_AGL_Layers/4_meta-agl-devel.md b/docs/3_Developer_Guides/1_AGL_Layers/4_meta-agl-devel.md new file mode 100644 index 0000000..859d958 --- /dev/null +++ b/docs/3_Developer_Guides/1_AGL_Layers/4_meta-agl-devel.md @@ -0,0 +1,145 @@ +--- +title: meta-agl-devel +--- + +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/meta-agl-devel-guides-devguides-book.yml --> + +## Introduction + +The `meta-agl-devel` layer contains components that are being tested or +still in development. +The layer also contains software packages that Original Equipment +Manufacturers (OEMs) need but are not included in the AGL software. + +## Sub-Layers + +The `meta-agl-devel` layer contains the following files and sub-layers: + +``` +. +├── meta-agl-telemetry +├── meta-audio-4a-framework +├── meta-audio-soundmanager-framework +├── meta-egvirt +├── meta-gstrecorder-rcar-gen3 +├── meta-hmi-framework +├── meta-oem-extra-libs +├── README.md +├── templates +``` + +The following list provides a summary of these sub-layers: + +* `meta-agl-telemetry`: Provides the smallest AGL image. + The image is designed to be used when a device requires restricted + scope of responsibilites (e.g. collecting vehicle telemetry). + +* `meta-audio-4a-framework`: A collection of recipes used for the + first integration of 4A (i.e. Advanced AGL Audio Architecture). + +* `meta-pipewire`: A collection of recipes used for the integration + of the pipewire sound system. + +* `meta-audio-soundmanager-framework`: Supports the Soundmanager + Audio Framework features, which maps to the `agl-audio-soundmanager-framework` + AGL feature. + +* `meta-egvirt`: The AGL Virtualization Expert Group (EG-VIRT) layer. + This layer supports the design, test, implementation, and assessment + of virtualization technologies (e.g. containers, hypervisors, system + partitioners, and so forth) aimed at AGL ARMv8 and Intel platforms. + +* `meta-gstrecorder-rcar-gen3`: Supports streaming audio and video for + the Pro and Premier board kits (e.g. + [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) + and + [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK)). + +* `meta-hmi-framework`: Provides AGL's Human Machine Interface (HMI) framework + through resource management consisting of sounds, windows, and input control. + For more information, see the + [HMI-Framework Page](https://wiki.automotivelinux.org/hmiframework) of the + AGL Wiki. + +* `meta-oem-extra-libs`: Provides libraries and software packages needed by + OEMs but not provided by the AGL software. + +* `templates`: Feature templates that support the `meta-agl-devel` layer. + +## Additional Sub-Layer Information + +This section provides additional information for the `meta-egvirt`, +`meta-oem-extra-libs`, and `meta-hmi-framework` layers. + +### Virtualization Support + +The `meta-egvirt` layer enables virtualization support in AGL. +The AGL Virtualization Expert (EG-VIRT) group is responsible +for design and implementation of AGL virtualization solutions +(.e.g the Virtualization platform architecture of AGL). +You can read about EG-VERT's efforts on the +"[Virtualization Expert Group's](https://wiki.automotivelinux.org/eg-virt)" +page of the AGL wiki. + +Additionally, you can learn more about virtualization as it applies to AGL +by reading +"[The Automotive Grade Linux Software Defined Connected Car Architecture](https://www.automotivelinux.org/wp-content/uploads/sites/4/2018/06/agl_software_defined_car_jun18.pdf)" +whitepaper. + +### OEM Extra Libraries + +The `meta-oem-extra-libs` layer provides additional software packages many OEMs need +but are not part of the AGL source. +Following is the list of packages this layer provides: + + * boost + * fixesproto + * imagemagick + * iptables + * Xorg-macros + * zlib + * eglibc = glibc + * libcurl + * libgif + * libneon + * mongoose + * fuse + * protocol buffers + * bsdiff + * module-init-tools + * libcroco + * libtiff + * librsvg + * libpcap + +To add these packages to your library, you need to include the +`agl-oem-extra-libs` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../getting_started/reference/getting-started/image-workflow-initialize-build-environment.html)" +section. + +Once you have included the AGL feature, you can build your image. + +### HMI Framework + +The `meta-hmi-framework` layer supports the Human-Machine Interface (HMI) Framework. +The HMI-Framework is the User Interface (UI) to control the Infotainment System. +Work continues to close the gap between the user experience of a smart phone +and the Infotainment System in a vehicle, for example. + +You can find more out about HMI Framework progress on the +"[HMI Framework](https://wiki.automotivelinux.org/hmiframework)" page on the AGL Wiki. + +To add HMI Framework support to your image, you need to include the +`hmi-framework` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../getting_started/reference/getting-started/image-workflow-initialize-build-environment.html)" +section. + +Once you have included the AGL feature, you can build your image. diff --git a/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md index 83a974d..c4d8b08 100644 --- a/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md +++ b/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md @@ -84,8 +84,8 @@ details on how to do that. Once you have generated non-default keys, you need to configure SSH to use the correct key for Gerrit. In that case, you need to create a ``~/.ssh/config`` file modeled after the one below. - ```sh -host gerrit.automotivelinux.org + ```sh +host gerrit.automotivelinux.org HostName gerrit.automotivelinux.org IdentityFile ~/.ssh/id_rsa_automotivelinux_gerrit User <LFID> diff --git a/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md index 32475aa..49b443d 100644 --- a/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md +++ b/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md @@ -2,20 +2,18 @@ title: Using Jira for current work items --- -This document has been created to give further insight into the work in -progress towards the Automotive Grade Linux architecture based on the -community roadmap. The requirements for the roadmap are being tracked in +This document has been created to give further insight into the work in progress +towards the Automotive Grade Linux architecture based on the community roadmap. +The requirements for the roadmap are being tracked in [Jira](https://jira.automotivelinux.org/). -On this page you will see all the public (and restricted) boards that -have been created. For example the **Board Name** *CI and Automated Test -Expert Group*: +On this page you will see all the public (and restricted) boards that have been +created. For example the **Board Name** *CI and Automated Test Expert Group*:  -When you click on *CI and Automated Test Expert Group* under **Board -name** you will be directed to a page that contains the following -columns: +When you click on *CI and Automated Test Expert Group* under **Board name** you +will be directed to a page that contains the following columns:  @@ -23,11 +21,10 @@ The meanings to these columns are as follows: - **NOT STARTED** – list of items slated for the current sprint (sprints are defined in 2 week iterations), but are not currently in progress -- **IN PROGRESS** – items currently being worked by someone in the - community. +- **IN PROGRESS** – items currently being worked by someone in the community. - **DONE** – items merged and complete in the sprint. -If there is an item you are interested in working on, want more -information or have questions, or if there is an item that you feel needs -to be in higher priority, please add comments directly to the Jira item. -All feedback and help is very much appreciated.
\ No newline at end of file +If there is an item you are interested in working on, want more information or +have questions, or if there is an item that you feel needs to be in higher +priority, please add comments directly to the Jira item. All feedback and help +is very much appreciated.
\ No newline at end of file diff --git a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md index 8bba660..44da2d9 100644 --- a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md +++ b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md @@ -2,40 +2,41 @@ title: Working with Gerrit --- -Follow these instructions to collaborate on AGL through the Gerrit review system. +Follow these instructions to collaborate on AGL through the Gerrit review +system. Please be sure that you are subscribed to the [mailing -list](https://lists.automotivelinux.org/g/agl-dev-community) and of -course, you can reach out on IRC at the #automotive channel on -Freenode.net +list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you +can reach out on IRC at the #automotive channel on Freenode.net Gerrit assigns the following roles to users: -- **Submitters**: May submit changes for consideration, review other - code changes, and make recommendations for acceptance or rejection by - voting +1 or -1, respectively. -- **Maintainers**: May approve or reject changes based upon feedback - from reviewers voting +2 or -2, respectively. +- **Submitters**: May submit changes for consideration, review other code + changes, and make recommendations for acceptance or rejection by voting +1 or + -1, respectively. +- **Maintainers**: May approve or reject changes based upon feedback from + reviewers voting +2 or -2, respectively. ## Getting deeper into Gerrit -A comprehensive walk-through of Gerrit is beyond the scope of this -document. There are plenty of resources available on the Internet. A good -summary can be found -[here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and -[Basic Gerrit Walkthrough for GitHub Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). +A comprehensive walk-through of Gerrit is beyond the scope of this document. +There are plenty of resources available on the Internet. A good summary can be +found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and [Basic Gerrit +Walkthrough for GitHub +Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). ## Working with a local clone of the repository To work on something, whether a new feature or a bugfix: -1. Open the Gerrit [repo page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). +1. Open the Gerrit [repo + page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). 2. Select the repository you wish to work on. -3. Open a terminal window and clone the project locally using the - ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected, - as this will make authentication much simpler. For example, for `documentation` repository: +3. Open a terminal window and clone the project locally using the ``Clone with + git hook`` URL. Be sure that ``ssh`` is also selected, as this will make + authentication much simpler. For example, for `documentation` repository: ```sh $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P @@ -66,14 +67,18 @@ To work on something, whether a new feature or a bugfix: ## Using git review -There's a **very** useful tool for working with Gerrit called [git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This command-line tool can automate most of the ensuing sections for you. Ofcourse, reading the information below is also highly recommended so that you understand what's going on behind the scenes. +There's a **very** useful tool for working with Gerrit called +[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This +command-line tool can automate most of the ensuing sections for you. Ofcourse, +reading the information below is also highly recommended so that you understand +what's going on behind the scenes. ```sh # for first time use only $ git review -s ``` -If `.gitreview` is missing, add the following section to ``.git/config``, and replace ``<LFID>`` -with your LFID id. +If `.gitreview` is missing, add the following section to ``.git/config``, and +replace ``<LFID>`` with your LFID id. ```sh [remote "gerrit"] @@ -88,8 +93,8 @@ $ cd documentation $ git review ``` -When you update your patch, you can commit with ``git commit --amend``, -and then repeat the ``git review`` command. +When you update your patch, you can commit with ``git commit --amend``, and then +repeat the ``git review`` command. ## Typical Review Workflow @@ -119,30 +124,30 @@ and then repeat the ``git review`` command. ## Reviewing Using Gerrit -- **Add**: This button allows the change submitter to manually add - names of people who should review a change; start typing a name and - the system will auto-complete based on the list of people registered - and with access to the system. They will be notified by email that - you are requesting their input. +- **Add**: This button allows the change submitter to manually add names of + people who should review a change; start typing a name and the system will + auto-complete based on the list of people registered and with access to the + system. They will be notified by email that you are requesting their input. -- **Abandon**: This button is available to the submitter only; it - allows a committer to abandon a change and remove it from the merge - queue. +- **Abandon**: This button is available to the submitter only; it allows a + committer to abandon a change and remove it from the merge queue. -- **Change-ID**: This ID is generated by Gerrit (or system). It becomes - useful when the review process determines that your commit(s) have to - be amended. You may submit a new version; and if the same Change-ID - header (and value) are present, Gerrit will remember it and present - it as another version of the same change. +- **Change-ID**: This ID is generated by Gerrit (or system). It becomes useful + when the review process determines that your commit(s) have to be amended. + You may submit a new version; and if the same Change-ID header (and value) + are present, Gerrit will remember it and present it as another version of the + same change. -- **Status**: Currently, the example change is in review status, as - indicated by “Needs Verified” in the upper-left corner. The list of - Reviewers will all emit their opinion, voting +1 if they agree to the - merge, -1 if they disagree. Gerrit users with a Maintainer role can - agree to the merge or refuse it by voting +2 or -2 respectively. +- **Status**: Currently, the example change is in review status, as indicated + by “Needs Verified” in the upper-left corner. The list of Reviewers will all + emit their opinion, voting +1 if they agree to the merge, -1 if they + disagree. Gerrit users with a Maintainer role can agree to the merge or + refuse it by voting +2 or -2 respectively. Notifications are sent to the email address in your commit message's -Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), -to check the progress of your requests. +Signed-off-by line. Visit your [Gerrit +dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), to check +the progress of your requests. -The history tab in Gerrit will show you the in-line comments and the author of the review. +The history tab in Gerrit will show you the in-line comments and the author of +the review. diff --git a/docs/5_How_To_Contribute/4_Submitting_Changes.md b/docs/5_How_To_Contribute/4_Submitting_Changes.md index 36e21f4..d226450 100644 --- a/docs/5_How_To_Contribute/4_Submitting_Changes.md +++ b/docs/5_How_To_Contribute/4_Submitting_Changes.md @@ -2,41 +2,40 @@ title: Submitting Changes --- -Carefully review the following before submitting a change. These -guidelines apply to developers that are new to open source, as well as -to experienced open source developers. +Carefully review the following before submitting a change. These guidelines +apply to developers that are new to open source, as well as to experienced open +source developers. ## Change Requirements -This section contains guidelines for submitting code changes for review. -For more information on how to submit a change using Gerrit, please see -[Working with Gerrit](./3_Working_with_Gerrit.md). +This section contains guidelines for submitting code changes for review. For +more information on how to submit a change using Gerrit, please see [Working +with Gerrit](./3_Working_with_Gerrit.md). Changes are submitted as Git commits. Each commit must contain: -- a short and descriptive subject line that is 72 characters or fewer, - followed by a blank line. -- a change description with your logic or reasoning for the changes, - followed by a blank line +- a short and descriptive subject line that is 72 characters or fewer, followed + by a blank line. +- a change description with your logic or reasoning for the changes, followed + by a blank line - a Signed-off-by line, followed by a colon (Signed-off-by:) -- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit - won't accept patches without this identifier. +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't + accept patches without this identifier. -A commit with the above details is considered well-formed. -[This page](https://chris.beams.io/posts/git-commit/) is a very useful for the -same. +A commit with the above details is considered well-formed. [This +page](https://chris.beams.io/posts/git-commit/) is a very useful for the same. -All changes and topics sent to Gerrit must be well-formed. -Informationally, ``commit messages`` must include: +All changes and topics sent to Gerrit must be well-formed. Informationally, +``commit messages`` must include: - **what** the change does, - **why** you chose that approach, and - **how** you know it works -- for example, which tests you ran. -For example: One commit fixes whitespace issues, another renames a -function and a third one changes the code's functionality. An example -commit file is illustrated below in detail: +For example: One commit fixes whitespace issues, another renames a function and +a third one changes the code's functionality. An example commit file is +illustrated below in detail: ```sh @@ -51,8 +50,8 @@ Signed-off-by: Your Name <commit-sender@email.address> ``` Include the issue ID in the one line description of your commit message for -readability. Gerrit will link issue IDs automatically to the corresponding -entry in Jira. +readability. Gerrit will link issue IDs automatically to the corresponding entry +in Jira. Each commit must also contain the following line at the bottom of the commit message: @@ -65,5 +64,5 @@ The name in the Signed-off-by line and your email must match the change authorship information. Make sure your :file:``.git/config`` is set up correctly. Always submit the full set of changes via Gerrit. -When a change is included in the set to enable other changes, but it -will not be part of the final set, please let the reviewers know this. +When a change is included in the set to enable other changes, but it will not be +part of the final set, please let the reviewers know this. diff --git a/docs/5_How_To_Contribute/5_Reviewing_Changes.md b/docs/5_How_To_Contribute/5_Reviewing_Changes.md index 14c18bf..e9d6758 100644 --- a/docs/5_How_To_Contribute/5_Reviewing_Changes.md +++ b/docs/5_How_To_Contribute/5_Reviewing_Changes.md @@ -14,8 +14,8 @@ title: Reviewing Changes message and a score, -1, 0 or +1. - **Patch Sets:** If multiple revisions of a patch exist, this button - enables navigation among revisions to see the changes. By default, - the most recent revision is presented. + enables navigation among revisions to see the changes. By default, the + most recent revision is presented. - **Download:** This button brings up another window with multiple options to download or checkout the current changeset. The button on @@ -25,16 +25,15 @@ title: Reviewing Changes Underneath the commit information, the files that have been changed by this patch are displayed. -3. Click on a filename to review it. Select the code base to - differentiate against. The default is ``Base`` and it will generally - be what is needed. +3. Click on a filename to review it. Select the code base to differentiate + against. The default is ``Base`` and it will generally be what is needed. -4. The review page presents the changes made to the file. At the top of - the review, the presentation shows some general navigation options. - Navigate through the patch set using the arrows on the top right - corner. It is possible to go to the previous or next file in the set - or to return to the main change screen. Click on the yellow sticky - pad to add comments to the whole file. +4. The review page presents the changes made to the file. At the top of the + review, the presentation shows some general navigation options. Navigate + through the patch set using the arrows on the top right corner. It is + possible to go to the previous or next file in the set or to return to the + main change screen. Click on the yellow sticky pad to add comments to the + whole file. The focus of the page is on the comparison window. The changes made are presented in green on the right versus the base version on the left. @@ -44,13 +43,13 @@ title: Reviewing Changes 5. After adding the comment, it is saved as a *Draft*. -6. Once you have reviewed all files and provided feedback, click the - *green up arrow* at the top right to return to the main change page. - Click the ``Reply`` button, write some final comments, and submit - your score for the patch set. Click ``Post`` to submit the review of - each reviewed file, as well as your final comment and score. Gerrit - sends an email to the change-submitter and all listed reviewers. - Finally, it logs the review for future reference. All individual - comments are saved as *Draft* until the ``Post`` button is clicked. +6. Once you have reviewed all files and provided feedback, click the *green up + arrow* at the top right to return to the main change page. Click the + ``Reply`` button, write some final comments, and submit your score for the + patch set. Click ``Post`` to submit the review of each reviewed file, as well + as your final comment and score. Gerrit sends an email to the + change-submitter and all listed reviewers. Finally, it logs the review for + future reference. All individual comments are saved as *Draft* until the + ``Post`` button is clicked. diff --git a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md index 42f39f4..671c685 100644 --- a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md +++ b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md @@ -3,23 +3,21 @@ title: Gerrit Recommended Practices --- This document presents some best practices to help you use Gerrit more -effectively. The intent is to show how content can be submitted easily. -Use the recommended practices to reduce your troubleshooting time and -improve participation in the community. +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. ## Commit Messages -Gerrit follows the Git commit message format. Ensure the headers are at -the bottom and don't contain blank lines between one another. The -following example shows the format and content expected in a commit -message: +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: Brief (no more than 50 chars) one line description. -Elaborate summary of the changes made referencing why (motivation), what -was changed and how it was tested. Note also any changes to -documentation made to remain consistent with the code changes, wrapping -text at 72 chars/line. +Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. ```sh Bug-AGL: SPEC-<JIRA-ID> @@ -28,52 +26,50 @@ Change-Id: LONGHEXHASH Signed-off-by: Your Name your.email\@example.org ``` -The Gerrit server provides a precommit hook to autogenerate the -Change-Id which is one time use. +The Gerrit server provides a precommit hook to autogenerate the Change-Id which +is one time use. -**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/). +**Recommended reading:** [How to Write a Git Commit +Message](http://chris.beams.io/posts/git-commit/). ## Avoid Pushing Untested Work to a Gerrit Server To avoid pushing untested work to Gerrit. -Check your work at least three times before pushing your change to -Gerrit. Be mindful of what information you are publishing. +Check your work at least three times before pushing your change to Gerrit. Be +mindful of what information you are publishing. ## Keeping Track of Changes - Set Gerrit to send you emails: - Gerrit will add you to the email distribution list for a change if a - developer adds you as a reviewer, or if you comment on a specific - Patch Set. + developer adds you as a reviewer, or if you comment on a specific Patch Set. -- Opening a change in Gerrit's review interface is a quick way to - follow that change. +- Opening a change in Gerrit's review interface is a quick way to follow that + change. -- Watch projects in the Gerrit projects section at ``Gerrit``, select - at least *New Changes, New Patch Sets, All Comments* and *Submitted - Changes*. +- Watch projects in the Gerrit projects section at ``Gerrit``, select at least + *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. -Always track the projects you are working on; also see the -feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community) -to learn and help others ramp up. +Always track the projects you are working on; also see the feedback/comments +[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn +and help others ramp up. ## Topic branches Topic branches are temporary branches that you push to commit a set of logically-grouped dependent commits: -To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed -as a topic in **TopicName** use the following command as an example: +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a +topic in **TopicName** use the following command as an example: ```sh $ git push REMOTE HEAD:refs/for/master/TopicName ``` -The topic will show up in the review ``UI`` and in the -``Open Changes List``. Topic branches will disappear from the master -tree when its content is merged. +The topic will show up in the review ``UI`` and in the ``Open Changes List``. +Topic branches will disappear from the master tree when its content is merged. ## Finding Available Topics @@ -81,43 +77,40 @@ tree when its content is merged. $ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u ``` -- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted. -- *status* : Indicates the topic's current status: open , merged, - abandoned, draft, merge conflict. -- *project* : Refers to the current name of the project, in this case - fabric. +- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the + current URL where the project is hosted. +- *status* : Indicates the topic's current status: open , merged, abandoned, + draft, merge conflict. +- *project* : Refers to the current name of the project, in this case fabric. - *branch* : The topic is searched at this branch. -- *topic* : The name of an specific topic, leave it blank to include them - all. +- *topic* : The name of an specific topic, leave it blank to include them all. - *sort* : Sorts the found topics, in this case by update (-u). ## Downloading or Checking Out a Change -In the review UI, on the top right corner, the **Download** link -provides a list of commands and hyperlinks to checkout or download diffs -or files. +In the review UI, on the top right corner, the **Download** link provides a list +of commands and hyperlinks to checkout or download diffs or files. -We recommend the use of the *git review* plugin. The steps to install -git review are beyond the scope of this document. Refer to the -[git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) +We recommend the use of the *git review* plugin. The steps to install git review +are beyond the scope of this document. Refer to the [git review +documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) for the installation process. -To check out a specific change using Git, the following command usually -works: +To check out a specific change using Git, the following command usually works: ```sh $ git review -d CHANGEID ``` -If you don't have Git-review installed, the following commands will do -the same thing: +If you don't have Git-review installed, the following commands will do the same +thing: ```sh $ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD ``` -For example, for the 4th version of change 2464, NN is the first two -digits (24): +For example, for the 4th version of change 2464, NN is the first two digits +(24): ```sh $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD @@ -125,8 +118,8 @@ $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD ## Using Sandbox Branches -You can create your own branches to develop features. The branches are -pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. +You can create your own branches to develop features. The branches are pushed to +the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. These commands ensure the branch is created in Gerrit's server. @@ -157,13 +150,12 @@ $ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME ## Updating the Version of a Change -During the review process, you might be asked to update your change. It -is possible to submit multiple versions of the same change. Each version -of the change is called a patch set. +During the review process, you might be asked to update your change. It is +possible to submit multiple versions of the same change. Each version of the +change is called a patch set. -Always maintain the **Change-Id** that was assigned. For example, there -is a list of commits, **c0...c7**, which were submitted as a topic -branch: +Always maintain the **Change-Id** that was assigned. For example, there is a +list of commits, **c0...c7**, which were submitted as a topic branch: ```sh @@ -176,26 +168,26 @@ $ git log REMOTE/master..master $ git push REMOTE HEAD:refs/for/master/SOMETOPIC ``` -After you get reviewers' feedback, there are changes in **c3** and -**c4** that must be fixed. If the fix requires rebasing, rebasing -changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id -and push the changes again: +After you get reviewers' feedback, there are changes in **c3** and **c4** that +must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, +see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section +for more information. However, you must keep the same Change-Id and push the +changes again: ```sh $ git push REMOTE HEAD:refs/for/master/SOMETOPIC ``` -This new push creates a patches revision, your local history is then -cleared. However you can still access the history of your changes in -Gerrit on the ``review UI`` section, for each change. +This new push creates a patches revision, your local history is then cleared. +However you can still access the history of your changes in Gerrit on the +``review UI`` section, for each change. It is also permitted to add more commits when pushing new versions. ### Rebasing -Rebasing is usually the last step before pushing changes to Gerrit; this -allows you to make the necessary *Change-Ids*. The *Change-Ids* must be -kept the same. +Rebasing is usually the last step before pushing changes to Gerrit; this allows +you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. - **squash:** mixes two or more commits into a single one. - **reword:** changes the commit message. @@ -208,8 +200,8 @@ kept the same. Before pushing a rebase to your master, ensure that the history has a consecutive order. -For example, your ``REMOTE/master`` has the list of commits from **a0** -to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus: +For example, your ``REMOTE/master`` has the list of commits from **a0** to +**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: ```sh $ git log --oneline REMOTE/master..master @@ -225,8 +217,8 @@ $ git log --oneline REMOTE/master..master c7 ``` -If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull -with a rebase as follows: +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: ```sh $ git pull --rebase REMOTE master @@ -247,8 +239,8 @@ c7 ## Getting Better Logs from Git -Use these commands to change the configuration of Git in order to -produce better logs: +Use these commands to change the configuration of Git in order to produce better +logs: ```sh $ git config log.abbrevCommit true @@ -260,12 +252,12 @@ The command above sets the log to abbreviate the commits' hash. $ git config log.abbrev 5 ``` -The command above sets the abbreviation length to the last 5 characters -of the hash. +The command above sets the abbreviation length to the last 5 characters of the +hash. ```sh $ git config format.pretty oneline ``` -The command above avoids the insertion of an unnecessary line before the -Author line. +The command above avoids the insertion of an unnecessary line before the Author +line. diff --git a/docs/5_How_To_Contribute/7_General_Guidelines.md b/docs/5_How_To_Contribute/7_General_Guidelines.md index cc0ece5..1cb7d69 100644 --- a/docs/5_How_To_Contribute/7_General_Guidelines.md +++ b/docs/5_How_To_Contribute/7_General_Guidelines.md @@ -4,30 +4,28 @@ title: General Guidelines ## Getting help -If you are looking for something to work on, or need some expert -assistance in debugging a problem or working out a fix to an issue, our -community is always eager to help. We hang out on various -[developer meetings](https://www.automotivelinux.org/developer-meetings/), -IRC (#automotive on freenode.net) and the -[mailing lists](https://lists.automotivelinux.org/g/agl-dev-community). -We will be glad to help. The only silly question is the one you don't ask. -Questions are in fact a great way to help improve the project as they highlight -where our documentation could be clearer. +If you are looking for something to work on, or need some expert assistance in +debugging a problem or working out a fix to an issue, our community is always +eager to help. We hang out on various [developer +meetings](https://www.automotivelinux.org/developer-meetings/), IRC (#automotive +on freenode.net) and the [mailing +lists](https://lists.automotivelinux.org/g/agl-dev-community). We will be glad +to help. The only silly question is the one you don't ask. Questions are in fact +a great way to help improve the project as they highlight where our +documentation could be clearer. ## Reporting bugs If you are a user and you have found a bug, please submit an issue using -[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA -issue, please try to search the existing items to be sure no one else has -previously reported it. If it has been previously reported, then you -might add a comment that you also are interested in seeing the defect -fixed. - -If it has not been previously reported, create a new JIRA. Please try to -provide sufficient information for someone else to reproduce the issue. -One of the project's maintainers should respond to your issue within 24 -hours. If not, please bump the issue with a comment and request that it -be reviewed. +[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA issue, +please try to search the existing items to be sure no one else has previously +reported it. If it has been previously reported, then you might add a comment +that you also are interested in seeing the defect fixed. + +If it has not been previously reported, create a new JIRA. Please try to provide +sufficient information for someone else to reproduce the issue. One of the +project's maintainers should respond to your issue within 24 hours. If not, +please bump the issue with a comment and request that it be reviewed. ## Submitting your fix @@ -35,111 +33,106 @@ If you just submitted a JIRA for a bug you've discovered, and would like to provide a fix, we would welcome that gladly! Please assign the JIRA issue to yourself, then you can submit a change request (CR). -**NOTE:** If you need help with submitting your first CR, we have created -a brief [tutorial](./4_Submitting_Changes.md) for you. +**NOTE:** If you need help with submitting your first CR, we have created a +brief [tutorial](./4_Submitting_Changes.md) for you. ## Fixing issues and working stories -Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) and find -something that interests you. It is wise to start with something -relatively straight forward and achievable, and that no one is already -assigned. If no one is assigned, then assign the issue to yourself. -Please be considerate and rescind the assignment if you cannot finish in -a reasonable time, or add a comment saying that you are still actively -working the issue if you need a little more time. +Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) +and find something that interests you. It is wise to start with something +relatively straight forward and achievable, and that no one is already assigned. +If no one is assigned, then assign the issue to yourself. Please be considerate +and rescind the assignment if you cannot finish in a reasonable time, or add a +comment saying that you are still actively working the issue if you need a +little more time. ## Reviewing submitted Change Requests (CRs) Another way to contribute and learn about Automotive Grade Linux is to help the -maintainers with the review of the CRs that are open. Indeed -maintainers have the difficult role of having to review all the CRs -that are being submitted and evaluate whether they should be merged or -not. You can review the code and/or documentation changes, test the -changes, and tell the submitters and maintainers what you think. Once -your review and/or test is complete just reply to the CR with your -findings, by adding comments and/or voting. A comment saying something -like "I tried it on system X and it works" or possibly "I got an error -on system X: xxx " will help the maintainers in their evaluation. As a -result, maintainers will be able to process CRs faster and everybody -will gain from it. - -Just browse through the [open CRs on Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started. +maintainers with the review of the CRs that are open. Indeed maintainers have +the difficult role of having to review all the CRs that are being submitted and +evaluate whether they should be merged or not. You can review the code and/or +documentation changes, test the changes, and tell the submitters and maintainers +what you think. Once your review and/or test is complete just reply to the CR +with your findings, by adding comments and/or voting. A comment saying something +like "I tried it on system X and it works" or possibly "I got an error on system +X: xxx " will help the maintainers in their evaluation. As a result, maintainers +will be able to process CRs faster and everybody will gain from it. + +Just browse through the [open CRs on +Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started. ## Making Feature/Enhancement Proposals -Review [JIRA](https://jira.automotivelinux.org/) to be sure that there -isn't already an open (or recently closed) proposal for the same -function. If there isn't, to make a proposal we recommend that you open a -JIRA Epic, Story or Improvement, whichever seems to best fit the -circumstance and link or inline a "one pager" of the proposal that states -what the feature would do and, if possible, how it might be implemented. -It would help also to make a case for why the feature should be added, -such as identifying specific use case(s) for which the feature is needed -and a case for what the benefit would be should the feature be -implemented. Once the JIRA issue is created, and the "one pager" either -attached, inlined in the description field, or a link to a publicly -accessible document is added to the description, send an introductory -email to the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) mailing -list linking the JIRA issue, and soliciting feedback. - -Discussion of the proposed feature should be conducted in the JIRA issue -itself, so that we have a consistent pattern within our community as to -where to find design discussion. - -Getting the support of three or more of the AGL maintainers for the new -feature will greatly enhance the probability that the feature's related -CRs will be merged. +Review [JIRA](https://jira.automotivelinux.org/) to be sure that there isn't +already an open (or recently closed) proposal for the same function. If there +isn't, to make a proposal we recommend that you open a JIRA Epic, Story or +Improvement, whichever seems to best fit the circumstance and link or inline a +"one pager" of the proposal that states what the feature would do and, if +possible, how it might be implemented. It would help also to make a case for why +the feature should be added, such as identifying specific use case(s) for which +the feature is needed and a case for what the benefit would be should the +feature be implemented. Once the JIRA issue is created, and the "one pager" +either attached, inlined in the description field, or a link to a publicly +accessible document is added to the description, send an introductory email to +the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) +mailing list linking the JIRA issue, and soliciting feedback. + +Discussion of the proposed feature should be conducted in the JIRA issue itself, +so that we have a consistent pattern within our community as to where to find +design discussion. + +Getting the support of three or more of the AGL maintainers for the new feature +will greatly enhance the probability that the feature's related CRs will be +merged. ## What makes a good change request? -- One change at a time. Not five, not three, not ten. One and only one. - Why? Because it limits the blast area of the change. If we have a - regression, it is much easier to identify the culprit commit than if - we have some composite change that impacts more of the code. - -- Include a link to the JIRA story for the change. Why? Because a) we - want to track our velocity to better judge what we think we can - deliver and when and b) because we can justify the change more - effectively. In many cases, there should be some discussion around a - proposed change and we want to link back to that from the change - itself. - -- Include unit and integration tests (or changes to existing tests) - with every change. This does not mean just happy path testing, - either. It also means negative testing of any defensive code that it - correctly catches input errors. When you write code, you are - responsible to test it and provide the tests that demonstrate that - your change does what it claims. Why? Because without this we have no - clue whether our current code base actually works. - -- Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 -LOC change, how long do you think it takes to review all of that code? -Keep your changes to < 200-300 LOC, if possible. If you have a larger -change, decompose it into multiple independent changess. If you are -adding a bunch of new functions to fulfill the requirements of a new -capability, add them separately with their tests, and then write the code -that uses them to deliver the capability. Of course, there are always -exceptions. If you add a small change and then add 300 LOC of tests, you -will be forgiven;-) If you need to make a change that has broad impact or -a bunch of generated code (protobufs, etc.). Again, there can be -exceptions. - - **NOTE:** Large change requests, e.g. those with more than 300 LOC - are more likely than not going to receive a -2, and you'll be asked - to refactor the change to conform with this guidance. - -- Do not stack change requests (e.g. submit a CR from the same local branch - as your previous CR) unless they are related. This will minimize merge - conflicts and allow changes to be merged more quickly. If you stack requests - your subsequent requests may be held up because of review comments in the +- One change at a time. Not five, not three, not ten. One and only one. Why? + Because it limits the blast area of the change. If we have a regression, it + is much easier to identify the culprit commit than if we have some composite + change that impacts more of the code. + +- Include a link to the JIRA story for the change. Why? Because a) we want to + track our velocity to better judge what we think we can deliver and when and + b) because we can justify the change more effectively. In many cases, there + should be some discussion around a proposed change and we want to link back + to that from the change itself. + +- Include unit and integration tests (or changes to existing tests) with every + change. This does not mean just happy path testing, either. It also means + negative testing of any defensive code that it correctly catches input + errors. When you write code, you are responsible to test it and provide the + tests that demonstrate that your change does what it claims. Why? Because + without this we have no clue whether our current code base actually works. + +- Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 LOC + change, how long do you think it takes to review all of that code? Keep your + changes to < 200-300 LOC, if possible. If you have a larger change, decompose + it into multiple independent changess. If you are adding a bunch of new + functions to fulfill the requirements of a new capability, add them + separately with their tests, and then write the code that uses them to + deliver the capability. Of course, there are always exceptions. If you add a + small change and then add 300 LOC of tests, you will be forgiven;-) If you + need to make a change that has broad impact or a bunch of generated code + (protobufs, etc.). Again, there can be exceptions. + + **NOTE:** Large change requests, e.g. those with more than 300 LOC are + more likely than not going to receive a -2, and you'll be asked to + refactor the change to conform with this guidance. + +- Do not stack change requests (e.g. submit a CR from the same local branch as + your previous CR) unless they are related. This will minimize merge conflicts + and allow changes to be merged more quickly. If you stack requests your + subsequent requests may be held up because of review comments in the preceding requests. - Write a meaningful commit message. Include a meaningful 50 (or less) - character title, followed by a blank line, followed by a more - comprehensive description of the change. Each change MUST include the JIRA - identifier corresponding to the change (e.g. [SPEC-1234]). This can be - in the title but should also be in the body of the commit message. See the [complete requirements](./4_Submitting_Changes.md) for an acceptable change - request. + character title, followed by a blank line, followed by a more comprehensive + description of the change. Each change MUST include the JIRA identifier + corresponding to the change (e.g. [SPEC-1234]). This can be in the title but + should also be in the body of the commit message. See the [complete + requirements](./4_Submitting_Changes.md) for an acceptable change request. **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item. @@ -149,15 +142,14 @@ exceptions. Fix [SPEC-<JIRA-ID>] .... ``` -Finally, be responsive. Don't let a change request fester with review -comments such that it gets to a point that it requires a rebase. It only -further delays getting it merged and adds more work for you - to -remediate the merge conflicts. +Finally, be responsive. Don't let a change request fester with review comments +such that it gets to a point that it requires a rebase. It only further delays +getting it merged and adds more work for you - to remediate the merge conflicts. ## Legal stuff -We have tried to make it as easy as possible to make contributions. This -applies to how we handle the legal aspects of contribution. +We have tried to make it as easy as possible to make contributions. This applies +to how we handle the legal aspects of contribution. We simply ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message. @@ -166,5 +158,5 @@ include a sign-off statement in the commit message. Signed-off-by: John Doe <john.doe@example.com> ``` -You can include this automatically when you commit a change to your -local git repository using ``git commit -s``. +You can include this automatically when you commit a change to your local git +repository using ``git commit -s``. diff --git a/docs/5_How_To_Contribute/8_Adding_Documentation.md b/docs/5_How_To_Contribute/8_Adding_Documentation.md index b65e971..d2aad82 100644 --- a/docs/5_How_To_Contribute/8_Adding_Documentation.md +++ b/docs/5_How_To_Contribute/8_Adding_Documentation.md @@ -2,9 +2,9 @@ title: Adding Documentation --- -The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) -contains AGL documentation website template and content, rendering is -visible at +The [documentation gerrit +repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) +contains AGL documentation website template and content, rendering is visible at [https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and @@ -78,8 +78,8 @@ documentation ## Test Hyperlinks -[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that -allows to check all the hyperlinks in the site. +[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to +check all the hyperlinks in the site. For testing hyperlinks as soon as the local site is running, do: @@ -87,8 +87,8 @@ For testing hyperlinks as soon as the local site is running, do: $ linkchecker http://localhost:8000 ``` -The ```linkchecker``` output will display the broken link and there location -in the site. +The ```linkchecker``` output will display the broken link and there location in +the site. ## Submitting changes @@ -1,5 +1,5 @@ site_name: AGL Documentation -site_url: http://agl-docs.readthedocs.io/ +site_url: http://docs.automotivelinux.org/ site_author: Shankho Boron Ghosh theme_dir: 'theme/mkdocs_windmill' theme: @@ -10,16 +10,6 @@ theme: search_index_only: true include_search_page: true - - -#theme: - #name: windmill - #include_sidebar: False - #include_homepage_in_sidebar: False - #navigation_depth: 1 - #collapse_navigation: False - # titles_only: True - plugins: - search: separator: '[\s\-\_]+' |