PSL language syntax

Basic rules

1. Declarations can be listed in any sequence in a file.
2. One declaration can be written to one or multiple lines. The second and subsequent lines of the declaration must be written with indentations relative to the first line. The closing brace that completes the declaration can be written on the first line.
3. A multi-line declaration utilizes different-sized indentations to reflect the nesting of constructs comprising this declaration. The second and subsequent lines of a multi-line construct enclosed in braces must be written with an indentation relative to the first line of this construct. The closing brace of a multi-line construct can be written with an indentation or on the first line of the construct.
4. The PSL language is case sensitive.
5. Single-line comments and multi-line comments are supported:

   /* This is a comment

   * And this, too */

   // Another comment

Types of declarations

The PSL language has declarations for the following purposes:

• Describing the global parameters of a solution security policy
• Including PSL files
• Including EDL files
• Creating security model objects
• Binding methods of security models to security events
• Describing security audit profiles
• Describing solution security policy tests

Describing the global parameters of a KasperskyOS-based solution security policy

Global parameters include the following parameters of a solution security policy:

• Execute interface used by the KasperskyOS kernel when querying the Kaspersky Security Module to notify it about kernel startup or about initiating the startup of a process by the kernel or by other processes. To assign this interface, use the following declaration:

  execute: kl.core.Execute

  KasperskyOS currently supports only one execute interface (Execute) defined in the file named kl/core/Execute.idl. (This interface consists of one main method, which has no parameters and does not perform any actions. The main method is reserved for potential future use.)

• [Optional] Global security audit profile and initial security audit runtime-level. To define these parameters, use the following declaration:

  audit default = <security audit profile name> <security audit runtime-level>

  Example:

  audit default = global 0

  The default global profile is the empty security audit profile described in the file named toolchain/include/nk/base.psl from the KasperskyOS SDK, and the default security audit runtime-level is 0.

Including PSL files

To include a PSL file, use the following declaration:

The link to the PSL file is the file path (without the extension and dot before it) relative to the directory that is included in the set of directories where the nk-psl-gen-c compiler searches for PSL, IDL, CDL, and EDL files. (This set of directories is defined by the parameters -I <path to files> when starting the makekss script or the nk-psl-gen-c compiler.) A dot is used as a separator in a path description. A declaration is ended by the ._ character sequence.

Example:

This declaration includes the flow_part.psl file, which is located in the policy_parts directory. The policy_parts directory must reside in one of the directories where the nk-psl-gen-c compiler searches for PSL, IDL, CDL, and EDL files. For example, the policy_parts directory may reside in the same directory as the PSL file containing this declaration.

Including a PSL file containing a formal description of a security model

To use the methods of a required security model, you need to include a PSL file containing a formal description of this model. PSL files containing formal descriptions of security models are located in the KasperskyOS SDK at the following path:

toolchain/include/nk

Example:

Including EDL files

To include an EDL file for the KasperskyOS kernel, use the following declaration:

To include an EDL file for a program (such as a driver or application), use the following declaration:

The link to the EDL file is the EDL file path (without the extension and dot before it) relative to the directory that is included in the set of directories where the nk-psl-gen-c compiler searches for PSL, IDL, CDL, and EDL files. (This set of directories is defined by the parameters -I <path to files> when starting the makekss script or the nk-psl-gen-c compiler.) A dot is used as a separator in a path description.

Example:

The nk-psl-gen-c compiler finds IDL and CDL files via EDL files because EDL files contain links to the corresponding CDL files, and the CDL files contain links to the corresponding CDL and IDL files.

Creating security model objects

To call the methods of a required security model, create an object for this security model.

To create a security model object, use the following declaration:

The parameters of a security model object are specific to the security model. A description of parameters and examples of creating objects of various security models are provided in the "KasperskyOS security models" section.

Binding methods of security models to security events

To create an attachment between methods of security models and a security event, use the following declaration:

Security event type

The following specifiers are used to define the security event type:

• request – sending IPC requests.
• response – sending IPC responses.
• error – sending IPC responses containing information about errors.
• security – processes querying the Kaspersky Security Module via the security interface.
• execute – initializing the startups of processes or the startup of the KasperskyOS kernel.

Security event selectors

Security event selectors let you clarify the description of the defined type of security event. The following selectors are used:

