Security Configuration Tool#

Tool Version: 1.0

Introduction#

Security Configuration Tool generates security-related configuration files for NVIDIA DriveOS Linux systems based on user-provided Security Config YAMLs. It transforms security documentation into operational configuration artifacts including:

  • Systemd unit files for service/process management

  • Systemd tmpfiles rules for filesystem permissions of /sys/, /tmp/, /proc/ nodes

  • Udev rules for device management and assignment of permissions to /dev/nodes

  • Copy target YAML files for specifying files and permissions of the same in the Ext4 image generated.

  • AppArmor policies for mandatory access control

This tool aims to reduce manual effort for doing security calibration.

It works on “atomic” dependency information each component knows to generate the final security calibration data. “atomic” implying first-level dependencies the components are aware about.

Prerequisites#

  • python3 >= 3.10 with the following python3 modules:

    • jsonschema

    • ruamel.yaml

Usage#

This tool is automatically invoked when the tool bind_partitions or create_linux_targetfs.sh is run, with the correct set of parameters.

The external parameters exposed to the end user by these tools are the following parameters:

Table 1 Export parameters to control tool behavior#

Parameter

Value

Description

Example

SEC_CONF_TOOL_ADD_SPEC_FILES

Space separated list of files

Additional specification files created by DriveOS stakeholder to be used along with the DriveOS specification file to create the combined security calibration data.

Please see Specification Files for more information

SEC_CONF_TOOL_ADD_SPEC_FILES="${HOME}/driveav.spec.yaml ${CONFIG_HOME}/config/drive_customer.spec.yaml"

SEC_CONF_TOOL_ADD_ENV_FILES

Space separated list of files

Additional Environment files containing key=value pair for parsing specification files and other input security configs.

Please see Environment Files below for more information

SEC_CONF_TOOL_ADD_ENV_FILES="${HOME}/driveav.env ${CONFIG_HOME}/config/drive_customer.env"

Example Usage

export SEC_CONF_TOOL_ADD_SPEC_FILES="${HOME}/driveav.spec.yaml ${CONFIG_HOME}/config/drive_customer.spec.yaml"
export SEC_CONF_TOOL_ADD_ENV_FILES="${HOME}/driveav.env ${CONFIG_HOME}/config/drive_customer.env"
./drive-foundation/make/bind_partitions # Bind command for the target.

Quick Start Guide#

This guides shows step by step process to add a custom element’s contents to the target filesystem image with security enforced.

The steps to add the element to the security infrastructure are as follows:

  1. Create Security Config YAMLs for the element. Ensure all the groups documented are unique and not used by other nodes (Tool will catch this if groups are repeated.)

    1. File Ownership And Dependency Information

      1. Create a file ownership and dependency information YAML for the element.

      2. Identify all the files that will need to be present in the target filesystem image and categorize them into the supported file types.

      3. For each file, specify the properties as per the File Ownership And Dependency Information document.

      4. For identifying the dependencies, use readelf -a <lib/executable> | grep NEEDED to get the atomic dependencies of the library/executable.

        Note

        This step only gives compile time linked dependencies. Anything the code opens at runtime needs to be analyzed.

      5. Ensure the files that are depended on are present in either DriveOS security documents or in other elements’ security documents.

      6. Set shared: yes, if there are more than one process instance using the file.

      7. Ensure to specify any file opened or executed by the executable/library at runtime in the file_dependencies property.

      8. If the dependency library provides classes of functionality, create a func_class_mapping as specified in Dependency List document.

        Note

        You can check for func_class_mapping keyword in file_dependencies or library_dependencies of that library to confirm.

      9. If shared is set to ‘no’, it is expected that there will be a single process instance being dependent on the file.

        Note

        If no process or more than one process is dependent on the file, tool will error out.

      10. Ensure to record the directory entries of the path in the destination property if they don’t exist.

        Note

        Tool will error out if they don’t exist.

    2. Library Access Control And Abilities Dependency Information

      1. Any library documented in the File Ownership And Dependency Information document should also be documented in the Library Access Control And Abilities Dependency Information document.

      2. For each library, specify the properties as per the Library Access Control And Abilities Dependency Information document.

      3. One can give just the basename of the library as the key for the libraryList entry.

      4. When recording the dependencies, if the library wants to classify the functionalities exposed to be more fine-grained, create a func_class_mapping as specified in Dependency List document.

    3. KMD Ownership Information

      1. Any kmd node documented in the File Ownership And Dependency Information document should also be documented in the KMD Ownership Information document.

      2. For each kmd node, specify the properties as per the KMD Ownership Information document.

      3. Ensure to document full absolute paths as path in the entry (without symlinks).

      4. If using “mode” property, ensure to not give “world” user access.

    4. Process Information

      1. Any process that needs to be started on boot should be documented in the Process Information document.

      2. Ensure to have unique User for each process. (Tool will error out if it finds duplicate users)

  2. Create a specification file for the program, if it doesn’t exist. (Refer Specification Files for more information)

  3. Add the YAMLs created in step 1 to the specification file of the program.

  4. Reserve Users and Groups specified in step 1 in the target filesystem image. See NV UID and GID Reservation Tool for more information.

  5. Rebuild the target filesystem image using the tool create_linux_targetfs.sh or invoke bind_partitions with the correct set of parameters.

Example Scenario#

This guides shows step by step process to add a custom element’s contents to the target filesystem image with security enforced.

The example files used here are hypothetical and does not resemble existing DriveOS files.

Step 1#

Create the following YAMLs under the directory ${SECURITY_DIR}/custom/. Let us assume SECURITY_DIR is drive-linux/filesystem/security_configs/linux/.

file_ownership_and_dependencies.yaml

Filling in the initial template:

version: 1.0
os: linux
doctype: file_ownership_and_dependencies
element: custom
fileList:

Adding an entry for each file that needs to be added to the target filesystem image with security protection.

There are a few kernel modules, a library, a binary and a configuration file that needs to be added to the target filesystem image. Starting off with the kernel modules, the following properties are needed as per the File Ownership And Dependency Information document:

  1. destination: Path to the kernel module in the target filesystem image.

  2. source: Path to the kernel module in the SDK.

  3. filetype: kernel_module

  4. jama: JAMA number for the kernel module.

  5. purpose: Purpose of the kernel module.

- destination: /lib/modules/${NVRTKERNELNAME}/updates/drivers/virt/tegra/tegra_hv_pm_ctl.ko
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/kernel/${KERNEL_VERSION}/preempt_rt${PROD_SUFFIX}/modules/${NVRTKERNELNAME}/updates/drivers/virt/tegra/tegra_hv_pm_ctl.ko
  filetype: kernel_module
  jama: 'DOS-SHR-111'
  purpose: 'HV pwr mgmt driver required reboot, shutdown, suspend and resume funcitonality support.'
