yapgp

Yet another PGP puppet module.

Table of Contents

1. Description
2. Setup - The basics of getting started with yapgp
   • Beginning with yapgp
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

This module is designed to manage PGP public keys. It can fetch keys, keep them up to date, set the trust level, and export them.

Setup

Beginning with yapgp

Just include yapgp and you're good to go (this will install ruby-gpgme).

Usage

Typical usage would look like:

include yapgp

pgp_key { 'Tails sysadmins':
  fp     => 'D113CB6D5131D34BA5F0FE9E70F4F03116525F43':
  ensure => present,
  user   => root,
  trust  => 4,
}

This will add the tails-sysadmins@boum.org PGP public key to root's keyring and set the owner trustlevel to 4.

In case the key is not retrievable from external sources (e.g., keyservers) or not importable from external sources (for instance, when a uid is missing), you may provide a source parameter:

pgp_key { 'deb.tails.boum.org signing key':
  ensure => present,
  source => 'https://gitlab.tails.boum.org/tails/tails/-/raw/stable/config/chroot_sources/tails.chroot.gpg?inline=false',
  fp     => 'D68F87149EBA77541573C1C12453AA9CE4123A9A',
}

Upon failing to import the key from external sources, yapgp will then attempt to fetch the keydata from the provided source (a URI or file location).

Functions

To export a key, you can use the export_pgp_key function. Please keep in mind that puppet functions are ran during catalog compilation, so regardless of the relationship you specify, it will always run before any pgp_key types are executed. Hence, to prevent exporting keys that are not present in the keyring (yet), it is recommended to set a condition like this:

if export_pgp_key('D113CB6D5131D34BA5F0FE9E70F4F03116525F43') {
  file { '/root/tails-sysadmins.asc':
    content => export_pgp_key('D113CB6D5131D34BA5F0FE9E70F4F03116525F43','root'),
  }
}

Also keep in mind that be default, functions run on the puppet server. If you want to export a key from the keyring on the agent, defer the function as such:

file { '/home/user/tails-sysadmins.asc':
  content => Deferred('export_pgp_key', [ 'D113CB6D5131D34BA5F0FE9E70F4F03116525F43', 'user' ]),
}

Facts

This module adds a custom fact called pgp_keys, containing a hash of all keys available in root's keychain, indexed by fingerprint.

Limitations

This module assumes dirmngr is properly configured.

Only Debian 10 and higher are currently supported.

There is no support for dealing with private keys, nor for any encryption or decryption of data.

Development

Merge requests are welcome ;-)

Reference

Table of Contents

Classes

• yapgp: Main class, ensures dependencies are installed.

Resource types

• pgp_key: This type provides Puppet with the capability to manage PGP keys

Functions

• export_pgp_key: Returns an armored export of the given key.

Classes

yapgp

Ensures all the yapgp module's dependencies are installed.

Examples

include yapgp

Resource types

pgp_key

This type provides Puppet with the capability to manage PGP keys

Examples

Basic usage

pgp_key { 'Tails sysadmins':
  fp     => 'D113CB6D5131D34BA5F0FE9E70F4F03116525F43',
  ensure => present,
  trust  => 4,
  user   => root,
}

Properties

The following properties are available in the pgp_key type.

ensure

Valid values: present, absent

Ensure the key is present or absent

Default value: present

Parameters

The following parameters are available in the pgp_key type.

• fp
• name
• provider
• source
• trust
• user

fp

Valid values: %r{\A(0x)?[0-9a-fA-F]{40}\Z}

The fingerprint of the key you want to manage, should be the full 40-digit key fingerprint.

name

namevar

The unique name of this resource.

provider

The specific backend to use for this pgp_key resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

source

Where to retrieve the key from (URI or local file)

trust

Valid values: %r{\A[1-5]\Z}

The trustlevel of the key you want to manage, should be an integer between 1 and 5.

Default value: 1

user

The user for whom you want to manage the key.

Default value: root

Functions

export_pgp_key

Type: Ruby 3.x API

Takes the key fingerprint as first argument. The second argument, the username to whom the keyring belongs, is optional.

export_pgp_key()

Takes the key fingerprint as first argument. The second argument, the username to whom the keyring belongs, is optional.

Returns: Variant[String,Boolean] Returns an armored key as string or false if the given key cannot be exported.

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.3

Features

• added source parameter to pgp_key to allow importing from file or URI.

Release 0.1.2

Features

• Added pgp_keys custom fact

Release 0.1.1

• Moved to different repository

Release 0.1.0

Features

• The type pgp_key, which ensures a pgp key is up to date and at the right trustlevel.
• The function export_pgp_key, which returns the armored public key.

Bugfixes

Known Issues