Encrypting data in state files and Pillars

GPG

GNU Privacy Guard (GnuPG, GPG) is free software for encrypting information and creating electronic digital signatures. GnuPG is present in all free operating systems, including GNU/Linux, and is distributed under the free GNU General Public License.

GnuPG is fully compliant with the IETF OpenPGP standard. Current versions of GnuPG can interoperate with PGP and other OpenPGP-compliant systems.

The main functions of GnuPG are:

creating key pairs,
exchanging and verifying keys,
encrypting and decrypting messages and documents,
authenticating documents using digital signatures.

How GPG works

GnuPG uses public-key cryptography.
In a public key system, each user has a pair of keys: a private key and a public key.

The private key is needed by the user to decrypt messages encrypted with his public key that are sent to him by other users. The private key must be kept secret and should not be disclosed to other users under any circumstances. The public key can be given by the user to any of his correspondents to encrypt messages which are sent to the user.

GnuPG uses a scheme in which the user has a primary key and zero or more additional subordinate keys. The primary and subordinate key pairs are combined to simplify key management, and this combination can often be thought of as just a single key pair.

SaltStack GPG Renderer

Generating GPG-keys for SaltStack

To create a new GPG key pair for encrypting data, log in to the master as root and run the following:

Create a directory to store keys:
```
mkdir -p /etc/salt/gpgkeys
```
Disable any access rights to the directory for users of the owner's group and other users:
```
chmod 0700 /etc/salt/gpgkeys
```
Generate and save GPG keys in the created directory:
```
gpg --homedir /etc/salt/gpgkeys --gen-key
```

After running the gpg utility, follow these steps:

Select the type of key to create.
You should select one of the two options: RSA and RSA or DSA and Elgamal.
A key marked sign only is not suitable: you need a key that supports data encryption, not just signing:

sudo gpg --gen-key --homedir /etc/salt/gpgkeys
gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

gpg: keyring `/etc/salt/gpgkeys/secring.gpg' created
gpg: keyring `/etc/salt/gpgkeys/pubring.gpg' created
Please select what kind of key you want:
  (1) RSA and RSA (default)
  (2) DSA and Elgamal
  (3) DSA (sign only)
  (4) RSA (sign only)

Specify the key size in bits.
It is recommended to use a key size of 4096 bits:

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)

Set the key expiration date:

Please specify how long the key should be valid.
        0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)

Specify the key owner details:

GnuPG needs to construct a user ID to identify your key.

Real name: SaltBox
Email address: saltbox@example.local
Comment: "SaltBox KEY"
You selected this USER-ID:
    "SaltBox (SaltBox KEY) <saltbox@example.local>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?

Next, the key creation utility will ask for a passphrase for the key.
Leave the field blank and confirm the key creation.

Verify that the key has been created.
The output of the commands below should contain the created SaltBox key:

gpg --homedir /etc/salt/gpgkeys --list-keys
gpg --homedir /etc/salt/gpgkeys --list-secret-keys

Below is an example of the gpg --homedir /etc/salt/gpgkeys --list-keys command output when it runs successfully.

sec    4096R/3B42DC0F0 2025-04-15
uid                    SaltBox (SaltBox KEY) <saltbox@example.local>
ssb    4096R/3767D6BA  2025-04-15

Below is an example of the gpg --homedir /etc/salt/gpgkeys --list-secret-keys command output when it runs successfully.

sec    4096R/3B42DC0F0 2025-04-15
uid                    SaltBox (SaltBox KEY) <saltbox@example.local>
ssb    4096R/3767D6BA  2025-04-15

Create a public key for data encryption based on the newly created private key:
```
sudo gpg --homedir /etc/salt/gpgkeys --armor --export  > saltBox.gpg
```
The created public key can be given to users on whose side the data encryption will be performed (usually these are the SaltStack administrators who write the state files).
Import the GPG key into the user profile

Run the command with user rights:
```
gpg --import saltBox.gpg
```
Make sure the key was imported successfully:
```
gpg --list-keys
```

Encrypting data using a public key

Data encryption is performed by the following command:

echo -n "encrypted_password" | gpg --trust-model always -ear 'SaltBox'

Below is an example of the command output when it runs successfully.

The text starting with the line -----BEGIN PGP MESSAGE-----
and ending with the line -----END PGP MESSAGE----- must be copied in full (along with the specified lines) and pasted into the file containing the required pillar (See the Encrypted pillar SLS example for details).

SaltStack Pillar Encryption

Salt's renderer system can be used to decrypt pillar data.
This allows for pillar items to be stored in an encrypted state, and decrypted during pillar compilation.