- destination: /lib/modules/${NVRTKERNELNAME}/updates/drivers/cpuidle/cpuidle-tegra-auto.ko
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/kernel/${KERNEL_VERSION}/preempt_rt${PROD_SUFFIX}/modules/${NVRTKERNELNAME}/updates/drivers/cpuidle/cpuidle-tegra-auto.ko
      build_tree_path: ${NV_OUTDIR}/systemimage/${KERNELVARIANT}/lib/modules${PROD_SUFFIX}/${NVRTKERNELNAME}/updates/drivers/cpuidle/cpuidle-tegra-auto.ko
  filetype: kernel_module
  jama: 'DOS-SHR-111'

Next, the library and executable, the following properties are needed as per the File Ownership And Dependency Information document:

  1. destination: Path to the library/executable in the target filesystem image.

  2. source: Path to the library/executable in the SDK.

  3. filetype: library/executable

  4. shared: yes if there are more than one process instance using the library/executable.

  5. jama: JAMA number for the library/executable.

  6. purpose: Purpose of the library/executable.

  7. file_dependencies: Since this filetype is a library/executable, file_dependencies is a required property.

    1. Checking readelf -a <lib/executable> | grep NEEDED to get the atomic dependencies of the library/executable and analyzing the source code

  8. group: Since the files are shared, group is a required property, and is used to protect access to the files.

  9. additional_entries:

    1. /usr/lib/, /usr/bin/ are upstream, so entry is not needed.

    2. /usr/lib/custom/ is element-created, so entry is needed.

- destination: /usr/lib/libnvrm_host1x.so
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/libnvrm_host1x.so
  filetype: library
  shared: yes
  jama: 'DOS-SHR-111'
  purpose: 'userspace library for accessing host1x services'
  group: 'nvrm-host1x'
  file_dependencies:
      - /usr/lib/libnvos.so
      - /usr/lib/libnvrm_mem.so
      - /usr/lib/libnvsciipc.so
      - /usr/lib/libnvsocsys.so
      - /usr/lib/libnvrm_chip.so
      - /lib/aarch64-linux-gnu/libc.so.6
- destination: /usr/lib/custom/libnvrm_stream.so
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/custom/libnvrm_stream.so
  filetype: library
  shared: yes
  jama: 'DOS-SHR-111'
  purpose: 'userspace library for accessing host1x channel stream services'
  group: 'nvrm-stream'
  file_dependencies:
      - /usr/lib/libnvos.so
      - /usr/lib/libnvrm_mem.so
      - /usr/lib/libnvsciipc.so
      - /usr/lib/libnvsocsys.so
      - /usr/lib/libnvrm_chip.so
      - /usr/lib/libnvrm_sync.so
      - /usr/lib/libnvrm_host1x.so
      - /lib/aarch64-linux-gnu/libc.so.6
- destination: /usr/bin/custom_bin
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/custom/custom_bin
  filetype: executable
  shared: yes
  jama: 'DOS-SHR-111'
  purpose: 'custom binary'
  group: 'custom_bin-exe'
  file_dependencies:
      - /usr/lib/libnvos.so
      - /usr/lib/libnvrm_mem.so
      - /usr/lib/libnvsciipc.so
      - /usr/lib/libnvsocsys.so
      - /usr/lib/libnvrm_chip.so
      - /usr/lib/libnvrm_sync.so

- destination: /usr/lib/custom/
  filetype: directory
  shared: yes
  jama: 'DOS-SHR-111'
  purpose: 'Directory for storing custom libraries'

library_access_control_abilities_dependencies.yaml

Filling in the initial template:

version: 1.0
os: linux
doctype: library_access_control_abilities_dependencies
element: custom
libraryList:

  • Add an entry for each library that was added in the File Ownership And Dependency Information document.

  • Analyze the source code of the library to determine the dev_paths, sys_paths, other_pseudofs_paths that the library opens.

  • Use the capabilities man page to determine the capabilities that the library requires.

  • This is ideally none, but if the library only works under root conditions, it could imply the library needs some of the capabilities to run as non-root.

libnvrm_host1x.so:
    dev_paths:
        - r'/dev/nvrm_host[0-9]{1,2}'
    sys_paths:
        - r'/sys/bus/platform/devices/host[0-9]{1,2}'
    other_pseudofs_paths:
        - /proc/driver/nvrm_host1x
    capabilities:
libnvrm_stream.so:
    dev_paths:
        - /dev/nvrm_stream
    sys_paths:
        - /sys/bus/platform/devices/stream
    other_pseudofs_paths:
        - /proc/driver/nvrm_stream
    capabilities:
        - CAP_NET_ADMIN:
            phase: INIT

kmd_ownership_information.yaml

Filling in the initial template:

version: 1.0
os: linux
doctype: kmd_ownership_information
element: custom
kmdList:

  • Add an entry for each kmd node that was added in the File Ownership And Dependency Information document.

  • Protect all interfaces created by the KMD. Using regex for paths not known at build time.

  • Use glob for KERNEL and tmpfiles_glob.

    Note

    Glob cannot match 1:1 with regex, it is a fuzzy match, ensure on the target it matches only the files intended to be protected, using ls <glob_pattern>

tegra_hv_pm_ctl.ko:
    dev_paths:
        - path: /dev/tegra_hv_pm_ctl
          group: 'tegra_hv_pm_ctl'
          readable: yes
          writable: no
          KERNEL: tegra_hv_pm_ctl
        - path: r'/dev/tegra_hv_pm_ctl_node[0-9]{1,2}'
          group: 'tegra_hv_pm_ctl_node'
          readable: yes
          writable: no
          KERNEL: tegra_hv_pm_ctl_node[0-9]*
    sys_paths:
        - path: r'/sys/bus/platform/devices/tegra_hv_pm_ctl/[0-9a-z]+/node'
          group: 'tegra_hv_pm_ctl_sys_node'
          readable: yes
          writable: yes
          tmpfiles_glob: /sys/bus/platform/devices/tegra_hv_pm_ctl/[0-9a-z]*/node
    other_pseudofs_paths: []

process_information.yaml

Filling in the initial template:

version: 1.0
os: linux
doctype: process_information
element: custom
processList:

  • Add an entry for each process that needs to be started on the target.

  • For the process entry, initially analyze the ordering dependencies of the process.

  • The custom_bin has a strong dependency on VLAN interface being up, so it should be started after nv_tacp_init.service.

  • Since nv_tacp_init.service is also specified in the documentation id. nv_tacp_init can be used.

  • Any dependency on canonical services, use the tag service: <service/target name>, setting type to strong, since if these services fail, custom_bin.service will fail to start.

  • Set Before: [] if no dependencies precede this process.

custom_bin:
    After:
        - id: nv_tacp_init
          type: strong
        - service: network_online.target
          type: strong
    Before: []