• src=<kernel/process class name> – processes of the defined class or the KasperskyOS kernel are the sources of IPC messages.
• dst=<kernel/process class name> – processes of the defined class or the kernel are the recipients of IPC messages.
• interface=<interface name> – describes the following security events:
  • Clients attempt to use the endpoints of servers or the kernel with the defined interface.
  • Processes query the Kaspersky Security Module via the defined security interface.
  • The kernel or servers send clients the results from using the endpoints with the defined interface.
• component=<component name> – describes the following security events:
  • Clients attempt to use the core or server endpoints provided by the defined component.
  • The kernel or servers send clients the results from using the endpoints provided by the defined component.
• endpoint=<qualified endpoint name> – describes the following security events:
  • Clients attempt to use the defined core or server endpoints.
  • The kernel or servers send clients the results from using the defined endpoint.
• method=<method name> – describes the following security events:
  • Clients attempt to query servers or the kernel by calling the defined method of the endpoint.
  • Processes query the security module by calling the defined method of the security interface.
  • The kernel or servers send clients the results from calling the defined method of the endpoint.
  • The kernel notifies the security module about its startup by calling the defined method of the execute interface.
  • The kernel initiates the startup of processes by calling the defined method of the execute interface.
  • Processes initiate the startup of other processes, which results in the kernel calling the defined method of the execute interface.

Process classes, components, instances of components, interfaces, endpoints, and methods must be named the same as they are in the IDL, CDL, and EDL descriptions. The kernel must be named kl.core.Core.

The qualified name of the endpoint has the format <path to endpoint.endpoint name>. The path to the endpoint is a sequence of component instance names separated by dots. Among these component instances, each subsequent component instance is embedded into the previous one, and the last one provides the endpoint with the defined name.

For security events, specify the qualified name of the security interface method if you need to use the security interface defined in a CDL description. (If you need to use a security interface defined in an EDL description, it is not necessary to specify the qualified name of the method.) The qualified name of a security interface method is a construct in the format <path to security interface.method name>. The path to the security interface is a sequence of component instance names separated by dots. Among these component instances, each subsequent component instance is embedded into the previous one, and the last one supports the security interface that includes the method with the defined name.

If selectors are not specified, the participants of a security event may be any process and the kernel (except security events in which the kernel cannot participate).

You can use combinations of selectors. Selectors can be separated by commas.

There are restrictions on the use of selectors. The interface, component, and endpoint selectors cannot be used for security events of the execute type. The dst, component, and endpoint selectors cannot be used for security events of the security type.

There are also restrictions on combinations of selectors. For security events of the request, response and error types, the method selector can only be used together with one of the endpoint, interface, or component selectors or a combination of them. (The method, endpoint, interface and component selectors must be coordinated. In other words, the method, endpoint, interface, and component must be interconnected.) For security events of the request type, the endpoint selector can be used only together with the dst selector. For security events of the response and error types, the endpoint selector can be used only together with the src selector.

To ensure that IPC messages of the same type correspond to a security event description, one of the following conditions must be fulfilled for this description:

• For events of the request, response and error type, the "interface method-endpoint-server class or kernel" chain is unequivocally defined. For example, the security event description request dst=Server endpoint=net.Net method=Send corresponds to IPC messages of the same type, and the security event description request dst=Server corresponds to any IPC message sent to the Server.
• For security events, the security interface method is specified.
• The execute-interface method is indicated for execute events.

  There is currently support for only one fictitious method of the main execute-interface. This method is used by default, so it does not have to be defined through the method selector. This way, any description of an execute security event corresponds to IPC messages of the same type.

Security audit profile

A security audit profile is defined by the construct audit <security audit profile name>. If a security audit profile is not defined, the global security audit profile is used.

Called security model rules

Called security model rules are defined by a list from the following type of constructs:

Input data for security model rules may be values returned by security model expressions. The following construct is used to call a security model expression:

Parameters of interface methods can also be used as input data for methods of security models (rules and expressions). (For details about obtaining access to parameters of interface methods, see "Struct security model"). In addition, input data for methods of security models can also be the SID values of processes and the KasperskyOS kernel that are defined by the src_sid and dst_sid reserved words. The first reserved word refers to the SID of the process (or kernel) that is the source of the IPC message. The second reserved word refers to the SID of the process (or kernel) that is the recipient of the IPC message (dst_sid cannot be used for queries to the Kaspersky Security Module).

