# Credentials File Encryption

NetObserv SNMP Trap supports easy and secure trap listener credentials file encryption using SOPs and industry-standard AGE.

### Getting Started

#### Environmental Dependencies

1. Ensure [sops](https://github.com/getsops/sops) is installed in your local environment:

   ```shell
   # Change sops-v3.8.1.linux.amd64 if needed based on your environment
   curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.linux.amd64
   sudo mv sops-v3.8.1.linux.amd64 /usr/local/bin/sops
   sops --version # to verify install
   ```
2. Also ensure [age](https://github.com/FiloSottile/age) is installed in your local environment to edit via CLI:

   ```shell
   sudo apt install age # Debian based linux
   brew install age # macos
   age --version # to verify install
   ```

#### Trap Listener Credentials Encryption Configuration

Please visit [Trap Listener Credentials Encryption](https://github.com/elastiflow/documentation/blob/main/docs/config_ref/trapcoll/credential_file_encryption/README.md) to learn more.

### Recommended Usage

**Tip**: Always keep a secured backup of a non-encrypted version of the credentials file in case of any issues.

#### Setup

The easiest and most recommended way to get started is to simply set the following as below:

```shell
EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_ENABLE=true
EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_CREATE=true
EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_PASSWORD="YourPassword"
EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_PRIVATE_KEY_FILE_PATH="/etc/elastiflow/snmp/traps/.age/key.age"
EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_PUBLIC_KEY_FILE_PATH="/etc/elastiflow/snmp/traps/.age/public-age-keys.txt"
```

The following behavior will occur when the Trap collector is next restarted:

1. Generate password protected age keys at the configured credentials file paths.
2. Encrypt trap listener credential yaml files using those keys.

Once successfully encrypted with sops, the following listener credential file:

```yaml
credentials:
  users:
    - username: myuser2
      authentication_protocol: md5
      authentication_passphrase: mypassword2
      privacy_protocol: aes
      privacy_passphrase: myprivacy2
      authoritative_engine_id: authoritative_engine_id
```

* Will resemble the yaml below if using the default `sops` setting for `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_TYPE`:

```yaml
credentials:
  users:
    - username: ENC[AES256_GCM,data:B052jkhy4g==,iv:pcfami0QKG4TNRDre56mPUMyohUbnhUpZftAbZlRAFk=,tag:5EimGwktVw/GQ7kYj0k4rA==,type:str]
      authentication_protocol: ENC[AES256_GCM,data:LSfR,iv:Afp733FCUgvsgXJ7TBMa++W/fTNk8H68lGp/VYzaf70=,tag:JiORrsCG4I//uaygFWiIIQ==,type:str]
      authentication_passphrase: ENC[AES256_GCM,data:EuKcz8vsM5z5wAE=,iv:0GSAxu5/hn8OVoCIGrUGInvxGoY/frlJIXqTjDN9i3s=,tag:chIwUWMppBh9Olg26GwkOw==,type:str]
      privacy_protocol: ENC[AES256_GCM,data:9xyn,iv:vZw9m8W23yMyeOa9eXJIeGSy+IbddjbBoFXL4XVA3MI=,tag:IGMgiRLETWdfPO1VY6sGxA==,type:str]
      privacy_passphrase: ENC[AES256_GCM,data:7aQ5a0RAaBTEAQ==,iv:GzfYtnmMzvB4SrtZPAXHfjXuegFcuiMIW7pGJmXSIhc=,tag:J4BjEYX5RzW4ZkcBOooIqQ==,type:str]
      authoritative_engine_id: ENC[AES256_GCM,data:ILoVUxpuDvQy/c67DkxswEHsxgsi5ck=,iv:e8Kctcdbo18T+wvA0oNqSCDfNRdtO1WKS1ATuGKVSuU=,tag:L8ggZusCIfFLFdPM8eSXIw==,type:str]
sops:
  kms: []
  gcp_kms: []
  azure_kv: []
  hc_vault: []
  age:
    - recipient: age1ln04w90q920hqw0zhgqftlh3ckprcgdvq0dpvv87hnpxn3plv3tqx6xfqt
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBBRnNWM0toYzN3Z2FTWnRY
        RmdHM0dRSThMdXFQYWNpNjU4QmUzdkZmeldVCnZIS2pueHY1c0tzUGgxa2IzTGwz
        NGptai9nYy9sY1pRN2NPc0VvR0JLZmMKLS0tIHRqbVpVc3h4c01DT2trcjJpUTNa
        SkZmcFozSks0bEdsVS9uakc5YWtTZkUKak/51Zc6OoBPfqKNxqctmQAtfgi2/tDe
        OA0fPdh1cWrjbeNGkLsF9w4rV48LDmPEEyfoclhO0WRjsJLu8/vi1w==
        -----END AGE ENCRYPTED FILE-----
  lastmodified: "2024-09-29T05:19:18Z"
  mac: ENC[AES256_GCM,data:mirziSe8s+WUBs0k/A8GvJeo01HRBgWzVukqLyzUPkmRQMeMJDlYoSM9e9pHGZXchhq5Ech0eGbXo4cR9EP8lockdnHOsjHsAkRfzBUDJXVB9u5b6CvHfHBmRHUttOkA058+b8hla3T1nh/cVPBwI5woDoIuTBE3fp0idM6tHHw=,iv:dI3p5N8OmpZOD2kevZXCDO4fBaxy2g7ZmSBM6QTO6PQ=,tag:gMe+zE7i1dtl20WKM1MNbw==,type:str]
  pgp: []
  unencrypted_suffix: _unencrypted
  version: 3.8.1
```

-Otherwise, if `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_TYPE` is set as `standard`, the entire file will be encrypted:

```yaml
age-encryption.org/v1
-> X25519 K+YTITCvJ9Am1U/jEdCCpCqxBbXTvb4gMcuDhUAbcHc
pdbTI+71EOdHZfhjk+hjuBSxYrcmcS88Quxu7+jsfns
--- T9MMrZ9tjvN2Lf4pWevQDkGZrAw44JRHqFNWPqTi9D8
�%5RIa-���mpa	�0�|e���<7
+��.C0��\.K�Q�k?1d��d��
�^���%�
����-�y@�k.�{ĺ�L�S
3?\k
��2ż���Ie�� O�Q�ZR�	P���2�Wb1�ͧ�i��
%�
zr{�sk
�BT���
��0��e�Z�J$V��7$�7AʽZ���Q�^R��Cʹ��}\-�յ״Q�aګT�̫[���1q�ގ)n�Z|T4v��n�	j��@V}[��%7fDwQ�9Л��*��ۗ�����|d��!~�
```

#### Editing Encrypted Files

**SOPs**

**Note**: Encrypted files should not be manually edited without using the SOPs CLI editor.

To securely edit trap listener credential files, please use the SOPs CLI:

* Non-password protected private key:

  ```shell
  SOPS_AGE_RECIPIENTS=$(</etc/elastiflow/trap/.age/public-age-keys.txt) \
  SOPS_AGE_KEY_FILE=/etc/elastiflow/trap/.age/key.age \
  sops credentials/credential.yaml
  ```
* Password protected private key:

  ```shell
  SOPS_AGE_RECIPIENTS=$(</etc/elastiflow/trap/.age/public-age-keys.txt) \
  SOPS_AGE_KEY=$(age -d /etc/elastiflow/trap/.age/key.age) \
  sops credentials/credential.yaml
  ```

These commands will decrypt the file in memory and open with a text editor of your choice. By default, the editor used will be vim:

![sops editor vim](/files/2IOsENnt6HMDHZ9IKTyI)

* Using nano instead of vim:

  ```shell
  EDITOR=nano \
  SOPS_AGE_RECIPIENTS=$(</etc/elastiflow/trap/.age/public-age-keys.txt) \
  SOPS_AGE_KEY=$(age -d /etc/elastiflow/trap/.age/key.age) \
  sops credentials/credential.yaml
  ```

Once changes are made, save and exit to update the encrypted file stored on the disk drive.

**Standard AGE**

To securely edit trap listener credential files, please follow the below steps:

1. Decrypt the file:

   ```shell
   age -d -i /etc/elastiflow/trap/.age/key.age -o ./credentials/credential.yaml ./credentials/credential-dec.yaml
   ```
2. Edit the decrypted file using your preferred text editor.
3. Encrypt the file:

   ```shell
   age -r "$(cat /etc/elastiflow/trap/.age/public-age-keys.txt)" -o ./credentials/credential-dec.yaml ./credentials/credential.yaml
   ```
4. Remove the decrypted file:

   ```shell
   rm ./credentials/credential-dec.yaml
   ```
5. Restart the Trap collector to apply the changes.

### File Encryption Configuration Options

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_ENABLE

Specifies whether the credential yaml files located in the directory specified by `EF_INPUT_TRAP_LISTENER_CREDENTIALS_DIRECTORY_PATH` will be encrypted.

* Valid Values
  * `true`, `false`
* Default
  * `false`

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_CREATE

If credentials encryption is enabled (`EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_ENABLE` is `true`), the collector will create a new local keystore when set to true. This includes creating new AGE keys and encrypting all yml files located in the directory configured via `EF_INPUT_TRAP_LISTENER_CREDENTIALS_DIRECTORY_PATH`.

* Valid Values
  * `true`, `false`
* Default
  * `false`

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_TYPE

If device file encryption is enabled (`EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_ENABLE` is `true`) this setting specifies the type of encryption manager the user wants to use. The two options are `sops` and `standard`. `sops` is the default option. It will only encrypt the configuration values of the configuration file, leaving the file structure intact. `standard` will simply encrypt the entire configuration file using AGE encryption.

* Valid Values
  * `sops`, `standard`
* Default
  * `sops`

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_PASSWORD

The file specified in `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_PRIVATE_KEY_FILE_PATH` can be encrypted for added security. If used in conjunction with `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_CREATE`, then the keystore will be configured with a password protected private key.

* Default
  * `''`

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_PRIVATE\_KEY\_FILE\_PATH

Sets the filepath location of the private key file. If used in conjunction with `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_CREATE`, then the private key used in the keystore will be generated at this location.

* Default
  * `/etc/elastiflow/snmp/traps/.age/key.age`

**Note**: If using Trap collector generated keys, do not delete or modify the key files. Doing so will result in the loss of the ability to decrypt the credentials.

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_PUBLIC\_KEY\_FILE\_PATH

Sets the filepath location of the public key file. If used in conjunction with `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_CREATE`, then the public key used in the keystore will be generated at this location.

* Default
  * `/etc/elastiflow/snmp/traps/.age/public-age-keys.txt`

**Note**: If using Trap collector generated keys, do not delete or modify the key files. Doing so will result in the loss of the ability to decrypt the credentials.

#### EF\_INPUT\_TRAP\_LISTENER\_CREDENTIALS\_SECURE\_STORE\_PUBLIC\_KEY

This setting can be used in place of `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_PUBLIC_KEY_FILE_PATH` to directly assign the public key. Cannot be used in conjunction with `EF_INPUT_TRAP_LISTENER_CREDENTIALS_SECURE_STORE_CREATE`.

* Default
  * `''`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elastiflow.com/trapcoll/configuration/receiving-traps/credentials/credentials_encryption.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.