test(ssh): cover key rotation with Molecule

Replace a private key while retaining its public key file to detect stale derived keys.
Verify the replacement public key, ownership and file permissions.

Co-authored-by: Copilot <copilot@github.com>

.gitea/workflows/ansible-linters.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Run ansible-lint
       uses: ansible/ansible-lint@9bce2bfb8f4a984e6b13767bc0d6bf0a49492164 # v26.10.1
       with:
-        args: "--config-file .ansible-lint"
+        args: "--config-file .ansible-lint.yml"
         # The molecule scenario is linted as well, so its collections are required beside the ones of the role.
         requirements_file: "molecule/default/collections.yml"
         setup_python: "true"

README.md

@@ -138,11 +138,11 @@ environment variables can be espcilitly defined, to consume it during execution
 > [!IMPORTANT]
 > To allow consuming environment variables must be set `PermitUserEnvironment yes` in `/etc/ssh/sshd_config`.
 
-Private and public keys are configured directly using `filename` and `content`. The role writes each key to
-`~/.ssh/<filename>`. Store private key content encrypted with Ansible Vault.
+Private keys are configured using `filename` and `content`; the role writes them to `~/.ssh/<filename>` and extracts
+their public keys to `~/.ssh/<filename>.pub`. Store private key content encrypted with Ansible Vault.
 
 Entries in `authorized_keys` are also added to `~/.ssh/authorized_keys`, including their optional command and environment
