Skip to content

Adding support for Custom CA Certificates during system build #2913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
schaefi merged 1 commit into from
Jan 7, 2026
+749 −8
Merged

Adding support for Custom CA Certificates during system build #2913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions build-tests/x86/tumbleweed/test-image-disk-simple/appliance.kiwi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@
<repository type="rpm-md">
<source path="obsrepositories:/"/>
</repository>
<certificates target_distribution="suse">
<certificate name="/var/lib/ca-certificates/ca-bundle.pem"/>
</certificates>
<packages type="image">
<package name="patterns-base-minimal_base"/>
<package name="bind-utils"/>
Expand Down
20 changes: 20 additions & 0 deletions doc/source/commands/system_build.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ SYNOPSIS
[--add-repo-credentials=<user:pass_or_filename>...]
[--add-package=<name>...]
[--add-bootstrap-package=<name>...]
[--ca-cert=<cert-file>...]
[--ca-target-distribution=<suse|rhel|debian|archlinux>]
Copy link
Member

@Conan-Kudo Conan-Kudo Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should have been redhat instead of rhel.

[--delete-package=<name>...]
[--set-container-derived-from=<uri>]
[--set-container-tag=<name>]
Expand Down Expand Up @@ -98,6 +100,24 @@ OPTIONS
is shared between multiple image builds on that host for performance
reasons.

--ca-cert=<cert-file>

Add a cert-file to the directory storing additional local CA certificates.
The import will occur immediately after the bootstrap process, where
the required CA update tooling is expected to be installed. This
option is useful for situations where certificates are not packaged,
or the certificates are required during the build process, e.g. due
to proxy servers in the build environment that need certificates
in chroot. The option can be specified multiple times.

--ca-target-distribution=<suse|rhel|debian|archlinux>

Specify target distribution for the import of certificates
via the --ca-cert options(s) and/or the provided <certificates>
from the image description. The selected distribution is used
in KIWI to map the distribution specific CA storage path and
update tool for the import process.

--delete-package=<name>

Specify package to delete. The option can be specified
Expand Down
20 changes: 20 additions & 0 deletions doc/source/commands/system_prepare.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ SYNOPSIS
[--add-repo-credentials=<user:pass_or_filename>...]
[--add-package=<name>...]
[--add-bootstrap-package=<name>...]
[--ca-cert=<cert-file>...]
[--ca-target-distribution=<suse|rhel|debian|archlinux>]
[--delete-package=<name>...]
[--set-container-derived-from=<uri>]
[--set-container-tag=<name>]
Expand Down Expand Up @@ -95,6 +97,24 @@ OPTIONS
is shared between multiple image builds on the host for performance
reasons.

--ca-cert=<cert-file>

Add a cert-file to the directory storing additional local CA certificates.
The import will occur immediately after the bootstrap process, where
the required CA update tooling is expected to be installed. This
option is useful for situations where certificates are not packaged,
or the certificates are required during the build process, e.g. due
to proxy servers in the build environment that need certificates
in chroot. The option can be specified multiple times.

--ca-target-distribution=<suse|rhel|debian|archlinux>

Specify target distribution for the import of certificates
via the --ca-cert options(s) and/or the provided <certificates>
from the image description. The selected distribution is used
in KIWI to map the distribution specific CA storage path and
update tool for the import process.

--delete-package=<name>

Specify a package to delete. The option can be specified
Expand Down
43 changes: 39 additions & 4 deletions doc/source/image_description/elements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,41 @@ The following optional sub sections can be inserted below the description tag:
license
Specifies the license name which applies to this image description.

.. _sec.certificates:

<certificates>
--------------

Add a cert-file to the directory storing additional local CA certificates.
The import will occur immediately after the bootstrap process, where
the required CA update tooling is expected to be installed. This
setting is useful for situations where certificates are not packaged,
or the certificates are required during the build process, e.g. due
to proxy servers in the build environment that need certificates
in chroot. The required `target_distribution` attribute must be set
to allow kiwi a correct matching for the CA store path and the update
tool with regards to the image target distribution. The following
settings apply:

+--------------+-------------------------------------------+------------------------+
| Distributor | CA Store | Update Tool |
+==============+===========================================+========================+
| SUSE | /etc/pki/trust/anchors | update-ca-certificates |
+--------------+-------------------------------------------+------------------------+
| Red Hat | /etc/pki/ca-trust/source/anchors | update-ca-certificates |
+--------------+-------------------------------------------+------------------------+
| Debian Based | /usr/local/share/ca-certificates | update-ca-certificates |
+--------------+-------------------------------------------+------------------------+
| Arch Linux | /etc/ca-certificates/trust-source/anchors | update-ca-trust |
+--------------+-------------------------------------------+------------------------+

.. code:: xml

<certificates target_distribution="suse|rhel|debian|archlinux">
<certificate name="/some/ca/filename1"/>
<certificate name="/some/ca/filename2"/>
</certificates>

.. _sec.preferences:

<preferences>
Expand Down Expand Up @@ -170,7 +205,7 @@ table shows which package manager is connected to which distributor:
+==============+=================+
| SUSE | zypper |
+--------------+-----------------+
| RedHat | dnf4 / dnf5 |
| Red Hat | dnf4 / dnf5 |
+--------------+-----------------+
| Debian Based | apt |
+--------------+-----------------+
Expand Down Expand Up @@ -1706,7 +1741,7 @@ The namedCollection element is used to install a number of packages
grouped together under a name. This is a feature of the individual
distribution and used in the implementation of the {kiwi} package
manager backend. At the moment collections are only supported for
SUSE and RedHat based distributions. The optional `patternType` attribute
SUSE and Red Hat based distributions. The optional `patternType` attribute
is used to control the behavior of the dependency resolution of
the package collection. `onlyRequired` installs only the collection
and its required packages. `plusRecommended` installs the collection,
Expand All @@ -1724,9 +1759,9 @@ any of its required packages and any recommended packages.
`$ zypper search patterns`. By convention all packages that starts
with the name "patterns-" are representing a pattern package.