Set other boiler-plate properties:

  • RuntimeConditions: Ensure vlan0 is up.

  • User: Unique user for this process.

  • Executable: custom_bin

  • LaunchCmd: custom_bin and the arguments to pass to it.

  • AdditionalSystemdArgs: Include upstream groups to access /dev/console. Need to include tty.

  • AccessControlDependencies: r'/dev/tegra_hv_pm_ctl_node[0-9]{1,2}' is being opened.

  • ProcessSpecificFileDependencies: custom_bin is opening /usr/lib/custom/libnvrm_stream.so is opened by this process because of the argument passed to it.

Conditions:
    CompileConditions: {}
    RuntimeConditions:
        - ConditionPathExists: /dev/vlan0
User: custom-bin_1
ASIL: QM
Priority: 0
IsNetworkExposed: no
Rlimits: []
Executable: custom_bin
LaunchCmd: custom_bin --arg1 --load libnvrm_stream.so
AdditionalSystemdArgs:
    - SupplementaryGroups: tty
    - StandardOutput: journal+console
AccessControlDependencies:
    dev_paths:
        - r'/dev/tegra_hv_pm_ctl_node[0-9]{1,2}'
    sys_paths: []
    other_pseudofs_paths: []
ProcessSpecificFileDependencies:
    - /usr/lib/custom/libnvrm_stream.so

Step 2-3#

Check if the custom element is added to specification file. If not, add it.

file_ownership_and_dependencies:
     -  ${SECURITY_DIR}/main/file_ownership_and_dependencies.yaml
     -  ${SECURITY_DIR}/custom/file_ownership_and_dependencies.yaml
library_access_control_abilities_dependencies:
     -  ${SECURITY_DIR}/main/library_access_control_abilities_dependencies.yaml
     -  ${SECURITY_DIR}/custom/library_access_control_abilities_dependencies.yaml
process_information:
     -  ${SECURITY_DIR}/main/process_information.yaml
     -  ${SECURITY_DIR}/custom/process_information.yaml
kmd_ownership_information:
     -  ${SECURITY_DIR}/main/kmd_ownership_information.yaml
     -  ${SECURITY_DIR}/custom/kmd_ownership_information.yaml

Step 4#

Reserve all the groups newly added to the document, in this case it would be:

['nvrm-host1x', 'nvrm-stream', 'custom_bin-exe', 'tegra_hv_pm_ctl', 'tegra_hv_pm_ctl_node', 'tegra_hv_pm_ctl_sys_node', 'custom-bin_1']

Step 5#

Proceed to flash the target invoking bind_partitions.

Tool Inputs#

Specification Files#

This is a file that specifies the list of input security configuration files that shall be used to create the output security calibration data. The list of input files are categorized into 4:

  • File Ownership And Dependency Information

  • Library Access Control And Abilities Dependency Information

  • KMD Ownership Information

  • Process Information

Environment variables are expanded if exported in the shell environment before invocation.

Sample specification file:

file_ownership_and_dependencies:
     -  ${SECURITY_DIR}/nvhv/file_ownership_and_dependencies.yaml
     -  ${SECURITY_DIR}/linux_bsp/system_state/file_ownership_and_dependencies.yaml
library_access_control_abilities_dependencies:
     -  ${SECURITY_DIR}/nvhv/library_access_control_abilities_dependencies.yaml
process_information:
     -  ${SECURITY_DIR}/nvhv/process_info.yaml
     -  ${SECURITY_DIR}/nvsciipc/process_info.yaml
kmd_ownership_information:
     -  ${SECURITY_DIR}/nvhv/kmd_ownership.yaml
     -  ${SECURITY_DIR}/nvsciipc/kmd_ownership.yaml
Table 2 Specification file semantics#

Field

Value

Description

file_ownership_and_dependencies

Array(strings)

Path to File Ownership Security Config YAMLs

library_access_control_abilities_dependencies

Array(strings)

Path to Library Dependencies Security Config YAMLs

process_information

Array(strings)

Path to Process Information Security Config YAMLs

kmd_ownership_information

Array(strings)

Path to KMD Ownership Security Config YAMLs

Environment Files#

These are input files specifying key, value pair of all environment variables that are referenced in the security documents (Specification Files, all Security Config YAMLs), which will be exported by the tool before processing these files to reduce reliance on the input shell environment.

Environment file example

# Sample environment file,
# Environment file can have comments starting with "#",
# Environment file can reference other env variables set in the shell # for referencing installation directories.
SECURITY_DOCS_DIR=${NV_WORKSPACE}/${NV_SDK_NAME_LINUX}/filesystem/security_configs/linux/
KERNEL_VERSION=nvidia-6.1

Supports comments starting with # and ENV_VAR=VALUE follows the generic rules of environment variables in a Linux environment.

Security Config YAMLs#

This section describes the various security config yamls that are expected to be listed in the Specification Files listed above. Every element is expected to create the following four types of security documents:

  • File Ownership And Dependency Information

  • Library Access Control And Abilities Dependency Information

  • KMD Ownership Information

  • Process Information

File Ownership And Dependency Information#

This document describes the physical files that are expected to be copied into the target filesystem image.

Each entry in the document describes the destination location of the file in the image and other attributes that allow the file to get the correct set of permissions, user and group data.

It also contains traceability info on why files are added to the target filesystem image, along with dependency info on other physical files that allows to create the dependency graph of any process using it.

This document will be used to create copytarget yaml files that will be used while creating the target filesystem image.

The group information specified in the document will be used to calibrate the supplementary groups of the process accessing the files as per their dependency tree.

version: 1.0
os: linux
doctype: file_ownership_and_dependencies
element: Cust_Element::Sub_Element1
fileList:
  - destination: /lib/modules/${NVRTKERNELNAME}/updates/drivers/video/tegra/nvmap/nvmap.ko
    source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/kernel/${KERNEL_VERSION}/preempt_rt${PROD_SUFFIX}/modules/${NVRTKERNELNAME}/updates/drivers/video/tegra/nvmap/nvmap.ko
    filetype: kernel_module
    jama: ''
    purpose: 'module for nvmap access'
  - destination: /usr/lib/libnvrm_mem.so
    source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/libnvrm_mem.so
    filetype: library
    shared: yes
    jama: ''
    purpose: 'userspace library for accessing nvmap services'
    group: 'memserv-libnvrm_mem'
    file_dependencies:
        - /usr/lib/libnvos.so
        - /usr/lib/libnvsciipc.so
        - /usr/lib/libnvsocsys.so
  - destination: /usr/bin/nvmap_sanity
    source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/qa/rm/nvmap/nvmap_sanity
    filetype: test
    jama: ''
    purpose: 'Sanity test for Memory Services'
    file_dependencies:
        - libnvrm_mem.so
        - libnvsciipc.so
        - libnvos.so
        - libm.so.6
        - libc.so.6
        - ld-linux-aarch64.so.1
  - destination: /etc/systemd/scripts/nv_tacp_init.sh
    source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/filesystem/contents/config/startup/scripts/nv_tacp_init.sh
    filetype: shell_script
    shared: no
    jama: DOS-SHR-8329,DOS-SHR-8913
    purpose: 'Helper tool for nv_tacp_init.service Without TACP VLAN is not setup and aurix update will fail.'
    file_dependencies:
        - ifconfig
        - iptables
        - ip
        - dhclient
        - sysctl
        - route
        - ping
        - bash # for executing the script
        - sleep
        - grep
        - cut
        - cat