Embedded constructs for binding methods of security models to security events

In one declaration, you can bind methods of security models to different security events of the same type. To do so, use the match sections that consist of the following types of constructs:

Match sections can be embedded into another match section. A match section simultaneously uses its own security event selectors and the security event selectors at the level of the declaration and all match sections in which this match section is "wrapped". By default, a match section applies the security audit profile of its own container (match section of the preceding level or the declaration level), but you can define a separate security audit profile for the match section.

In one declaration, you can define different variants for processing a security event depending on the conditions in which this event occurred (for example, depending on the state of the finite-state machine associated with the resource). To do so, use the conditional sections that are elements of the following construct:

The choice construct can be used within a match section. A conditional section uses the security event selectors and security audit profile of its own container, but you can define a separate security audit profile for a conditional section.

If multiple conditions described in the choice construct are simultaneously fulfilled when a security event is processed, only the one conditional section corresponding to the first matching condition on the list is triggered.

Examples of binding security model methods to security events

See "Examples of binding security model methods to security events", "Example descriptions of basic security policies for KasperskyOS-based solutions", and "KasperskyOS security models".

Describing security audit profiles

To perform a security audit, you need to associate security model objects with security audit profile(s). A security audit profile (hereinafter also referred to as an audit profile) combines security audit configurations (hereinafter also referred to as audit configurations), each of which defines the security model objects covered by the audit, and specifies the conditions for conducting the audit. You can define a global audit profile (for more details, see "Describing the global parameters of a KasperskyOS-based solution security policy") and/or assign audit profile(s) at the level of binding security model methods to security events, and/or assign audit profile(s) at the level of match sections or choice sections (for more details, see "Binding methods of security models to security events").

To describe a security audit profile, use the following declaration:

Security audit runtime-level

The security audit runtime-level (hereinafter referred to as the audit runtime-level) is a global parameter of a solution security policy and consists of an unsigned integer that defines the active security audit configuration. (The word "runtime-level" here refers to the configuration variant and does not necessarily involve a hierarchy.) The audit runtime-level can be changed during operation of the Kaspersky Security Module. This is done by using a specialized method of the Base security model that is called when processes query the security module via the security interface (for more details, see "Base security model"). The initial audit runtime-level is assigned together with the global audit profile (for more details, see "Describing the global parameters of a KasperskyOS-based solution security policy"). An empty audit profile can be explicitly assigned as the global audit profile.

You can define multiple audit configurations in an audit profile. In different configurations, different security model objects can be covered by the audit and different conditions for conducting the audit can be applied. Audit configurations in a profile correspond to different audit runtime-levels. If a profile does not have an audit configuration corresponding to the current audit runtime-level, the security module will activate the configuration that corresponds to the next-lowest audit runtime-level. If a profile does not have an audit configuration for an audit runtime-level equal to or less than the current level, the security module will not use this profile (in other words, an audit will not be performed for this profile).

Audit runtime-levels can be used to regulate the level of detail of an audit, for example. The higher the audit runtime-level, the higher the level of detail. The higher the level of detail, the more security model objects are covered by the audit and/or the less restrictions are applied in the audit conditions.

Another example of applying audit runtime-levels is the capability to shift the audit from one subsystem to another subsystem (for example, shift an audit related to drivers to an audit related to applications, or shift an audit related to the network subsystem to an audit related to the graphic subsystem).

Name of the security model object

The security model object name is indicated so that the methods provided by this object can be covered by the audit. These methods will be covered by the audit whenever they are called, provided that the conditions for conducting the audit are observed.

Security audit conditions

Security audit conditions are defined separately for each object of a security model.

To define the audit conditions related to the results from calling security model rules, use the following constructs:

• ["granted"] – the audit is performed if the rules return the "granted" result.
• ["denied"] – the audit is performed if the rules return the "denied" result.
• ["granted", "denied"] – the audit is performed if the rules return the "granted" or "denied" result.
• [] – the audit is not performed, regardless of the result returned by the rules.

Audit conditions related to results from calling rules are not applied to expressions. These conditions must be defined (by any allowed construct) even if the security model contains only expressions because PSL language syntax requires it.

