eyamlprocessor.py

1. Introduction
2. Public API
   1. Initialization
   2. Public Instance Methods
   3. Public Static Methods

Introduction

The eyamlprocessor.py file extends processor.py, enabling it to understand EYAML (Encrypted YAML) content. The document doesn't need to be encrypted, but where encrypted content is encountered, it can be processed given the necessary encryption key(s).

This class is found in the following name-space: yamlpath.eyaml.EYAMLProcessor

Public API

Initialization

This class' constructor has the following signature and documentation:

    def __init__(
        self, logger: ConsolePrinter, data: Any, **kwargs: Optional[str]
    ) -> None:
        """
        Instantiate an EYAMLProcessor.

        Parameters:
        1. logger (ConsolePrinter) Instance of ConsolePrinter or subclass
        2. data (Any) Parsed YAML data

        Keyword Arguments:
        * binary (str) The external eyaml command to use when performing
            data encryption or decryption; if no path is provided, the
            command will be sought on the system PATH.  Defaut="eyaml"
        * publickey (Optional[str]) Fully-qualified path to the public key
            for use with data encryption
        * privatekey (Optional[str]) Fully-qualified path to the public key
            for use with data decryption

        Returns:  N/A

        Raises:  N/A
        """

This class extends the base initialization of the parent Processor class by adding some named Keyword Arguments, described above.

Be aware of when you need to supply the public key, private key, or both. For example, when you intend to read or verify a value before encrypting its replacement, you must supply both keys.

Public Instance Methods

The EYAMLProcessor class exposes all public methods of the underlying Processor class along with these additional capabilities against the wrapped data:

• decrypt_eyaml:

    def decrypt_eyaml(self, value: str) -> str:
        """
        Decrypt an EYAML value.

        Parameters:
        1. value (str) The EYAML value to decrypt

        Returns:  (str) The decrypted value or the original value if it was not
            actually encrypted.

        Raises:
        - `EYAMLCommandException` when the eyaml binary cannot be utilized
        """

• encrypt_eyaml:

    def encrypt_eyaml(
        self, value: str,
        output: EYAMLOutputFormats = EYAMLOutputFormats.STRING
    ) -> str:
        """
        Encrypt a value via EYAML.

        Parameters:
        1. value (str) the value to encrypt
        2. output (EYAMLOutputFormats) the output format of the encryption

        Returns:  (str) The encrypted result or the original value if it was
            already an EYAML encryption.

        Raises:
        - `EYAMLCommandException` when the eyaml binary cannot be utilized.
        """

• find_eyaml_paths:

    def find_eyaml_paths(self) -> Generator[YAMLPath, None, None]:
        """
        Find every encrypted value and reports its YAML Path.

        Parameters:  N/A

        Returns:  (Generator[Path, None, None]) each YAML Path entry as they
            are discovered

        Raises:  N/A
        """

• get_eyaml_values:

    def get_eyaml_values(
        self, yaml_path: YAMLPath, mustexist: bool = False,
        default_value: str = ""
    ) -> Generator[str, None, None]:
        """
        Retrieve and decrypt all EYAML nodes identified via a YAML Path.

        Parameters:
        1. yaml_path (Path) The YAML Path specifying which nodes to decrypt
        2. mustexist (bool) Indicates whether YAML Path must specify a
           pre-existing node; when False, the node will be created when
           missing
        3. default_value (str) The default value to add to the YAML data
           when `mustexist=False` and yaml_path points to a non-existent
           node

        Returns:  (str) The decrypted value or `default_value` when YAML Path
            specifies a non-existant node

        Raises:
        - `YAMLPathException` when YAML Path is invalid
        """

• set_eyaml_value:

    def set_eyaml_value(
        self, yaml_path: YAMLPath, value: str,
        output: EYAMLOutputFormats = EYAMLOutputFormats.STRING,
        mustexist: bool = False
    ) -> None:
        """
        Encrypt and store a value where specified via YAML Path.

        Parameters:
        1. yaml_path (Path) The YAML Path specifying which nodes are to
           receive the encrypted value
        2. value (any) The value to encrypt
        3. output (EYAMLOutputFormats) the output format of the encryption
        4. mustexist (bool) Indicates whether YAML Path must
           specify a pre-existing node

        Returns:  N/A

        Raises:
        - `YAMLPathException` when YAML Path is invalid
        """

Public Static Methods

The EYAMLProcessor class provides the following public static methods:

• get_eyaml_executable:

    @staticmethod
    def get_eyaml_executable(binary: Optional[str] = "eyaml") -> Optional[str]:
        """
        Return the full executable path to an eyaml binary.

        Returns None when it cannot be found or is not executable.

        Parameters:
        1. binary (str) The executable to test; if an absolute or relative
           path is not provided, the system PATH will be searched for a
           match to test

        Returns: (str) None or the executable eyaml binary path

        Raises:  N/A
        """

• is_eyaml_value:

    @staticmethod
    def is_eyaml_value(value: str) -> bool:
        """
        Indicate whether a value is EYAML-encrypted.

        Parameters:
        1. value (any) The value to check

        Returns:  (bool) True when the value is encrypted; False, otherwise

        Raises:  N/A
        """