Table 3 File Ownership And Dependency Information semantics#

Property

Required, Constraint

Type

Description

Example

element

Yes, Not empty

String
Name of the element.

Allowed characters: [a-zA-Z0-9_:-]
element: Cust_Element::Sub_Element1
element: LCM

destination

Yes, Not empty

String
Absolute path where the file will be installed in the target filesystem.
Valid Unix file path.
destination: /path/to/file1/in/target

source

Yes, Not empty

Dictionary
Dictionary containing the key pdk_sdk_installed_path.
This key’s value is the path to the file in the SDK. relative to NV_WORKSPACE (SDK installation directory).

pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/filesystem/contents/bin/testbin

filetype

Yes, Not empty

Enum
Type of the file.
Allowed values:
- configuration
- executable
- library
- directory
- data
- kernel_module
- symlink
- firmware
- shell_script
- test
- ubuntu_system_config
Legend:
Perm1/Perm2 -> Perm1 is when the file is shared, Perm2 is when the file is not shared.
Perm1 -> Permission regardless of the file is shared or not.
configuration:
- Gets the permission 040/400.
- Sets ‘shared’ to a required property.
data:
- Gets the permission 040/400.
- Sets ‘shared’ to a required property.
kernel_module:
- Gets the permission 400.
- Sets ‘shared’ implicitly to ‘no’.
- Sets ‘user’ to ‘root’.
- Sets ‘group’ to ‘root’.
firmware:
- Gets the permission 400.
- Sets ‘shared’ implicitly to ‘no’.
- Sets ‘user’ to ‘root’.
- Sets ‘group’ to ‘root’.
symlink:
- Gets the permission 777.
- Sets ‘shared’ to implicitly ‘yes’.
- Sets ‘user’ to ‘root’.
- Sets ‘group’ to ‘root’.
ubuntu_system_config:
- Gets the permission 444.
- Sets ‘shared’ to implicitly ‘yes’ as most of Ubuntu config files are world readable.
- Sets ‘user’ to ‘root’.
- Sets ‘group’ to ‘root’.
directory:
- Gets the permission 500/555.
- Sets ‘shared’ to a required property.
- Sets ‘group’ to ‘root’.
executable:
- Gets the permission 010/100.
- Sets ‘shared’ to a required property.
- Sets ‘file_dependencies’ to a required property.
library:
- Gets the permission 040/400.
- Sets ‘shared’ to a required property.
- Sets ‘file_dependencies’ to a required property.
shell_script:
- Gets the permission 050/500.
- Sets ‘shared’ to a required property.
- Sets ‘file_dependencies’ to a required property.
test:
- Gets the permission 555.
- Sets ‘shared’ to a implicitly ‘yes’.
- Sets ‘file_dependencies’ to a required property.
- Sets ‘user’ to ‘root’.
- Sets ‘group’ to ‘root’.
filetype: executable
filetype: library

shared

Optional, Not empty (See filetype when it becomes mandatory)

enum
Whether the file is shared between elements.
Allowed values:
- yes
- no
If shared is set to ’no’, user of file is set to ‘root’.
If shared is set to ‘yes’, this file will be accessible only via the “group” specified. Makes ‘group’ a required property.

shared: yes

jama

Yes

String
Traceability information for the file.

jama: ‘DOS-REQ-1111’

purpose

Yes, Not empty

String
One line description of the file on its purpose in the filesystem.

purpose: “Example file”

group

Optional, Not empty (See filetype, shared when it becomes required property and not implicitly set)

String
Group name of the file
Use [A-Za-z0-9_-] char set and size < 32 characters

group: “file1_g”

file_dependencies

Optional, Not empty (See filetype, when it becomes mandatory)

Array(strings/dicts)
Give first level file dependencies (not VFS), actual block device files dependent on by executables/libraries

Format could be 2 types:
- Full absolute valid unix paths in the target for dependencies like configuration, data, directory that are known to the executable/lib and referenced in its code
- library name against which it is linked. (This can be a symlink also)

The individual elements of the list could also be dicts and are recommended to be if the dependent file provides classes of functionality.
See section Dependency List below for more information.

This field also supports regex, please see Regex Support Section below
file_dependencies:
- /path/to/dep_file1
- /path/to/dep_file2
- libtestlib.so
- /path/to/dep_lib.so

Library Access Control And Abilities Dependency Information#

This document is an extension of the File Ownership And Dependency Information document. It describes the virual filesystem dependencies of the libraries that are expected to be present in the target filesystem image.

This allows processes to depend on a library without having to know the full internals of the library and gain access to the groups and capabilities required by the library to access the virtual filesystem nodes.

This document allows processes to create a dependency graph of all the items they need to depend on and the groups they need to be added to, to access all the nodes they need.

version: 1.0
os: linux
doctype: library_access_control_abilities_dependencies
element: Cust_Element::Sub_Element1
libraryList:
  libnvos.so:
    dev_paths: []
    sys_paths: []
    other_pseudofs_paths: []
    capabilities: []
  libnvsocsys.so:
    dev_paths: []
    sys_paths:
      - /sys/devices/soc0/soc_id
      - /sys/devices/soc0/revision
      - /sys/devices/soc0/major
      - /sys/devices/soc0/minor
      - /sys/devices/soc0/platform
      - /sys/devices/platform/bus@0/1000000.efuse/efuse0/nvmem
      - /sys/devices/platform/bus@0/101f054.efuse/efuse2/nvmem
      - /sys/devices/platform/bus@0/1000000.efuse/efuse_odm_id_0
      - /sys/devices/platform/bus@0/1000000.efuse/efuse_odm_id_1
      - /sys/devices/platform/bus@0/1000000.efuse/efuse_odm_info
    other_pseudofs_paths: []
    capabilities: []
Table 4 Library Access Control And Abilities Dependency Information Semantics#

Property

Required, Constraint

Type

Description

Example

element

Yes, Not empty

String
Name of the element.

Allowed characters: [a-zA-Z0-9_:-]
element: Cust_Element::Sub_Element1
element: LCM

libraryList

Yes, Not empty

Dictionary
A dictionary of libraries with their dependencies.

Key is the library name and value is a dictionary with the following properties, see <library.so> for more information.
libraryList:
libnvos.so: …
libnvsocsys.so: …

<library.so>

Yes, Not empty

Dictionary
A dictionary with the following properties.

dev_paths: ….
sys_paths: ….
other_pseudofs_paths: ….
capabilities: ….
libnvsocsys.so:

dev_paths: … sys_paths: … other_pseudofs_paths: … capabilities: …