Encrypted pillar SLS

# pillars/top.sls
secrets:
  vault:
    foo: |
      -----BEGIN PGP MESSAGE-----

      hQEMAw2B674HRhwSAQgAhTrN8NizwUv/VunVrqa4/X8t6EUulrnhKcSeb8sZS4th
      W1Qz3K2NjL4lkUHCQHKZVx/VoZY7zsddBIFvvoGGfj8+2wjkEDwFmFjGE4DEsS74
      ZLRFIFJC1iB/O0AiQ+oU745skQkU6OEKxqavmKMrKo3rvJ8ZCXDC470+i2/Hqrp7
      +KWGmaDOO422JaSKRm5D9bQZr9oX7KqnrPG9I1+UbJyQSJdsdtquPWmeIpamEVHb
      VMDNQRjSezZ1yKC4kCWm3YQbBF76qTHzG1VlLF5qOzuGI9VkyvlMaLfMibriqY73
      zBbPzf6Bkp2+Y9qyzuveYMmwS4sEOuZL/PetqisWe9JGAWD/O+slQ2KRu9hNww06
      KMDPJRdyj5bRuBVE4hHkkP23KrYr7SuhW2vpe7O/MvWEJ9uDNegpMLhTWruGngJh
      iFndxegN9w==
      =bAuo
      -----END PGP MESSAGE-----
    bar: this was unencrypted already
    baz: |
      -----BEGIN PGP MESSAGE-----

      hQEMAw2B674HRhwSAQf+Ne+IfsP2IcPDrUWct8sTJrga47jQvlPCmO+7zJjOVcqz
      gLjUKvMajrbI/jorBWxyAbF+5E7WdG9WHHVnuoywsyTB9rbmzuPqYCJCe+ZVyqWf
      9qgJ+oUjcvYIFmH3h7H68ldqbxaAUkAOQbTRHdr253wwaTIC91ZeX0SCj64HfTg7
      Izwk383CRWonEktXJpientApQFSUWNeLUWagEr/YPNFA3vzpPF5/Ia9X8/z/6oO2
      q+D5W5mVsns3i2HHbg2A8Y+pm4TWnH6mTSh/gdxPqssi9qIrzGQ6H1tEoFFOEq1V
      kJBe0izlfudqMq62XswzuRB4CYT5Iqw1c97T+1RqENJCASG0Wz8AGhinTdlU5iQl
      JkLKqBxcBz4L70LYWyHhYwYROJWjHgKAywX5T67ftq0wi8APuZl9olnOkwSK+wrY
      1OZi
      =7epf
      -----END PGP MESSAGE-----
    qux:
      - foo
      - bar
      - |
        -----BEGIN PGP MESSAGE-----

        hQEMAw2B674HRhwSAQgAg1YCmokrweoOI1c9HO0BLamWBaFPTMblOaTo0WJLZoTS
        ksbQ3OJAMkrkn3BnnM/djJc5C7vNs86ZfSJ+pvE8Sp1Rhtuxh25EKMqGOn/SBedI
        gR6N5vGUNiIpG5Tf3DuYAMNFDUqw8uY0MyDJI+ZW3o3xrMUABzTH0ew+Piz85FDA
        YrVgwZfqyL+9OQuu6T66jOIdwQNRX2NPFZqvon8liZUPus5VzD8E5cAL9OPxQ3sF
        f7/zE91YIXUTimrv3L7eCgU1dSxKhhfvA2bEUi+AskMWFXFuETYVrIhFJAKnkFmE
        uZx+O9R9hADW3hM5hWHKH9/CRtb0/cC84I9oCWIQPdI+AaPtICxtsD2N8Q98hhhd
        4M7I0sLZhV+4ZJqzpUsOnSpaGyfh1Zy/1d3ijJi99/l+uVHuvmMllsNmgR+ZTj0=
        =LrCQ
        -----END PGP MESSAGE-----

When the pillar data is compiled, the results will be decrypted:

$: salt myminion pillar.items

myminion:
    ----------
    secrets:
        ----------
        vault:
            ----------
            bar:
                this was unencrypted already
            baz:
                rosebud
            foo:
                supersecret
            qux:
                - foo
                - bar
                - baz

References

Wikipedia article about GnuPG
GnuPG Manual
SaltStack Pillar Encryption
SaltSTack GPG Renderer

GPG​

How GPG works​

SaltStack GPG Renderer​

Generating GPG-keys for SaltStack​

Encrypting data using a public key​

SaltStack Pillar Encryption​

Encrypted pillar SLS​

References​

GPG