Audit conditions specific to security models are defined by constructs specific to these models (for more details, see KasperskyOS Security models). These conditions apply to rules and expressions. For example, one of these conditions can be the state of a finite-state machine.

Security audit profile for a security audit route

A security audit route includes the kernel and the Klog and KlogStorage processes, which are connected by IPC channels based on the "kernel – Klog – KlogStorage" scheme. Security model methods that are associated with transmission of audit data via this route must not be covered by the audit. Otherwise, this will lead to an avalanche of audit data because any data transmission will give rise to new data.

To "suppress" an audit that was defined by a profile with a wider scope (for example, by a global profile or a profile at the level of binding security model methods to a security event), you need to assign an empty audit profile at the level of binding security model methods to security events or at the level of the match section or choice section.

Example descriptions of audit profiles

See Example descriptions of security audit profiles.

Describing and performing tests for a KasperskyOS-based solution security policy

A solution security policy is tested to verify whether or not the policy actually allows what should be allowed and denies what should be denied.

To describe a set of tests for a solution security policy, you need to use the following declaration:

You can describe multiple sets of tests by using several of these declarations.

The test set description can optionally include the initial part of the tests and/or the final part of the tests. The execution of each test from the set begins with whatever is described in the initial part of the test and ends with whatever is described in the final part of the test. This lets you describe the repeated initial and/or final parts of tests in each test.

Each test includes one or more test cases.

Test cases

A test case associates a security event description and values of interface method parameters with an expected decision of the Kaspersky Security Module. If the actual security module decision matches the expected decision, the test case passes. Otherwise it fails.

When a test is run, the test cases are executed in the same sequence in which they are described. In other words, you can test how the security module handles a sequence of security events.

If all test cases within a test pass, the test passes. If even one test case fails to pass, the test fails. A test is terminated on the first failing test case.

A test case description is created in the PAL language and is comprised of a sequence of values:

The expected decision of the security module can be indicated as grant ("granted"), deny ("denied") or any ("any decision"). If the expected security module decision is not specified, the "granted" decision is expected. If the any value is specified, the security module decision does not have any influence on whether or not the test case passes. In this case, the test case may fail due to errors that occur when the security module processes an IPC message (for example, when the IPC message has an invalid structure).

For information about the types and selectors of security events, and about the limitations when using selectors, see Binding methods of security models to security events. Selectors must ensure that the security event description corresponds to IPC messages of the same type. (When security model methods are bound to security events, selectors may fail to ensure this.)

In security event descriptions, you need to specify the SID instead of the process class name (and the KasperskyOS kernel). However, this requirement does not apply to execute events for which the SID of the started process (or kernel) is unknown. To save the SID of the process or kernel to a variable, you need to use the <- operator in the test case description in the following format:

The SID value will be assigned to the variable even if startup of the process of the defined class (or kernel) is denied by the tested policy but the "denied" decision is expected.

The PAL language supports abbreviated forms of security event descriptions:

• security: <Process SID> ! <qualified name of security interface method> corresponds to security src=<process SID> method=<qualified name of security interface method>.
• request: <client SID> ~> <kernel/server SID> : <qualified name of endpoint.method name> corresponds to request src=<client SID> dst=<kernel/server SID> endpoint=<qualified name of endpoint> method=<method name>.
• response: <client SID> <~ <kernel/server SID> : <qualified name of endpoint.method name> corresponds to response src=<kernel/server SID> dst=<client SID> endpoint=<qualified name of endpoint> method=<method name>.

If an interface method has parameters, their values are defined by comma-separated constructs:

The names and types of parameters must comply with the IDL description. The sequence order of parameters is not important.

Example definition of parameter values

In this example, the number is passed through the param1 parameter. The string buffer is passed through the param2 parameter. A structure consisting of two fields is passed through the param3 parameter. The collection field contains an array or sequence of three numeric elements. The filehandle field contains the SID. A union or structure containing one field is passed through the param4 parameter. The name field contains an array or sequence of two string buffers.

Example descriptions of policy tests

See "Example descriptions of tests for KasperskyOS-based solution security policies".

Test procedure

Descriptions of tests are placed into PSL files, including those that contain a solution security policy description (for example, into the security.psl file).

To run tests, you need to use the --tests run parameter when starting the nk-psl-gen-c compiler:

You also need to indicate the following data for the nk-psl-gen-c compiler:

• Directories that contain auxiliary files from the KasperskyOS SDK (common, sysroot-*-kos/include, toolchain/include). This set of directories is defined by the parameters -I, -include-dir <path to files>.
• Directories that contain PSL, IDL, CDL, and EDL files related to the solution. This set of directories is defined by the parameters -I, --include-dir <path to files>.
• Path to the file that will save the source code of the Kaspersky Security Module and tests. This path is defined by the parameter -o, --output <path to file>.

The nk-psl-gen-c compiler generates the source code of the security module and tests in the C language, saves this code to a file, and then runs the compilation of this code using gcc and executes the obtained test program. The test program is run in an environment where the KasperskyOS SDK is installed (on a computer running a Linux operating system). It does not utilize the KasperskyOS kernel, system software or applications of the solution.

To generate the source code of the security module and tests without compiling it, you need to use the --tests generate parameter when starting the nk-psl-gen-c compiler.

Test results are printed to the console. To print the test results to a file, you need to use the --test-output <path to file> parameter when starting the nk-psl-gen-c compiler.

Example test results:

The test results contain information about whether or not each test passed or failed. If a test failed, the results indicate which test case from the specific test did not pass, and provide the location of the description of the failed test case in the PSL file.

PSL data types

The data types supported in the PSL language are presented in the table below.

PSL data types

Aliases of certain PSL types

The nk/base.psl file from the KasperskyOS SDK defines the data types that are used as the types of parameters (or structural elements of parameters) and returned values for methods of various security models. Aliases and definitions of these types are presented in the table below.

Aliases and definitions of certain data types in PSL

Mapping IDL types to PSL types

Data types of the IDL language are used to describe the parameters of interface methods. The input data for security model methods have types from the PSL language. The set of data types in the IDL language differs from the set of data types in the PSL language. Parameters of interface methods transmitted in IPC messages can be used as input data for methods of security models, so the policy description developer needs to understand how IDL types are mapped to PSL types.

Integer types of IDL are mapped to integer types of PSL and to variant types of PSL that combine these integer types (including with other types). For example, signed integer types of IDL are mapped to the Signed type in PSL, and integer types of IDL are mapped to the ScalarLiteral type in PSL.

The Handle type in IDL is mapped to the HandleDesc type in PSL.

Unions and structures of IDL are mapped to PSL dictionaries.

Arrays and sequences of IDL are mapped to arrays and sequences of PSL, respectively.

String buffers in IDL are mapped to the text type in PSL.

Byte buffers in IDL are not currently mapped to PSL types, so the data contained in byte buffers cannot be used as inputs for security model methods.

Examples of binding security model methods to security events

Processing the initiation of process startups

Handling the startup of the KasperskyOS kernel

Handling IPC request forwarding

Handling IPC response forwarding

Handling the transmission of IPC responses containing error information

Handling queries sent by processes to the Kaspersky Security Module

Using match sections

Assigning audit profiles

Example descriptions of basic security policies for KasperskyOS-based solutions

Example 1

The solution security policy in this example allows any interaction between different processes of the Client, Server and Einit classes, and between these processes and the KasperskyOS kernel. The "granted" decision will always be received when these processes query the Kaspersky Security Module. This policy can be used only as a stub during the early stages of development of a KasperskyOS-based solution so that the Kaspersky Security Module does not interfere with interactions. It would be unacceptable to apply such a policy in a real-world KasperskyOS-based solution.

security.psl

Example 2

The solution security policy in this example imposes limitations on queries sent from clients of the FsClient class to servers of the FsDriver class. When a client opens a resource controlled by a server of the FsDriver class, a finite-state machine in the unverified state is associated with this resource. A client of the FsClient class is allowed to read data from a resource controlled by a server of the FsDriver class only if the finite-state machine associated with this resource is in the verified state. To switch a resource-associated finite-state machine from the unverified state to the verified state, a process of the FsVerifier class needs to query the Kaspersky Security Module.

In a real-world KasperskyOS-based solution, this policy cannot be applied because it allows an excessive variety of interactions between different processes and between processes and the KasperskyOS kernel.

security.psl

Example descriptions of security audit profiles

Example 1

Example 2

Example descriptions of tests for KasperskyOS-based solution security policies

Example 1

Example 2

Example 3