Rewriting a 2017 Drupal Module for Drupal 11: Where the Time Actually Went

Rewriting a 2017 Drupal Module for Drupal 11: Where the Time Actually Went

After my post on Digital Locker, a reader on LinkedIn asked a good question: when I moved the module to Drupal 11, which part took longer, the API changes or building automated tests around the signing flow?

The honest answer is neither. The API changes were mostly mechanical, and once the code was right the tests came quickly. The time went into something I had not planned for: finding out what the 2017 code had been getting wrong all along.

Where the time went rewriting Digital Locker for Drupal 11: API changes were mechanical, security and correctness bugs took most of the time, tests were easy afterwards. Four bugs: Pull API open to anyone, empty signatures without file://, Aadhaar overflowing an integer field, and a private key committed to Git

The API changes: a checklist

The Digital Locker 2.0.x rewrite touched 60 files. A lot of that was replacing APIs that no longer exist:

  • \Drupal::entityManager(), drupal_set_message(), file_save_data(), file_default_scheme(), file_directory_temp() and the path.alias_manager service.
  • Procedural hooks moved to #[Hook] classes, and plugins to #[Action] and #[FieldWidget] attributes.
  • Requirements checks moved to hook_runtime_requirements(), and static calls became autowired services.
  • The token_var dependency, which never got a Drupal 9 release, was replaced by a module token, [digitallocker:issuer-id], with an update hook for existing patterns.

Each change is well documented in a change record, and Upgrade Status and Drupal Rector point you at most of them. It is tedious, but it is not hard.

Where the time actually went

Rewriting each file properly, rather than patching it until it ran, meant reading what every piece of code actually did. That turned up four problems that no deprecation tool would ever report.

1. The Pull API served signed certificates to anyone

DigiLocker fetches certificates from the issuer's site through a Pull API. The old route was open to everyone, and the controller never checked who was asking:

digitallocker_issuer.pull_api:
  path: 'digitallocker/issuer/pull-api'
  requirements:
    _access: 'TRUE'

Anyone who could guess a node ID could download a signed PDF for it, and not only for certificates: any node on the site.

The route still has to accept anonymous requests, because DigiLocker does not log in. What changed is that the request is now authenticated by what DigiLocker signs. Every Pull API request carries an orgId and a keyhash, a SHA-256 of the site's API key and the request timestamp. The controller verifies both before doing anything else:

if (!$this->requestSigner->verify($org_id, $timestamp, $keyhash)) {
  throw new AccessDeniedHttpException('Invalid credentials.');
}

The comparison uses hash_equals(), a site with no credentials configured refuses every request, and only content types marked as certificate types can be served at all.

The requester side had a similar gap: its callback now needs a permission and a CSRF token, and the browser can no longer choose the filename a document is saved under.

2. Signatures that were silently empty

This was the one that took longest to understand. The old code signed the PDF like this:

$pdf->setSignature($certificate, $certificate, $priv_key_pass, '', 1, $info);

It looks right, it runs without errors, and it produces a PDF. But TCPDF only reads a certificate from disk when the path starts with file://. A bare path is treated as the certificate content itself, which is not a valid certificate, so the document came out with an empty signature and nothing complained.

$pdf->setSignature(
  'file://' . $certificate,
  'file://' . $certificate,
  (string) $config->get('certificate_pass'),
  $extra_certs !== NULL ? 'file://' . $extra_certs : '',
  1,
  $info,
);

A bug like this is the worst kind for a module whose whole job is signed documents: everything looks like it works.

3. An Aadhaar number does not fit in an integer

Certificate types store the recipient's Aadhaar number, so the document can be pushed to the right DigiLocker account. Aadhaar numbers are 12 digits, too large for the integer field the module offered. It now uses a text field. An identifier made of digits is still not a number: you never do arithmetic on it.

4. A private key committed to the repository

The example submodule shipped with a certificate and private key in Git. It was meant to make the demo work out of the box. In practice, a key that every installation shares is not a secret. It is gone, and each site now supplies its own certificate, kept outside the repository.

And one more, found after the rewrite

The XML parsing in the Pull API, the requester and the Push API still accepted entity declarations. That was fixed separately in #3286990: any message containing a <!DOCTYPE is now rejected, and parsing runs with network access turned off.

Then the tests were easy

Once the code was right, writing tests around it was quick, because each bug above had already described exactly what to test. There is a unit test for the request signer, including the hash DigiLocker documents and each way verification should fail, and a kernel test for the Pull API that covers every way it should say no:

  • an unsigned request, a wrong keyhash and a wrong orgId are denied;
  • a node that is not a certificate type, and an unknown URI, return not found;
  • an empty body, malformed XML, an oversized body, an external entity and entity expansion are rejected;
  • and a correctly signed request returns a document that starts with %PDF.

All of this runs on every merge request in the drupal.org GitLab CI, alongside PHPCS and PHPStan.

What the tests do not cover yet

To be honest about the original question: the signature itself is not tested automatically yet. The kernel test checks that a signed request gets a PDF back, but not that the PDF carries a valid signature from the configured certificate. The file:// bug would slip straight past it. Generating a throwaway certificate in the test and checking the signature in the output is on the list, and it is a good first issue if you want to help.

A checklist for upgrading an old contrib module

  1. Run Upgrade Status and Rector first, and treat their output as the easy part of the job.
  2. Read every route's access requirements. Anything with _access: 'TRUE' needs a reason, written down next to it.
  3. Check that security-critical calls actually work, not just that they run. Signing, encryption and hashing can fail silently.
  4. Look for secrets in the repository, including in example and test modules.
  5. Check field types against real data. Identifiers made of digits belong in text fields.
  6. Parse untrusted XML defensively: no entity substitution, no network access, and reject a DOCTYPE you do not expect.
  7. Write a test for each bug you fix, then set up GitLab CI so they keep running.
  8. Write down what the tests do not cover. That list is your next set of issues.

What is next

The roadmap post covers the plan: Sign in with DigiLocker, protecting Aadhaar numbers on certificates, and the move from TCPDF, which its author has deprecated in favour of tc-lib-pdf. That move is exactly where a signature test will earn its keep.

If you maintain an old contrib module and want a second pair of eyes on the upgrade, or your organisation needs DigiLocker integration as part of a larger Drupal project, I work at Axelerant and am happy to connect you with the team. Get in touch.