dev_paths

Yes, Not Null, can be empty

Array(strings/dict)
Each item is a valid unix path to a device node in the target filesystem, for examle (/dev/*).

If the path is not determinable statically, for example if the device is enumerated at runtime,
record this as a regex string. For example, if the path is say /dev/i2c.<4 digit number>, then record it as r'/dev/i2c[0-9]{4}'.

See the Regex Support section for more information.

The individual items of the list could also be dicts and are recommended to be if the dependent file provides classes of functionality.
See the Dependency List section for more information.
dev_paths:
- r'/dev/i2c[0-9]{4}'
- /dev/zero

sys_paths

Yes, Not Null, can be empty

Array(strings)
Each item is a valid unix path to a sysfs node in the target filesystem, for example (/sys/*).

If the path is not determinable statically, for example if the device is enumerated at runtime,
record this as a regex string. i.e. if the path is say /sys/devices/soc<>number>/soc_id, then record it as r'/sys/devices/soc0/soc_id'.

See section Regex Support below for more information

The individual items of the list could also be dicts and are recommended to be if the dependent file provides classes of functionality.
See the Dependency List section for more information.
sys_paths:
- r'/sys/devices/soc[0-9]+/soc_id'
- /sys/devices/soc0/revision

other_pseudofs_paths

Yes, Not Null, can be empty

Array(strings)
Each item is a valid unix path to a pseudo-filesystem node in the target filesystem other than /dev/, /sys/.
(/proc/, /tmp/, /var/run and other VFS paths in target.)

If the path is not determinable statically, for example if the device is enumerated at runtime,
record this as a regex string. For example, if the path is say /sys/devices/soc<>number>/soc_id, then record it as r'/sys/devices/soc0/soc_id'.

See the Regex Support section for more information.

The individual items of the list could also be dicts and are recommended to be if the dependent file provides classes of functionality.
See section Dependency List below for more information.
other_pseudofs_paths:
- r'/proc/self/fd/[0-9]+'
- /var/run/nv_tacp_init.pid

capabilities

Yes, Not Null, can be empty

Array(dicts)
Each item is a dictionary with the following properties:

Key: Capability name
Value: {“phase”: enum[“INIT”, “RUN”]}

Capability name is the capability as per man(7)capabilities

Phase is the time at which the capability is required. INIT implies it will be dropped after initialization.
RUN implies it is required during the run phase and will not be dropped.
capabilities:
- CAP_SYS_ADMIN:
phase: INIT
- CAP_NET_ADMIN:
phase: RUN

KMD Ownership Information#

This document describes the virtual filesystem nodes exposed in the target, and the groups that should restrict access to them.

This document will be used to create udev rules and systemd-tmpfiles rules that modify the permissions of the virtual filesystem nodes to be minimal and as configured.

It also contains the information to the dependent processes what groups they should be added to, to access the virtual filesystem nodes.

version: 1.0
os: linux
doctype: kmd_ownership_information
element: Cust_Element::Sub_Element1
kmds:
    tegra-drm.ko:
        dev_paths:
            - path: r'/dev/dri/renderD[0-9]+'
              group: 'host1x-drm'
              readable: yes
              writable: yes
              KERNEL: renderD[0-9]*
              SUBSYSTEM: 'drm'
              SYMLINK: /dev/dri-render-host1x
              parent:
                KERNEL: '[0-9]*.host1x.drm'
                SUBSYSTEM: 'host1x'
                DRIVER: 'drm'
        sys_paths:
            - path: /sys/devices/platform/bus@0/d0b0000000.pcie/pci0000:00/0000:00:00.1/0000:01:00.0/dump_gr_hw_state_on_ctxsw_timeout
              group: 'nvgpu-gr_state_ctxsw_timeout'
              readable: true
              writable: true
            - path: /sys/devices/platform/bus@0/d0b0000000.pcie/pci0000:00/0000:00:00.1/0000:01:00.0/load
              group: 'nvgpu-load'
              readable: true
              writable: false
        other_pseudofs_paths: []
Table 5 KMD Ownership Information semantics#

Property

Required, Constraint

Type

Description

Example

element

Yes, Not empty

String
Name of the element.

Allowed characters: [a-zA-Z0-9_:-]
element: Cust_Element::Sub_Element1
element: LCM

kmds

Yes, Not empty

Dictionary
A dictionary of kernel modules with their ownership information
kmds:
tegradisp.ko: …
tegramod.ko: …

<kernel_module.ko>

Yes, Not empty

Dictionary
A dictionary with the following properties:

dev_paths: ….
sys_paths: ….
other_pseudofs_paths: ….
tegradisp.ko:

dev_paths: … sys_paths: … other_pseudofs_paths: …

dev_paths

Yes, Not Null, can be empty

Array(dict)
Each item is a dictionary with the following properties.
See detailed description of each property in the next rows:

path: …
group: …
readable: … (Optional)
writable: … (Optional)
mode: … (Optional, and not recommended, unless required for functionality)
KERNEL: …
SUBSYSTEM: … (Optional)
DRIVER: … (Optional)
SYMLINK: … (Optional)
parent: … (Optional)
dev_paths:
- path: r’/dev/dri/renderD[0-9]+’
group: ‘host1x-drm’
readable: yes
writable: yes
KERNEL: renderD[0-9]*
SUBSYSTEM: ‘drm’

sys_paths/other_pseudofs_paths

Yes, Not Null, can be empty

Array(dict)
Each item is a dictionary with the following properties
See detailed description of each property in the next rows

path: …
group: …
readable: … (Optional)
writable: … (Optional)
mode: … (Optional, and not recommended, unless required for functionality)
tmpfiles_glob: … (Optional, required if path is a regex)
sys_paths:
- path: r’/sys/devices/soc[0-9]+/soc_id’
group: ‘nvgpu-soc_id’
readable: yes
writable: no
tmpfiles_glob: /sys/devices/soc[0-9]*/soc_id
- path: …
other_pseudofs_paths:
- path: /proc/net/dev
group: ‘nv-net_dev’
readable: yes
writable: no
tmpfiles_glob: /proc/net/dev

path

Yes, Not empty

String/Regex
Path to the device node/sysfs node/pseudo-filesystem node
Ensure this path is the absolute path to the node. i.e. run realpath <path> on the target to ensure
there are no symlinks in the path.

If the path is not determinable statically, for example if the device is enumerated at runtime,
record this as a regex string. i.e. if the path is say /dev/i2c.<4 digit number>, then record it as r'/dev/i2c[0-9]{4}'.
Or for sysfs nodes, if the path is say /sys/devices/soc<>number>/soc_id, then record it as r'/sys/devices/soc[0-9]+/soc_id'.

Please see Regex Support below for more information
path: r’/dev/i2c[0-9]{4}’
path: r’/sys/devices/soc[0-9]+/soc_id’

group

Yes, Not empty

String
Group name that should protect the path during access
group: ‘nvgpu-soc_id’

readable

Optional, default is yes

Boolean
Whether the path is readable
‘yes’ will translate into ‘r’ bit being set for the node
‘no’ will translate into ‘r’ bit being cleared for the node
Example:
readable: yes
readable: no

writable

Optional, default is no

Boolean
Whether the path is writable
‘yes’ will translate into ‘w’ bit being set for the node
‘no’ will translate into ‘w’ bit being cleared for the node
Example:
- writable: yes
- writable: no

mode

Optional, default is “0o000” (Not recommended to use)

Octal String
Mode of the path
This is not recommended to use, unless required for functionality
This will set permission of the node to something else other than
the architecture derived defaults of ‘040’, ‘060’, ‘020’.
Use this to force some other bits to be set for the node
Example:
- mode: “0o644”
- mode: “0o666”

KERNEL

Yes, not empty

String
Kernel name of the device node: Reported by udev to identify the node.
This is required for dev_paths and only applicable for dev_paths.

udevadm info -a –name=/dev/<path>
Put KERNEL = “<First KERNEL>” reported by the tool
E.g.
$ udevadm info -a –name=/dev/dri/renderD128
looking at device ‘/devices/platform/bus@0/13e40000.host1x/drm/drm/renderD128’:
KERNEL==”renderD128”
SUBSYSTEM==”drm”
….
So KERNEL: renderD128 should be entry in YAML.

KERNEL supports glob patterns, one can specify renderD* to match nodes, if not known
at compile time.
KERNEL: renderD128
KERNEL: renderD*
KERNEL: sda*

SUBSYSTEM

Optional, default is empty

String
Subsystem name of the device node: Reported by udev to identify the node.
This is only applicable for dev_paths.

Use same method as KERNEL to get the SUBSYSTEM value.
This is only required if KERNEL is not unique for the node, for example while using glob patterns.
SUBSYSTEM: ‘drm’
SUBSYSTEM: ‘nvme’

DRIVER

Optional, default is empty

String
Driver name of the device node: Reported by udev to identify the node
This is only applicable for dev_paths.

Use same method as KERNEL to get the DRIVER value
This is only required if KERNEL is not unique for the node, for example while using glob patterns).
DRIVER: ‘drm’
DRIVER: ‘nvme’

