Merge pull request #1128 from puppetlabs/modern_debian_keyrings

Add support for modern keyrings

Author: Ramesh7

Gemfile

@@ -22,7 +22,7 @@ group :development do
   gem "voxpupuli-puppet-lint-plugins", '~> 4.0', require: false
   gem "facterdb", '~> 1.18',                     require: false
   gem "metadata-json-lint", '~> 3.0',            require: false
-  gem "puppetlabs_spec_helper", '~> 6.0',        require: false
+  gem "puppetlabs_spec_helper", '~> 7.0',        require: false
   gem "rspec-puppet-facts", '~> 2.0',            require: false
   gem "codecov", '~> 0.2',                       require: false
   gem "dependency_checker", '~> 1.0.0',          require: false

README.md

@@ -66,6 +66,28 @@ include apt
 
 ### Add GPG keys
 
+You can fetch GPG keys via HTTP, Puppet URI, or local filesystem. The key can be in GPG binary format, or ASCII armored, but the filename should have the appropriate extension (`.gpg` for keys in binary format; or `.asc` for ASCII armored keys).
+
+#### Fetch via HTTP
+
+```puppet
+apt::keyring { 'puppetlabs-keyring.gpg':
+  source => 'https://apt.puppetlabs.com/keyring.gpg',
+}
+```
+
+#### Fetch via Puppet URI
+
+```puppet
+apt::keyring { 'puppetlabs-keyring.gpg':
+  source => 'puppet:///modules/my_module/local_puppetlabs-keyring.gpg',
+}
+```
+
+Alternatively `apt::key` can be used.
+
+**Warning** `apt::key` is deprecated in the latest Debian and Ubuntu releases. Please use apt::keyring instead.
+
 **Warning:** Using short key IDs presents a serious security issue, potentially leaving you open to collision attacks. We recommend you always use full fingerprints to identify your GPG keys. This module allows short keys, but issues a security warning if you use them.
 
 Declare the `apt::key` defined type:
@@ -184,6 +206,22 @@ apt::source { 'puppetlabs':
 }
 ```
 
+### Adding name and source to the key parameter of apt::source, which then manages modern apt gpg keyrings
+
+The `name` parameter of key hash should contain the filename with extension (such as `puppetlabs.gpg`).
+
+```puppet
+apt::source { 'puppetlabs':
+  comment  => 'Puppet8',
+  location => 'https://apt.puppetlabs.com/',
+  repos    => 'puppet8',
+  key      => {
+    'name'   => 'puppetlabs.gpg',
+    'source' => 'https://apt.puppetlabs.com/keyring.gpg',
+  },
+}
+```
+
 <a id="configure-apt-from-hiera"></a>
 
 ### Configure Apt from Hiera

REFERENCE.md

@@ -20,6 +20,7 @@
 
 * [`apt::conf`](#apt--conf): Specifies a custom Apt configuration file.
 * [`apt::key`](#apt--key): Manages the GPG keys that Apt uses to authenticate packages.
+* [`apt::keyring`](#apt--keyring): Manage GPG keyrings for apt repositories
 * [`apt::mark`](#apt--mark): Manages apt-mark settings
 * [`apt::pin`](#apt--pin): Manages Apt pins. Does not trigger an apt-get update run.
 * [`apt::ppa`](#apt--ppa): Manages PPA repositories using `add-apt-repository`. Not supported on Debian.
@@ -73,6 +74,7 @@ The following parameters are available in the `apt` class:
 * [`proxy_defaults`](#-apt--proxy_defaults)
 * [`sources`](#-apt--sources)
 * [`keys`](#-apt--keys)
+* [`keyrings`](#-apt--keyrings)
 * [`ppas`](#-apt--ppas)
 * [`pins`](#-apt--pins)
 * [`settings`](#-apt--settings)
@@ -239,6 +241,14 @@ Creates new `apt::key` resources. Valid options: a hash to be passed to the crea
 
 Default value: `$apt::params::keys`
 
+##### <a name="-apt--keyrings"></a>`keyrings`
+
+Data type: `Hash`
+
+Hash of `apt::keyring` resources.
+
+Default value: `{}`
+
 ##### <a name="-apt--ppas"></a>`ppas`
 
 Data type: `Hash`
@@ -624,6 +634,101 @@ Passes additional options to `apt-key adv --keyserver-options`.
 
 Default value: `$apt::key_options`
 
+### <a name="apt--keyring"></a>`apt::keyring`
+
+Manage GPG keyrings for apt repositories
+
+#### Examples
+
+##### Download the puppetlabs apt keyring
+
+```puppet
+apt::keyring { 'puppetlabs-keyring.gpg':
+  source => 'https://apt.puppetlabs.com/keyring.gpg',
+}
+```
+
+##### Deploy the apt source and associated keyring file
+
+```puppet
+apt::source { 'puppet8-release':
+  location => 'http://apt.puppetlabs.com',
+  repos    => 'puppet8',
+  key      => {
+    name   => 'puppetlabs-keyring.gpg',
+    source => 'https://apt.puppetlabs.com/keyring.gpg'
+  }
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `apt::keyring` defined type:
+
+* [`keyring_dir`](#-apt--keyring--keyring_dir)
+* [`keyring_filename`](#-apt--keyring--keyring_filename)
+* [`keyring_file`](#-apt--keyring--keyring_file)
+* [`keyring_file_mode`](#-apt--keyring--keyring_file_mode)
+* [`source`](#-apt--keyring--source)
+* [`content`](#-apt--keyring--content)
+* [`ensure`](#-apt--keyring--ensure)
+
+##### <a name="-apt--keyring--keyring_dir"></a>`keyring_dir`
+
+Data type: `Stdlib::Absolutepath`
+
+Path to the directory where the keyring will be stored.
+
+Default value: `'/etc/apt/keyrings'`
+
+##### <a name="-apt--keyring--keyring_filename"></a>`keyring_filename`
+
+Data type: `String[1]`
+
+Optional filename for the keyring. It should also contain extension along with the filename.
+
+Default value: `$name`
+
+##### <a name="-apt--keyring--keyring_file"></a>`keyring_file`
+
+Data type: `Stdlib::Absolutepath`
+
+File path of the keyring.
+
+Default value: `"${keyring_dir}/${keyring_filename}"`
+
+##### <a name="-apt--keyring--keyring_file_mode"></a>`keyring_file_mode`
+
+Data type: `Stdlib::Filemode`
+
+File permissions of the keyring.
+
+Default value: `'0644'`
+
+##### <a name="-apt--keyring--source"></a>`source`
+
+Data type: `Optional[Stdlib::Filesource]`
+
+Source of the keyring file. Mutually exclusive with 'content'.
+
+Default value: `undef`
+
+##### <a name="-apt--keyring--content"></a>`content`
+
+Data type: `Optional[String[1]]`
+
+Content of the keyring file. Mutually exclusive with 'source'.
+
+Default value: `undef`
+
+##### <a name="-apt--keyring--ensure"></a>`ensure`
+
+Data type: `Enum['present','absent']`
+
+Ensure presence or absence of the resource.
+
+Default value: `'present'`
+
 ### <a name="apt--mark"></a>`apt::mark`
 
 Manages apt-mark settings
@@ -925,6 +1030,20 @@ apt::source { 'puppetlabs':
 }
 ```
 
+##### Download key behaviour to handle modern apt gpg keyrings. The `name` parameter in the key hash should be given with
+
+```puppet
+extension. Absence of extension will result in file formation with just name and no extension.
+apt::source { 'puppetlabs':
+  location => 'http://apt.puppetlabs.com',
+  comment  => 'Puppet8',
+  key      => {
+    'name'   => 'puppetlabs.gpg',
+    'source' => 'https://apt.puppetlabs.com/keyring.gpg',
+  },
+}
+```
+
 #### Parameters
 
 The following parameters are available in the `apt::source` defined type:
@@ -1001,9 +1120,12 @@ Default value: `{}`
 
 Data type: `Optional[Variant[String, Hash]]`
 
-Creates a declaration of the apt::key defined type. Valid options: a string to be passed to the `id` parameter of the `apt::key`
-defined type, or a hash of `parameter => value` pairs to be passed to `apt::key`'s `id`, `server`, `content`, `source`, `weak_ssl`,
-and/or `options` parameters.
+Creates an `apt::keyring` in `/etc/apt/keyrings` (or anywhere on disk given `filename`) Valid options:
+  * a hash of `parameter => value` pairs to be passed to `file`: `name` (title), `content`, `source`, `filename`
+
+The following inputs are valid for the (deprecated) `apt::key` defined type. Valid options:
+  * a string to be passed to the `id` parameter of the `apt::key` defined type
+  * a hash of `parameter => value` pairs to be passed to `apt::key`: `id`, `server`, `content`, `source`, `weak_ssl`, `options`
 
 Default value: `undef`
 
@@ -1012,6 +1134,7 @@ Default value: `undef`
 Data type: `Optional[Stdlib::AbsolutePath]`
 
 Absolute path to a file containing the PGP keyring used to sign this repository. Value is used to set signed-by on the source entry.
+This is not necessary if the key is installed with `key` param above.
 See https://wiki.debian.org/DebianRepository/UseThirdParty for details.
 
 Default value: `undef`
@@ -1030,8 +1153,8 @@ Default value: `undef`
 Data type: `Optional[String]`
 
 Tells Apt to only download information for specified architectures. Valid options: a string containing one or more architecture names,
-separated by commas (e.g., 'i386' or 'i386,alpha,powerpc'). Default: undef (if unspecified, Apt downloads information for all architectures
-defined in the Apt::Architectures option).
+separated by commas (e.g., 'i386' or 'i386,alpha,powerpc').
+(if unspecified, Apt downloads information for all architectures defined in the Apt::Architectures option)
 
 Default value: `undef`
 

manifests/init.pp

@@ -88,6 +88,9 @@
 # @param keys
 #   Creates new `apt::key` resources. Valid options: a hash to be passed to the create_resources function linked above.
 #
+# @param keyrings
+#   Hash of `apt::keyring` resources.
+#
 # @param ppas
 #   Creates new `apt::ppa` resources. Valid options: a hash to be passed to the create_resources function linked above.
 #
@@ -159,6 +162,7 @@
   Apt::Proxy $proxy                               = $apt::params::proxy,
   Hash $sources                                   = $apt::params::sources,
   Hash $keys                                      = $apt::params::keys,
+  Hash $keyrings                                  = {},
   Hash $ppas                                      = $apt::params::ppas,
   Hash $pins                                      = $apt::params::pins,
   Hash $settings                                  = $apt::params::settings,
@@ -347,6 +351,12 @@
   if $keys {
     create_resources('apt::key', $keys)
   }
+  # manage keyrings if present
+  $keyrings.each |$key, $data| {
+    apt::keyring { $key:
+      * => $data,
+    }
+  }
   # manage ppas if present
   if $ppas {
     create_resources('apt::ppa', $ppas)

manifests/keyring.pp

@@ -0,0 +1,74 @@
+# @summary Manage GPG keyrings for apt repositories
+#
+# @example Download the puppetlabs apt keyring
+#   apt::keyring { 'puppetlabs-keyring.gpg':
+#     source => 'https://apt.puppetlabs.com/keyring.gpg',
+#   }
+# @example Deploy the apt source and associated keyring file
+#   apt::source { 'puppet8-release':
+#     location => 'http://apt.puppetlabs.com',
+#     repos    => 'puppet8',
+#     key      => {
+#       name   => 'puppetlabs-keyring.gpg',
+#       source => 'https://apt.puppetlabs.com/keyring.gpg'
+#     }
+#   }
+#
+# @param keyring_dir
+#   Path to the directory where the keyring will be stored.
+#
+# @param keyring_filename
+#   Optional filename for the keyring. It should also contain extension along with the filename.
+#
+# @param keyring_file
+#   File path of the keyring.
+#
+# @param keyring_file_mode
+#   File permissions of the keyring.
+#
+# @param source
+#   Source of the keyring file. Mutually exclusive with 'content'.
+#
+# @param content
+#   Content of the keyring file. Mutually exclusive with 'source'.
+#
+# @param ensure
+#   Ensure presence or absence of the resource.
+#
+define apt::keyring (
+  Stdlib::Absolutepath $keyring_dir = '/etc/apt/keyrings',
+  String[1] $keyring_filename = $name,
+  Stdlib::Absolutepath $keyring_file = "${keyring_dir}/${keyring_filename}",
+  Stdlib::Filemode $keyring_file_mode = '0644',
+  Optional[Stdlib::Filesource] $source = undef,
+  Optional[String[1]] $content = undef,
+  Enum['present','absent'] $ensure = 'present',
+) {
+  ensure_resource('file', $keyring_dir, { ensure => 'directory', mode => '0755', })
+  if $source and $content {
+    fail("Parameters 'source' and 'content' are mutually exclusive")
+  } elsif ! $source and ! $content {
+    fail("One of 'source' or 'content' parameters are required")
+  }
+
+  case $ensure {
+    'present': {
+      file { $keyring_file:
+        ensure  => 'file',
+        mode    => $keyring_file_mode,
+        owner   => 'root',
+        group   => 'root',
+        source  => $source,
+        content => $content,
+      }
+    }
+    'absent': {
+      file { $keyring_file:
+        ensure => $ensure,
+      }
+    }
+    default: {
+      fail("Invalid 'ensure' value '${ensure}' for apt::keyring")
+    }
+  }
+}