Dpkg::Vendor: Rework keyring hooks

Add new archive-keyrings and archive-keyrings-historic for archive
related keyrings. Rename keyrings to package-keyrings for the source
package keyrings. And add a compatibility keyrings hook that aliases
to package-keyrings and emits a deprecation warning.

Prompted-by: Johannes Schauer <josch@debian.org>

debian/changelog

@@ -19,6 +19,9 @@ dpkg (1.18.11) UNRELEASED; urgency=medium
     Closes: #787980
   * Perl modules:
     - Obsolete Source-Version substvar in Dpkg::Substvars by emitting errors.
+    - Rework keyring hooks in Dpkg::Vendor. Deprecate the keyrings hook, and
+      add package-keyrings, archive-keyrings and archive-keyrings-historic
+      hooks. Prompted by Johannes Schauer <josch@debian.org>.
   * Packaging:
     - Add liblocale-gettext-perl to libdpkg-perl Recommends.
     - Wrap and document dependency relationships.

scripts/Dpkg/Source/Package.pm

@@ -434,7 +434,7 @@ sub check_signature {
         if (length $ENV{HOME} and -r "$ENV{HOME}/.gnupg/trustedkeys.gpg") {
             push @exec, '--keyring', "$ENV{HOME}/.gnupg/trustedkeys.gpg";
         }
-        foreach my $vendor_keyring (run_vendor_hook('keyrings')) {
+        foreach my $vendor_keyring (run_vendor_hook('package-keyrings')) {
             if (-r $vendor_keyring) {
                 push @exec, '--keyring', $vendor_keyring;
             }

scripts/Dpkg/Vendor/Debian.pm

@@ -49,9 +49,16 @@ specific behavior and policies.
 sub run_hook {
     my ($self, $hook, @params) = @_;
 
-    if ($hook eq 'keyrings') {
+    if ($hook eq 'package-keyrings') {
         return ('/usr/share/keyrings/debian-keyring.gpg',
                 '/usr/share/keyrings/debian-maintainers.gpg');
+    } elsif ($hook eq 'keyrings') {
+        warnings::warnif('deprecated', 'deprecated keyrings vendor hook');
+        return $self->run_hook('package-keyrings', @params);
+    } elsif ($hook eq 'archive-keyrings') {
+        return ('/usr/share/keyrings/debian-archive-keyring.gpg');
+    } elsif ($hook eq 'archive-keyrings-historic') {
+        return ('/usr/share/keyrings/debian-archive-removed-keys.gpg');
     } elsif ($hook eq 'builtin-build-depends') {
         return qw(build-essential:native);
     } elsif ($hook eq 'builtin-build-conflicts') {

scripts/Dpkg/Vendor/Default.pm

@@ -75,12 +75,26 @@ supported hooks are:
 The first parameter is a Dpkg::Source::Package object. The hook is called
 just before the execution of $srcpkg->build().
 
-=item keyrings ()
+=item package-keyrings ()
 
 The hook is called when dpkg-source is checking a signature on a source
-package. It takes no parameters, but returns a (possibly empty) list of
+package (since dpkg 1.18.11). It takes no parameters, but returns a
+(possibly empty) list of vendor-specific keyrings.
+
+=item archive-keyrings ()
+
+The hook is called when there is a need to check signatures on artifacts
+from repositories, for example by a download method (since dpkg 1.18.11).
+It takes no parameters, but returns a (possibly empty) list of
 vendor-specific keyrings.
 
+=item archive-keyrings-historic ()
+
+The hook is called when there is a need to check signatures on artifacts
+from historic repositories, for example by a download method
+(since dpkg 1.18.11). It takes no parameters, but returns a (possibly empty)
+list of vendor-specific keyrings.
+
 =item builtin-build-depends ()
 
 The hook is called when dpkg-checkbuilddeps is initializing the source
@@ -126,6 +140,13 @@ sub run_hook {
     if ($hook eq 'before-source-build') {
         my $srcpkg = shift @params;
     } elsif ($hook eq 'keyrings') {
+        warnings::warnif('deprecated', 'obsolete keyrings vendor hook');
+        return ();
+    } elsif ($hook eq 'package-keyrings') {
+        return ();
+    } elsif ($hook eq 'archive-keyrings') {
+        return ();
+    } elsif ($hook eq 'archive-keyrings-historic') {
         return ();
     } elsif ($hook eq 'register-custom-fields') {
         return ();

scripts/Dpkg/Vendor/Ubuntu.pm

@@ -70,11 +70,16 @@ sub run_hook {
         }
 
     } elsif ($hook eq 'keyrings') {
-        my @keyrings = $self->SUPER::run_hook($hook);
-
-        push(@keyrings, '/usr/share/keyrings/ubuntu-archive-keyring.gpg');
-        return @keyrings;
-
+        return $self->run_hook('package-keyrings', @params);
+    } elsif ($hook eq 'package-keyrings') {
+        return ($self->SUPER::run_hook($hook),
+                '/usr/share/keyrings/ubuntu-archive-keyring.gpg');
+    } elsif ($hook eq 'archive-keyrings') {
+        return ($self->SUPER::run_hook($hook),
+                '/usr/share/keyrings/ubuntu-archive-keyring.gpg');
+    } elsif ($hook eq 'archive-keyrings-historic') {
+        return ($self->SUPER::run_hook($hook),
+                '/usr/share/keyrings/ubuntu-archive-removed-keys.gpg');
     } elsif ($hook eq 'register-custom-fields') {
         my @field_ops = $self->SUPER::run_hook($hook);
         push @field_ops,