SYMLINK

Optional, default is empty

String
This symlink will be created on the device for clients to interact with.
This is only applicable for dev_paths
This will force udev to create a symlink for the node with the name specified here.
Allows clients to interact with the node using the symlink name instead of the actual node name.
SYMLINK: ‘/dev/dri-render-host1x’
SYMLINK: ‘/dev/nvme0n1’

parent

Optional, default is empty

Dictionary
This is only applicable for dev_paths
This allows to specify the parent of the node, if node cannot be uniquely identified by KERNEL, SUBSYSTEM, and DRIVER.

E.g.
Udevadm info starts with the device specified by the devpath and then
walks up the chain of parent devices. It prints, for every device
found, all possible attributes in the udev rules key format.
A rule to match, can be composed by the attributes of the device
and the attributes from one single parent device.

sudo udevadm info -a –name=/dev/dri/renderD128
looking at device ‘/devices/platform/bus@0/13e40000.host1x/drm/drm/renderD128’:
KERNEL==”renderD128”
SUBSYSTEM==”drm”
…
KERNELS==”13e40000.host1x.drm”
SUBSYSTEMS==”host1x”
DRIVERS==”drm”

So in addition to KERNEL: renderD128, one can also specify
parent:
KERNEL: “*host1x.drm”
SUBSYSTEM: “host1x”
DRIVER: “drm”
to uniquely identify the node.
parent:
KERNEL: “*host1x.drm”
SUBSYSTEM: “host1x”
DRIVER: “drm”

tmpfiles_glob

Optional, required if path is a regex and it is a sysfs/other_pseudofs_path node

String
This is only applicable for sys_paths/other_pseudofs_paths
This allows to specify a glob pattern to match the path
This is only required if path is a regex

This is required since systemd-tmpfiles does not support regex and uses glob patterns
tmpfiles_glob: /sys/devices/soc[0-9]*/soc_id
if path is r’/sys/devices/soc[0-9]{1,2}/soc_id’

Process Information#

This document describes the processes that are expected to be launched when the target image is booted.

In production systems, there are no interfaces to launch processes, so documenting processes here creates systemd unit files for each process node, that launches the process during the boot process.

The unit file generated contains all the supplementary groups the process can take to access required items. It also contains the AppArmor profile name that should be used to restrict the process along with a bounding set of capabilities that should be set for the process.

version: 1.0
os: linux
doctype: process_information
element: Cust_Element::Sub_Element1
processeList:
  nv_virtual_shutdown:
    After:
      - service: systemd-udevd.service
        type: strong
      - service: systemd-modules-load.service
        type: strong
    Before: []
    Conditions:
      CompileConditions: {}
      RuntimeConditions:
        - ConditionPathExists: /dev/tegra_hv_pm_ctl
    ASIL: QM
    Priority: 0 #Keeping nice value 0 for now, max is 19, min is -20
    IsNetworkExposed: False
    User: system-state
    Rlimits:
      NOFILE: 10
    Executable: nv_linux_shutdown
    AdditionalSystemdArgs: # Refer to systemd.unit
      - StandardOutput: journal+console
      - StandardError: journal+console
      - SupplementaryGroups: tty #Add /dev/tty to communicate with /dev/console from upstream
    LaunchCmd: nv_linux_shutdown
    AccessControlDependencies:
      dev_paths: # First level dependencies of the process driver code itself (ignore libs)
        - /dev/tegra_hv_pm_ctl
      sys_paths:
        - /sys/power/mem_sleep
        - /sys/power/state
      other_pseudofs_paths: []
      capabilities:
        - CAP_SYS_BOOT:
            phase: RUN
        - CAP_KILL:
            phase: RUN
    ProcessSpecificFileDependencies:
        - /etc/shutdown/sc7_custom.conf
    ResourceOwnership:
      dev_paths: []
      sys_paths: []
      other_pseudofs_paths: []
Table 6 Process Information semantics#

Property

Required, Constraint

Type

Description

Example

element

Yes, Not empty

String
Name of the element.

Allowed characters: [a-zA-Z0-9_:-]
element: Cust_Element::Sub_Element1

processList

Yes, Not empty

Dictionary
A dictionary of processes with their information
processList:
nv_virtual_shutdown: …

<process>

Yes, Not empty

Dictionary
A dictionary with the following properties

See detailed description of each property in the next rows

After: …
Before: …
Conditions: …
ASIL: …
Priority: …
IsNetworkExposed: …
User: …
Rlimits: …
Executable: …
AdditionalSystemdArgs: …
LaunchCmd: …
AccessControlDependencies: …
ProcessSpecificFileDependencies: …
ResourceOwnership: …
nv_virtual_shutdown:
After: …
Before: …
Conditions: …
ASIL: …
Priority: …
IsNetworkExposed: …
…

