diff options
authorScott Rifenbark <>2014-05-28 12:23:04 (GMT)
committerRichard Purdie <>2014-11-20 17:24:52 (GMT)
commite3dd621197548b4cf64988e757e9bc926082db73 (patch)
parent30b8d9378b8260e452552b806610dc9b6fe0b69f (diff)
dev-manual: Updated the "Making Images More Secure" section.yocto-1.6.2daisy-11.0.2
Fixes [YOCTO #5482] I did some significant re-writing and re-organization of this section. It now includes a bit about securing an image in general, provides general considerations, considerations specific to the OpenEmbedded build system, pointers to some tools in meta-security layer, and some other items. I added some key references to the section on considerations specific to the OpenEmbedded build system. In particular, I provided some cross-linking back to the extrausers.bbclass section to reference an example of adding a user account. I also split out the topics of adding an extra user and setting a password on the image in the bulleted list. Updated the setting root and extra user's passwords. Also, permanently removed the reference to the wiki that showed the less optimal way of setting a root password. Added a cross-reference to the meta-selinux layer in the section that describes how to make images more secure. (From yocto-docs rev: 812bf8e2c91c4dd14a2245509ea7008a24e90835) Signed-off-by: Scott Rifenbark <> Signed-off-by: Richard Purdie <>
1 files changed, 215 insertions, 20 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index bead56c..27e1b52 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3577,32 +3577,227 @@
3577 <title>Making Images More Secure</title> 3577 <title>Making Images More Secure</title>
3578 3578
3579 <para> 3579 <para>
3580 The Yocto Project has security flags that you can enable that 3580 Security is of increasing concern for embedded devices.
3581 help make your build output more secure. 3581 Consider the issues and problems discussed in just this
3582 The security flags are in the 3582 sampling of work found across the Internet:
3583 <filename>meta/conf/distro/include/</filename> 3583 <itemizedlist>
3584 file in your 3584 <listitem><para><emphasis>
3585 <link linkend='source-directory'>Source Directory</link> 3585 "<ulink url=''>Security Risks of Embedded Systems</ulink>"</emphasis>
3586 (e.g. <filename>poky</filename>). 3586 by Bruce Schneier
3587 </para></listitem>
3588 <listitem><para><emphasis>
3589 "<ulink url=''>Internet Census 2012</ulink>"</emphasis>
3590 by Carna Botnet</para></listitem>
3591 <listitem><para><emphasis>
3592 "<ulink url=''>Security Issues for Embedded Devices</ulink>"</emphasis>
3593 by Jake Edge
3594 </para></listitem>
3595 <listitem><para><emphasis>
3596 "<ulink url=''>They ought to know better: Exploiting Security
3597Gateways via their Web Interfaces</ulink>"</emphasis>
3598 by Ben Williams
3599 </para></listitem>
3600 </itemizedlist>
3587 </para> 3601 </para>
3588 3602
3589 <para> 3603 <para>
3590 These GCC/LD flags enable more secure code generation. 3604 When securing your image is of concern, there are steps, tools,
3591 By including the <filename></filename> 3605 and variables that you can consider to help you reach the
3592 file, you enable flags to the compiler and linker that cause 3606 security goals you need for your particular device.
3593 them to generate more secure code. 3607 Not all situations are identical when it comes to making an
3608 image secure.
3609 Consequently, this section provides some guidance and suggestions
3610 for consideration when you want to make your image more secure.
3594 <note> 3611 <note>
3595 These flags are enabled by default in the 3612 Because the security requirements and risks are
3596 <filename>poky-lsb</filename> distribution. 3613 different for every type of device, this section cannot
3614 provide a complete reference on securing your custom OS.
3615 It is strongly recommended that you also consult other sources
3616 of information on embedded Linux system hardening and on
3617 security.
3597 </note> 3618 </note>
3598 Use the following line in your
3599 <filename>local.conf</filename> file
3600 to enable the security compiler and
3601 linker flags to your build:
3602 <literallayout class='monospaced'>
3603 require conf/distro/include/
3604 </literallayout>
3605 </para> 3619 </para>
3621 <section id='general-considerations'>
3622 <title>General Considerations</title>
3624 <para>
3625 General considerations exist that help you create more
3626 secure images.
3627 You should consider the following suggestions to help
3628 make your device more secure:
3629 <itemizedlist>
3630 <listitem><para>
3631 Scan additional code you are adding to the system
3632 (e.g. application code) by using static analysis
3633 tools.
3634 Look for buffer overflows and other potential
3635 security problems.
3636 </para></listitem>
3637 <listitem><para>
3638 Pay particular attention to to the security for
3639 any web-based administration interface.
3640 </para>
3641 <para>Web interfaces typically need to perform
3642 administrative functions and tend to need to run with
3643 elevated privileges.
3644 Thus, the consequences resulting from the interface's
3645 security becoming compromised can be serious.
3646 Look for common web vulnerabilities such as
3647 cross-site-scripting (XSS), unvalidated inputs,
3648 and so forth.</para>
3649 <para>As with system passwords, the default credentials
3650 for accessing a web-based interface should not be the
3651 same across all devices.
3652 This is particularly true if the interface is enabled
3653 by default as it can be assumed that many end-users
3654 will not change the credentials.
3655 </para></listitem>
3656 <listitem><para>
3657 Ensure you can update the software on the device to
3658 mitigate vulnerabilities discovered in the future.
3659 This consideration especially applies when your
3660 device is network-enabled.
3661 </para></listitem>
3662 <listitem><para>
3663 Ensure you remove or disable debugging functionality
3664 before producing the final image.
3665 For information on how to do this, see the
3666 "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>"
3667 section.
3668 </para></listitem>
3669 <listitem><para>
3670 Ensure you have no network services listening that
3671 are not needed.
3672 </para></listitem>
3673 <listitem><para>
3674 Remove any software from the image that is not needed.
3675 </para></listitem>
3676 <listitem><para>
3677 Enable hardware support for secure boot functionality
3678 when your device supports this functionality.
3679 </para></listitem>
3680 </itemizedlist>
3681 </para>
3682 </section>
3684 <section id='security-flags'>
3685 <title>Security Flags</title>
3687 <para>
3688 The Yocto Project has security flags that you can enable that
3689 help make your build output more secure.
3690 The security flags are in the
3691 <filename>meta/conf/distro/include/</filename>
3692 file in your
3693 <link linkend='source-directory'>Source Directory</link>
3694 (e.g. <filename>poky</filename>).
3695 <note>
3696 Depending on the recipe, certain security flags are enabled
3697 and disabled by default.
3698 </note>
3699 </para>
3701 <para>
3703 The GCC/LD flags in <filename></filename>
3704 enable more secure code generation.
3705 By including the <filename></filename>
3706 file, you enable flags to the compiler and linker that cause
3707 them to generate more secure code.
3708 <note>
3709 The GCC/LD flags are enabled by default in the
3710 <filename>poky-lsb</filename> distribution.
3711 </note>
3713 Use the following line in your
3714 <filename>local.conf</filename> file or in your custom
3715 distribution configuration file to enable the security
3716 compiler and linker flags to your build:
3717 <literallayout class='monospaced'>
3718 require conf/distro/include/
3719 </literallayout>
3720 </para>
3721 </section>
3723 <section id='considerations-specific-to-the-openembedded-build-system'>
3724 <title>Considerations Specific to the OpenEmbedded Build System</title>
3726 <para>
3727 You can take some steps that are specific to the
3728 OpenEmbedded build system to make your images more secure:
3729 <itemizedlist>
3730 <listitem><para>
3731 Ensure "debug-tweaks" is not listed with
3732 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>.
3733 The default is to enable "debug-tweaks" by adding it
3734 to
3735 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
3736 in <filename>local.conf</filename>.
3737 However, you should comment out the variable or be
3738 sure that it does not have "debug-tweaks" before
3739 producing your final image.
3740 Among other things, leaving this in place sets the
3741 root password as blank, which makes logging in for
3742 debugging or inspection easy during
3743 development but also means anyone can easily log in
3744 during production.
3745 </para></listitem>
3746 <listitem><para>
3747 It is possible to set a root password for the image
3748 and also to set passwords for any extra users you might
3749 add (e.g. administrative or service type users).
3750 When you set up passwords for multiple images or
3751 users, you should not duplicate passwords.
3752 </para>
3753 <para>
3754 To set up passwords, use the
3755 <filename>extrausers</filename> class, which is the
3756 preferred method.
3757 For an example on how to set up both root and user
3758 passwords, see the
3759 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>"
3760 section.
3761 <note>
3762 When adding extra user accounts or setting a
3763 root password, be cautious about setting the
3764 same password on every device.
3765 If you do this, and the password you have set
3766 is exposed, then every device is now potentially
3767 compromised.
3768 If you need this access but want to ensure
3769 security, consider setting a different,
3770 random password for each device.
3771 Typically, you do this as a separate step after
3772 you deploy the image onto the device.
3773 </note>
3774 </para></listitem>
3775 <listitem><para>
3776 Consider enabling a Mandatory Access Control (MAC)
3777 framework (such as SMACK or SELinux) and tuning it
3778 appropriately for your device's usage.
3779 You can find more information in the
3780 <ulink url=''><filename>meta-selinux</filename></ulink>
3781 layer.
3782 </para></listitem>
3783 </itemizedlist>
3784 </para>
3786 <para>
3787 </para>
3788 </section>
3790 <section id='tools-for-hardening-your-image'>
3791 <title>Tools for Hardening Your Image</title>
3793 <para>
3794 The Yocto Project provides tools for making your image
3795 more secure.
3796 You can find these tools in the
3797 <filename>meta-security</filename> layer of the
3798 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
3799 </para>
3800 </section>
3606 </section> 3801 </section>
3607 3802
3608 <section id='creating-your-own-distribution'> 3803 <section id='creating-your-own-distribution'>