New tricks for the Checksum API

As a step in preparing for new features in Integrity Checker and wp-checksum, the backend API that powers the two packages has learned a new trick. Alternative hashes, a way of saying that a specific file may have more than one acceptable MD5 hash.

Why are alternative hashes needed?

Lots of WordPress plugins and themes sometimes has small changes made to them without the version number getting bumped. The most common example of this that the readme.txt of a plugin is often changed when a new version of WordPress is released.

The readme file contains information about the latest version of WordPress that it was tested with. This information is shown to users in the plugin repository and can be a vital piece of information before deciding to install a plugin. So it’s quite natural that after a new release of WordPress, plugin authors update the readme file to reflect successful testing on the new version. The content of readme.txt doesn’t change the plugin functionality at all, so it’s quite OK to update it without bumping the plugin version.

The problem is that an updated readme.txt forces the MD5 hash to change and both Integrity Checker and wp-checksum will see this as a sign of a modified file and alert the user. Integrity Checker (and soon wp-checksum) has the concept of a SOFT change and will flag a modified readme.txt as one. But the modified file is still shown and may cause concern.

It’s not too uncommon for plugin authors to modify other files without bumping the version number. We’ve seem a lot of different files get a lot of different modifications within the same plugin version number. Sometimes it’s a corrected typo, other times it’s a quite dramatic change.

The end result is that for any given official version of  a plugin or theme there may be multiple actual versions, one actual version for each commit into the WordPress repository.


How does alternative hashes help?

By having alternative hashes defined for a file, the clients that are using the API will have far fewer false positives. The contents of a file in your WordPress installation might differ slightly from what that same file looks like in the WordPress repository. But that doesn’t mean that your files was modified in a malicious manner, it might just mean that the plugin  author modified the file without bumping the plugin version.

For any type of security related software, avoiding false positives is a good thing for several reasons. Most importantly, it means that whenever a real modification is found, you are much more likely to take it seriously. Another benefit is to avoid causing uncalled for worries, the less experience a user has, the more likely he/she is to become overly worried about something that turns out to be a false positive. All in all, reducing false positives is a win.

Next steps

With the upgraded backend API in place, both wp-checksum and Integrity Checker now needs to get support for the added feature.  We expect to have both clients updated within a week. Having said that, we’re not 100% in control over when the updated version of the plugin in the WordPress repository will be made available since the repository maintainer has a stricter upgrade procedure in place these days.

Access to the API

For the majority of users, accessing the API is mostly done via one of the clients we provide, Integrity Checker and wp-checksum, but the API is public and to some extent free to anyone.  If you’re interested in developing your own client, please don’t hesitate to contact us for API keys as well as developer documentation.

Your thoughts

We’d be glad to hear back from you. Ping us if you want to know more about the API, get an API key or just to say hi. We’d be especially happy if you have any ideas on how to improve client functionality or if you want to contribute to the development.

One Reply to “New tricks for the Checksum API”

Leave a Reply

Your email address will not be published. Required fields are marked *