After

Required, can be empty

Array(dict)
List of services that must be running before the process can start
Each item in the list can either be:
* dict
has property “id”: with value “String”, pointing to another “proces_instance_enty”
has property “type”: “strong/weak”, based on whether the process shouldn’t start if the dependent process failed or
if its just for ordering and it can start independent of the pass/fail status of the dependent process.
* dict
has property “service”: with value “String”, pointing to a systemd service name.
has property “type”: “strong/weak”, same as above.
After:
- id: nv_nvsciipc_init
type: strong
- service: systemd-modules-load.service
type: strong

Before

Required, can be empty

Array(dict)
List of services that must wait for the process to finish before they can start
Same format as After, type: strong implies a failure of this process will cause the other process to not start
Before:
- id: nv_nvsciipc_init
type: strong
- service: network.target
type: strong

Conditions

Required

Dictionary
Conditions that must be met for the process to start
has two keys:
- CompileConditions: …
- RuntimeConditions: …

CompileConditions set it to {} for now, as its unimplemented and might be removed
in the future.

RuntimeConditions are conditions that must be met at runtime while process starts
Refer to systemd.unit Conditions <https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#Conditions%20and%20Asserts>

Key: value is the same as the systemd documentation, = replaced with colon
Conditions:
- CompileConditions: {}
- RuntimeConditions:
- ConditionPathExists: /dev/tegra_hv_pm_ctl
- ConditionPathExists: /sys/devices/platform/tegra_hv_pm_ctl

ASIL

Required

Enum
ASIL level of the process
Valid values: [QM, A, B, C, D]
ASIL: QM

Priority

Required

Integer
This will range from -20 to 19. used to determine Nice value of the process.
Priority of the process. Keep 0 for now, as its for future use.
Priority: 0

IsNetworkExposed

Required

Enum
Whether the process is network exposed
Valid values: [yes, no]
Set to no for now, as its for future use.
IsNetworkExposed: no

User

Required

String, Not empty
User of the process to be launched
User: system-state

Rlimits

Required

Dictionary
Rlimits of the process
Set to {} for now, as its for future use.
Rlimits: {}

Executable

Required

String, Not empty
Executable of the process to be launched
Executable: nv_linux_shutdown

AdditionalSystemdArgs

Required, Not empty

Array(dict)
Additional arguments to be passed to systemd
Refer to systemd.unit for more information
Refer to systemd.service for more information

Key: value is the same as the systemd documentation, = replaced with colon
AdditionalSystemdArgs:
- StandardOutput: journal+console
- StandardError: journal+console

LaunchCmd

Required, Not empty

String
Commandline of the process to be launched.
LaunchCmd: nv_linux_shutdown –arg1 –arg2

AccessControlDependencies

Required

Dictionary
Access control dependencies of the process.
Dictionary with keys as dev_paths, sys_paths, other_pseudofs_paths, capabilities.

These keys are same as the ones in Library Access Control And Abilities Dependency Information.
Refer to that section for more information.
AccessControlDependencies:
dev_paths: …
sys_paths: …
other_pseudofs_paths: …
capabilities: …

ProcessSpecificFileDependencies

Required

Array(String/dict)
Process specific file dependencies of the process.
These are similar to file_dependencies in File Ownership And Dependency Information.
The ones in that documentation applies to each instance of the executable.
These are specific to this process and will be applied to the process alone.

Refer to File Ownership And Dependency Information file_dependencies attribute for more information.
ProcessSpecificFileDependencies:
- /etc/shutdown/sc7_custom.conf

ResourceOwnership

Optional

Dictionary
Resource ownership of the process.
These contain the properties dev_paths, sys_paths, other_pseudofs_paths.
These are similar to the entries in KMD Ownership Information.

Only difference being dev_paths also follow same format as sys_paths and other_pseudofs_paths
as udev doesn’t manage userspace dev/ nodes.
ResourceOwnership:
dev_paths: …
sys_paths: …
other_pseudofs_paths: …

IsTestUnit

Optional

Boolean
Whether the process is a test unit.
Default is False.
If set to True, the process will be considered as a test.
IsTestUnit: False

LaunchOnBoot

Optional

Boolean
Whether the process should be launched by systemd automatically on boot.
Specify False if the application is not to be launched on boot automatically,
but rather is invoked via some other application (or user for tests).
Default is True.

LaunchOnBoot: False

RemoveGroups

Optional

Array(String)
Groups to remove from the process
List of strings.
List of group names to be removed from the identified groups.
Only used when IsTestUnit: true. useful for negative testing.
This Removes the additional groups from the final list of groups.
RemoveGroups:
- group1
- group2

Dependency List#

In Library Access Control And Abilities Dependency Information, Process Information, File Ownership And Dependency Information sections of Security Config YAMLs, there are mechanisms of specifying the dev_paths, sys_paths, other_pseudofs_paths dependencies as a list. file_dependencies in case of File Ownership And Dependency Information document. The expected value of these keys are an array of paths as specified in the semantics of the doc. It can also be a dictionary specifying additional properties of the dependency and is recommended to be a dict if the dependency exposes multiple classes of functionalities.

Table 7 Dependency List semantics#

Property

Required, Constraint

Type

Description

func_class_mapping

Optional

Dictionary
Dictionary of function class mappings

Key: String
Functionality Class exposed by the component

Value: List of Strings
Each string is a Functionality Class exposed by the dependency item

Special Strings:
- all_func_classes: matches any function class of the object

This is beneficial if a library accesses multiple /dev/nodes.

Without this key added, an executable depending on the library will get assigned all the groups protecting each of the device node.

version: 1.0
os: linux
doctype: library_access_control_abilities_dependencies
element: Nvtzvault
libraryList:
    libnvtzvault.so:
        dev_paths:
            - /dev/nvtzvault-ta-00:
                func_class_mapping:
                    NVTZVAULT_TA_00: [all_func_classes]
            - /dev/nvtzvault-ta-01:
                func_class_mapping:
                    NVTZVAULT_TA_01: [all_func_classes]
            - /dev/nvtzvault-ta-02:
                func_class_mapping:
                    NVTZVAULT_TA_02: [all_func_classes]
            - /dev/nvtzvault-ta-03:
                func_class_mapping:
                    NVTZVAULT_TA_03: [all_func_classes]