-settings. Public keys are still automatically extracted from private keys into `~/.ssh/<filename>.pub`.
+settings.
 
 ```yaml
 unix_users:
@@ -157,13 +157,11 @@ unix_users:
         StrictHostKeyChecking: "no"
         UserKnownHostFile: /dev/null
       authorized_keys:
-      - filename: claire@claire-pc.pub
-        content: ssh-ed25519 AAAAC3NzaC... claire
+      - content: ssh-ed25519 AAAAC3NzaC... claire
       - command: /usr/local/bin/upload-file.sh
         envs:
         - key: SSH_KEY_NAME
           value: bob@bob-pc
-        filename: bob@bob-pc.pub
         content: ssh-ed25519 AAAAC3NzaC... bob
       private_keys:
       - filename: toor@toor-pc.ed25519.key

defaults/main.yml

@@ -8,26 +8,25 @@ unix_groups: {}
 #     gid: 1001
 #     state: absent
 
-unix_users:
-  alice:
-    state: "present"
-    name: "Alice"
-    uid: "1000"
-    ssh:
-      config:
-      - Host: "*"
-        StrictHostKeyChecking: "no"
-        UserKnownHostFile: /dev/null
-      authorized_keys:
-      - filename: alice@alice-pc.pub
-        content: ssh-ed25519 AAAAC3NzaC... alice
-        # command: "" # optional
-      private_keys:
-      - filename: alice@alice-pc.ed25519.key
-        content: |
-          -----BEGIN OPENSSH PRIVATE KEY-----
-          ...
-          -----END OPENSSH PRIVATE KEY-----
+unix_users: {}
+# alice:
+#   state: "present"
+#   name: "Alice"
+#   uid: "1000"
+#   ssh:
+#     config:
+#     - Host: "*"
+#       StrictHostKeyChecking: "no"
+#       UserKnownHostFile: /dev/null
+#     authorized_keys:
+#     - content: ssh-ed25519 AAAAC3NzaC... alice
+#       # command: "" # optional
+#     private_keys:
+#     - filename: alice@alice-pc.ed25519.key
+#       content: |
+#         -----BEGIN OPENSSH PRIVATE KEY-----
+#         ...
+#         -----END OPENSSH PRIVATE KEY-----
 #     home: /home/alice
 #     btrfs: false
 #     netrc:

molecule/default/converge.yml

@@ -28,14 +28,12 @@
           - Host: "*"
             StrictHostKeyChecking: "no"
           authorized_keys:
-          - filename: alice.pub
-            content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/authorized_keys/molecule.pub', rstrip=false) }}"
+          - content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/authorized_keys/molecule.pub', rstrip=false) }}"
             command: "/usr/bin/true"
             envs:
             - key: EDITOR
               value: vi
-          - filename: alice-login.pub
-            content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/authorized_keys/molecule.pub', rstrip=false) }}"
+          - content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/authorized_keys/molecule.pub', rstrip=false) }}"
           private_keys:
           - filename: alice.ed25519.key
             content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/private_keys/molecule.ed25519.key', rstrip=false) }}"

molecule/default/create.yml

@@ -37,10 +37,22 @@
     - "{{ _authorized_key }}"
 
   # The key pair is generated instead of committed, private key material does not belong into a repository.
-  - name: Generate the ssh key pair the role is fed with
+  - name: Generate the SSH key pairs for initial configuration and rotation
     ansible.builtin.command:
-      cmd: "ssh-keygen -t ed25519 -N '' -C molecule -f {{ _private_key }}"
-      creates: "{{ _private_key }}"
+      argv:
+      - ssh-keygen
+      - -t
+      - ed25519
+      - -N
+      - ''
+      - -C
+      - molecule
+      - -f
+      - "{{ item }}"
+      creates: "{{ item }}"
+    loop:
+    - "{{ _private_key }}"
+    - "{{ _private_key }}.replacement"
 
   - name: Offer the public key as authorized key fixture
     ansible.builtin.copy:

molecule/default/verify.yml

@@ -11,8 +11,6 @@
       /home/molecule-alice/.ssh/config: "0644"
       /home/molecule-alice/.ssh/alice.ed25519.key: "0600"
       /home/molecule-alice/.ssh/alice.ed25519.key.pub: "0644"
-      /home/molecule-alice/.ssh/alice.pub: "0644"
-      /home/molecule-alice/.ssh/alice-login.pub: "0644"
       /home/molecule-alice/.forward: "0644"
       /home/molecule-alice/.netrc: "0600"
       /home/molecule-alice/.bashrc.d: "0755"
@@ -88,28 +86,6 @@
       - (_alice_keys.results[0].content | b64decode).splitlines() | select('match', '^ssh-ed25519 ') | list | length == 1
       fail_msg: "the authorized key of molecule-alice does not match the key extracted from its private key"
 
-  - name: Read the configured private and public SSH key files
-    ansible.builtin.slurp:
-      src: "{{ _alice_home }}/.ssh/{{ item }}"
-    loop:
-    - alice.ed25519.key
-    - alice.pub
-    - alice-login.pub
-    no_log: true
-    register: _alice_key_contents
-
-  - name: Assert that SSH key files contain the exact configured content
-    vars:
-      _private_key_content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/private_keys/molecule.ed25519.key', rstrip=false) }}"
-      _public_key_content: "{{ lookup('ansible.builtin.file', molecule_scenario_directory + '/files/ssh/authorized_keys/molecule.pub', rstrip=false) }}"
-    ansible.builtin.assert:
-      that:
-      - (_alice_key_contents.results[0].content | b64decode) == _private_key_content
-      - (_alice_key_contents.results[1].content | b64decode) == _public_key_content
-      - (_alice_key_contents.results[2].content | b64decode) == _public_key_content
-      - _public_key_content | trim in (_alice_keys.results[0].content | b64decode).splitlines()
-    no_log: true
-
   - name: Read the user and group database
     ansible.builtin.getent:
       database: "{{ item }}"
@@ -166,3 +142,57 @@
       - _bob_files.results[0].stat.exists
       - not _bob_files.results[1:] | map(attribute='stat.exists') | select | list
       fail_msg: "molecule-bob has files that were never declared for him"
+
+- name: Verify SSH key rotation
+  hosts: all
+  vars:
+    _replacement_key: "{{ molecule_scenario_directory }}/files/ssh/private_keys/molecule.ed25519.key.replacement"
+    unix_groups: {}
+    unix_users:
+      molecule-alice:
+        group: molecule-alice
+        password: alice
+        ssh:
+          private_keys:
+          - filename: alice.ed25519.key
+            content: "{{ lookup('ansible.builtin.file', _replacement_key, rstrip=false) }}"
+        state: present
+  tasks:
+  - name: Replace the private key while keeping the existing public key file
+    ansible.builtin.include_role:
+      name: unix-users
+
+  - name: Read the public key after rotation
+    ansible.builtin.slurp:
+      src: /home/molecule-alice/.ssh/alice.ed25519.key.pub
+    register: _rotated_public_key
+
+  - name: Assert the existing public key matches the replacement key and differs from the original
+    vars:
+      _expected_public_key: "{{ lookup('ansible.builtin.file', _replacement_key + '.pub') }}"
+    ansible.builtin.assert:
+      that:
+      - (_rotated_public_key.content | b64decode).split()[1] == _expected_public_key.split()[1]
+      - _rotated_public_key.content != _alice_keys.results[1].content
+
+  - name: Stat the rotated private and public keys
+    ansible.builtin.stat:
+      path: "{{ item.path }}"
+    loop:
+    - path: /home/molecule-alice/.ssh/alice.ed25519.key
+      mode: '0600'
+    - path: /home/molecule-alice/.ssh/alice.ed25519.key.pub
+      mode: '0644'
+    loop_control:
+      label: "{{ item.path }}"
+    register: _rotated_key_files
+
+  - name: Assert rotated keys retain their owner and permissions
+    ansible.builtin.assert:
+      that:
+      - item.stat.pw_name == 'molecule-alice'
+      - item.stat.gr_name == 'molecule-alice'
+      - item.stat.mode == item.item.mode
+    loop: "{{ _rotated_key_files.results }}"
+    loop_control:
+      label: "{{ item.item.path }}"

tasks/create_unix_user.yml

@@ -95,17 +95,6 @@
     state: absent
   when: unix_user.value.ssh.authorized_keys is not defined or unix_user.value.ssh.authorized_keys | length <= 0
 
-- name: "Create public SSH keys for unix user: {{ unix_user.key }}"
-  ansible.builtin.copy:
-    content: "{{ item.content }}"
-    dest: "{{ _unix_users_home }}/.ssh/{{ item.filename }}"
-    owner: "{{ unix_user.key }}"
-    group: "{{ unix_user.value.group | default('users') }}"
-    mode: "0644"
-  loop: "{{ unix_user.value.ssh.authorized_keys | default([]) }}"
-  loop_control:
-    label: "{{ item.filename }}"
-
 - name: "Create private SSH keys for unix user: {{ unix_user.key }}"
   ansible.builtin.copy:
     content: "{{ item.content }}"
@@ -119,25 +108,26 @@
   when: unix_user.value.ssh.private_keys is defined and unix_user.value.ssh.private_keys | length > 0
 
 - name: "Extract public SSH keys from private keys for unix user: {{ unix_user.key }}"
-  ansible.builtin.shell:
-    cmd: "ssh-keygen -y -f {{ (_unix_users_home + '/.ssh/' + item.filename) | quote }} > {{ (_unix_users_home + '/.ssh/' + item.filename + '.pub') | quote }}"
-    creates: "{{ _unix_users_home }}/.ssh/{{ item.filename }}.pub"
+  ansible.builtin.command:
+    argv: [ "ssh-keygen", "-y", "-f", "{{ _unix_users_home }}/.ssh/{{ item.filename }}" ]
+  changed_when: false
+  register: _unix_users_ssh_pub_key_extraction
   loop_control:
     label: "{{ item.filename }}"
   with_items:
   - "{{ unix_user.value.ssh.private_keys }}"
   when: unix_user.value.ssh.private_keys is defined and unix_user.value.ssh.private_keys | length > 0
 
-- name: "Correct permissions of public SSH keys for unix user: {{ unix_user.key }}"
-  ansible.builtin.file:
-    path: "{{ _unix_users_home }}/.ssh/{{ item.filename }}.pub"
+- name: "Write derived public SSH keys for unix user: {{ unix_user.key }}"
+  ansible.builtin.copy:
+    content: "{{ item.stdout }}\n"
+    dest: "{{ _unix_users_home }}/.ssh/{{ item.item.filename }}.pub"
     owner: "{{ unix_user.key }}"
     group: "{{ unix_user.value.group | default('users') }}"
     mode: "0644"
   loop_control:
-    label: "{{ item.filename }}"
-  with_items:
-  - "{{ unix_user.value.ssh.private_keys }}"
+    label: "{{ item.item.filename }}"
+  loop: "{{ _unix_users_ssh_pub_key_extraction.results }}"
   when: unix_user.value.ssh.private_keys is defined and unix_user.value.ssh.private_keys | length > 0
 
 - name: "Create custom SSH client config for unix user: {{ unix_user.key }}"