How should I structure my SHA-256 verification hash file(s) to make it the easiest for others?

Question

I have been developing a major (to me) PHP library/framework kind of thing which I hope will power important applications of mine and maybe others in the future.

I have so far not implemented any kind of "anti-tamper" measures, and now I'm wondering how I should do this.

When I "build"/package the library/framework for a "release", should I be calculating a SHA-256 of the final ZIP file, or of every individial file/module inside?

Regardless of the answer to the previous question, how should those hashes then be "structured"? As a single file? One for each? What should be the name and file extension, and what format should be used to tell whatever tool reads it later which hash applies to which file and which kind of hash it is? JSON? Is there some kind of standard for this?

I want to make this as "standards-compliant" as possible so that anyone can quickly verify that my library/framework has not been tampered with since I "shipped" it.

Related question: Is SHA-256 the currently "best" hash to use for this? Or should I use something else? I already have a way to make SHA-256 hashes of strings and files, so I hope this is the best current one.

I imagine and hope that the answer will be something along of a "hashes.json" which contains:

[
    {
        "file_path": "blabla1",
        "hash_type": "SHA256",
        "hash": "dfjifsjsdfjdhufdhjsfudshfudhfudhdfsuhfudhfsuhfdushdsufhfhdusf"
    },
    {
        "file_path": "blabla2",
        "hash_type": "SHA256",
        "hash": "dfjifsjsdfjdhufdhjsfudshfudhfudhdfsuhfudhfsuhfdushdsufhfhdusf"
    },
    {
        "file_path": "blabla3",
        "hash_type": "SHA256",
        "hash": "dfjifsjsdfjdhufdhjsfudshfudhfudhdfsuhfudhfsuhfdushdsufhfhdusf"
    },
    ...
]

I also wonder if I should be verifying these hashes from the library itself, or if that's just silly? I mean, it somebody just auto-injects a .php file of my library with some malicious code snippet, then the hash check would soon (depending on how often it's checked) stop it from executing, so the attacker would have to calculate and modify the hashes as well... which is much less likely and thus more secure, no?

Either way, that last question was just a bonus. If it makes this question "too broad" or "off-topic" or something, kindly just ignore it.

Answer 1

Your goal is laudable; to protect the users of your work.

The problem is hard.

For the person who wants to do a quick check that they downloaded the right thing and it wasn't corrupted in transit, publish (prominently) a single SHA256 hash that is easy to verify (e.g. of the thing they just downloaded). There is an existing question that discusses this: https://stackoverflow.com/questions/8637340/how-to-code-sign-my-binaries-php-scripts . For this, SHA256 is a perfectly fine hashing algorithm.

Note also that you can get a good fraction of the way towards solving the above problem (ensuring no undetected corruption of the content in transit) by simply using a valid HTTPS certificate on the web site you use to make your software available to the public and disabling HTTP on that site.

For real authentication of the code you generated, you might want to sign your code using a code signing certificate issued to you by a trusted certificate authority. Note that this is much more complicated, significantly harder to verify for the user in this case (I don't think PHP is typically protected this way), and significantly more expensive. On the other hand, as long as you protect the private key for that certificate, it should be impossible for someone to successfully pass their work off as yours to an informed, paranoid user.

I would recommend against auto-scanning your own code. If someone is going to modify the code, why would they keep the part that scans the code to detect the modification? I'm not saying it isn't do-able (I don't know enough). I'm saying it is likely to be an arms race, and that's only fun if you're in it for the race.