version: 1.0
os: linux
doctype: file_ownership_and_dependencies
element: NVPKCS11
fileList:
    - destination: /usr/lib/libnvpkcs11.so
      source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/libnvpkcs11.so
      filetype: library
      shared: yes
      group: libnvpkcs11
      jama: DOS-SHR-8382
      purpose: NVIDIA PKCS11 library
      file_dependencies:
        - /usr/lib/libnvos.so
        - /usr/lib/libnvvse.so
        - /usr/lib/libnvsciipc.so
        - /usr/lib/libnvsocsys.so
        - /usr/lib/libteec.so
        - /usr/lib/libnvtzvault.so:
            func_class_mapping:
                NVPKCS11_DEFAULT_ACCESS: NVTZVAULT_DEFAULT_ACCESS
                SERVICE_CRYPTO_ASYM_UUID: [NVTZVAULT_TA_00]
                SERVICE_PKCS11_KEYSTORE_FSI_DYNAMIC_1_UUID: [NVTZVAULT_TA_03]

    - destination: /usr/local/bin/nvpkcs11_kat
      source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/filesystem/contents/bin/nvpkcs11_kat
      filetype: executable
      shared: no
      jama: DOS-SHR-8984
      purpose: NVPKCS11 Known Answer Test
      file_dependencies:
        - /usr/lib/libnvpkcs11.so:
            func_class_mapping:
                all_func_classes: [NVPKCS11_DEFAULT_ACCESS, SERVICE_CRYPTO_ASYM_UUID]

In the above example, nvpkcs11_kat depends on libnvpkcs11.so which in turn depends on libnvtzvault.so.

By default depending on libnvtzvault.so will gain access to all /dev/nvtzvault-* nodes opened by the library.

To prevent this behavior, func_class_mapping should be used to have more finer access control.

With the above implementation, nvpkcs11_kat only uses the class NVPKCS11_DEFAULT_ACCESS, SERVICE_CRYPTO_ASYM_UUID of libnvpkcs11.so which inturn maps to NVTZVAULT_DEFAULT_ACCESS,``NVTZVAULT_TA_00``.

This reduces the access of the application to only the library libnvtzvault.so and the first node /dev/nvtzvault-ta-00.

Regex Support#

The Regex used in this tool, doesn’t support the full list of regex features specified in python ‘re’. Its a subset of features since the tool is doing theoretical match of regex paths and hence all the backtrack options of ‘re’ are not supported.

PythonRegex supports the following regex features:

Basic Operations:

  • Concatenation: ab

  • Alternation: a|b

  • Kleene star: a*

Character Classes:

  • Standard bracket notation: [abc], [a-z]

  • Negated classes: [^0-9]

Predefined Character Classes:

  • \d - digits [0-9]

  • \D - non-digits [^0-9]

  • \s - whitespace [ \t]

  • \S - non-whitespace [^ \t]

  • \w - word characters [a-zA-Z0-9_]

  • \W - non-word characters [^a-zA-Z0-9_]

Quantifiers:

  • * - zero or more

  • + - one or more (converted to aa*)

  • ? - zero or one

  • {m} - exactly m occurrences

  • {m,n} - between m and n occurrences

  • {m,} - m or more occurrences

Grouping:

  • Parentheses for grouping: (abc)

Wildcards:

  • . - any character

Escaping:

  • Backslash to escape special characters: \

The implementation internally converts these patterns to a simplified representation using concatenation, alternation, and Kleene star operations.

Using Filters#

Tool supports filters to specify conditional updates on the entries based on parameters. Add to any entry in Security Config YAMLs. For example, add __filters__ to each file entry, library entry, process entry, kmd entry to specify conditional updates and enablement.

Table 8 Filters semantics#

Key

Required

Type

Description

__enabled__

Optional

Boolean
Should the entry be considered while creating the security configuration data
Default is True. If set to False, it would be as if the entry is not specified in the document.

__filters__

Optional

Array(dict)
Array of filters to specify conditional updates on the entries based on parameters.

Each filter is a dictionary with the following keys:
- __condition__: (Condition to be met)
<property>: <value>

<property> is one of the parameters that is present in the entry, to be specified in the same indendation level (Need to specify parent key if they exist),
which will be updated if the condition is met.
<value> is the value to be set for the property.

<value> will keep extending until it hits a non-dict, non-list item when it will replace the value.
Each item in the array will be traversed top-down like if(condition1) {update1}; if(condition2) {update2}; if(condition3) {update3};
All filter items are processed in the order they are specified in the array, if a condition is met, the update is applied and tool continues to process the next item in the array.
If no condition is met, the entry is considered as is.

__condition__:

Required (if __filters__ is specified)

Dictionary
Condition to be met

Key: pct_variant
Value: Array of strings from enum [dev_nsr, test_nsr, prod_nsr]
This checks if the current pct_variant is part of the array.
 
- destination: /usr/lib/nvsipl_drv/libnvsipl_qry_imx623c_max96792a.so
  source:
      pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/nvsipl_drv/libnvsipl_qry_imx623c_max96792a.so
  filetype: library
  shared: yes
  jama: 'DOS-SHR-7657'
  purpose: 'Camera SW SIPL Devblk Camera query library. SIPL needs this library to support IMX623C cameras. SIPL will not support the cameras without library'
  group: "cam_sipl-qry_imx623c_max96792a"
  file_dependencies:
    - /usr/lib/libnvsipl.so
  __enabled__: False
  __filters__:
    - __condition__:
        pct_variant: [dev_nsr, test_nsr]
      __enabled__: True
    - __condition__:
        pct_variant: [dev_nsr]
      source:
        pdk_sdk_installed_path: ${NV_SDK_NAME_LINUX}/lib-target/nvsipl_drv/libnvsipl_qry_imx623c_max96792a_debug.so
      file_dependencies:
        - /usr/lib/libnvsipl_debug.so

In this example, the library will be enabled for dev_nsr and test_nsr variants and disabled for prod_nsr variant. Also in case of dev_nsr variant, the library source will be updated to libnvsipl_qry_imx623c_max96792a_debug.so, so the debug library will be copied into the destination path specified instead of the default library. Also the file dependencies will be appended to include libnvsipl_debug.so, making the final file dependencies as /usr/lib/libnvsipl.so, /usr/lib/libnvsipl_debug.so.

Tool Outputs#

Tool generates the following categories of output. After bind_partitions you can check the contents of ${NV_WORKSPACE}/drive-linux/filesystem/out/security_config_tool_generated for the generated files.

Table 9 Tool Outputs#

Category

Description

Systemd Unit Files
One file per process to be launched in Drive OS Linux, it contains all the information to restrict the process in terms of its capabilities, memory etc
It also contains the ordering information for the sequence of the process
It also contains all the Supplementary Groups the process can take to access required items
These outputs will be the under the sub-folder services/.

Udev rules
Rules to configure the permission of /dev/ entries in the system to be minimal
These outputs will be the under the sub-folder udev/.

Systemd tmp files
Rules to configure the permission of /sys/ and other /run/ /proc entries in the system to be minimal
These outputs will be the under the sub-folder systemd-tmpfiles/.

Copytarget YAMLs
For copying fies from the host into the target filesystem image created on the host.
These outputs will be the under the sub-folder copytarget/.

AppArmor Rules
AppArmor rules to restrict the access to the processes in the target filesystem image.
These outputs will be the under the sub-folder apparmor/.
On this page