.. note:: Collections on RedHat
.. note:: Collections on Red Hat

On RedHat based distributions collections are called `groups` and are
On Red Hat based distributions collections are called `groups` and are
extra metadata. To get the names of these groups type the following
command: `$ dnf group list -v`. Please note that since {kiwi} v9.23.39,
group IDs are allowed only, e.g.:
Expand Down
28 changes: 28 additions & 0 deletions kiwi/defaults.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,26 @@
# optional package manager environment variables
PACKAGE_MANAGER_ENV_VARS = '/.kiwi.package_manager.env'

# Distribution specific CA store and tooling
CA_UPDATE_MAP = {
'suse': {
'tool': 'update-ca-certificates',
'destination_path': '/etc/pki/trust/anchors'
},
'rhel': {
'tool': 'update-ca-certificates',
'destination_path': '/etc/pki/ca-trust/source/anchors/'
},
'debian': {
'tool': 'update-ca-certificates',
'destination_path': '/usr/local/share/ca-certificates/'
},
'archlinux': {
'tool': 'update-ca-trust',
'destination_path': '/etc/ca-certificates/trust-source/anchors/'
}
}

log = logging.getLogger('kiwi')


Expand Down Expand Up @@ -2316,6 +2336,14 @@ def get_apk_repo_config() -> str:
"""
return '/etc/apk/repositories'

@staticmethod
def get_ca_update_map(target_distribution) -> Optional[Dict[str, str]]:
return CA_UPDATE_MAP.get(target_distribution)

@staticmethod
def get_ca_target_distributions() -> List[str]:
return sorted(CA_UPDATE_MAP.keys())

def get(self, key):
"""
Implements get method for profile elements
Expand Down
7 changes: 7 additions & 0 deletions kiwi/exceptions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -874,3 +874,10 @@ class KiwiEnclaveFormatError(KiwiError):
Exception raised if no enclave_format attribute specified
for the selected build type
"""


class KiwiCATargetDistributionError(KiwiError):
"""
Exception raised if no CA target distribution can be found
but the request to import custom CA certificates was issued
"""
34 changes: 34 additions & 0 deletions kiwi/schema/kiwi.rnc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ div {
element image {
k.image.attlist &
k.include* &
k.certificates? &
k.description &
k.preferences+ &
k.profiles* &
Expand Down Expand Up @@ -1121,6 +1122,39 @@ div {
}
}

#==========================================
# common element <certificates>
#
div {
k.certificates.profiles.attribute = k.profiles.attribute
k.certificates.target_distribution.attribute =
attribute target_distribution {
"suse" | "rhel" | "debian" | "archlinux"
}
k.certificates.attlist =
k.certificates.profiles.attribute? &
k.certificates.target_distribution.attribute
k.certificates =
element certificates {
k.certificates.attlist,
k.certificate+
}
}

#==========================================
# common element <certificate>
#
div {
k.certificate.name.attribute = k.name.attribute
k.certificate.attlist = k.certificate.name.attribute
k.certificate =
# A pointer to a filename handled as a CA file
element certificate {
k.certificate.attlist,
empty
}
}

#==========================================
# common element <repository>
#
Expand Down
59 changes: 59 additions & 0 deletions kiwi/schema/kiwi.rng
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,9 @@ named /etc/ImageID</a:documentation>
<zeroOrMore>
<ref name="k.include"/>
</zeroOrMore>
<optional>
<ref name="k.certificates"/>
</optional>
<ref name="k.description"/>
<oneOrMore>
<ref name="k.preferences"/>
Expand Down Expand Up @@ -1736,6 +1739,62 @@ loading of the container at first boot</a:documentation>
</element>
</define>
</div>
<!--
==========================================
common element <certificates>

-->
<div>
<define name="k.certificates.profiles.attribute">
<ref name="k.profiles.attribute"/>
</define>
<define name="k.certificates.target_distribution.attribute">
<attribute name="target_distribution">
<choice>
<value>suse</value>
<value>rhel</value>
<value>debian</value>
<value>archlinux</value>
</choice>
</attribute>
</define>
<define name="k.certificates.attlist">
<interleave>
<optional>
<ref name="k.certificates.profiles.attribute"/>
</optional>
<ref name="k.certificates.target_distribution.attribute"/>
</interleave>
</define>
<define name="k.certificates">
<element name="certificates">
<ref name="k.certificates.attlist"/>
<oneOrMore>
<ref name="k.certificate"/>
</oneOrMore>
</element>
</define>
</div>
<!--
==========================================
common element <certificate>

-->
<div>
<define name="k.certificate.name.attribute">
<ref name="k.name.attribute"/>
</define>
<define name="k.certificate.attlist">
<ref name="k.certificate.name.attribute"/>
</define>
<define name="k.certificate">
<!-- A pointer to a filename handled as a CA file -->
<element name="certificate">
<ref name="k.certificate.attlist"/>
<empty/>
</element>
</define>
</div>
<!--
==========================================
common element <repository>
Expand Down
Loading