[sword-devel] How to validate a Sword module unlock key?

[Tobias Klein]

I like this idea, Jaak! :)

Can we implement this in the Sword engine with the next release that 
also delivers the "individualized unlock key function"? Ideally directly 
with a convenient API function that has the purpose to validate a given 
unlock key, with a signature like this:

*bool isSwordUnlockKeyValid(std::string key)*

In my view, having a mechanism for validating the unlock key is 
essential for having a professional unlock frontend. Without the 
availability of such a mechanism I see the following issues:

- Users need to go through full installation of a module before knowing 
that the unlock key they entered works. This is a rather lengthy 
feedback loop.

- Since there is a possibility for input errors when entering the key, 
the frontend must provide extra functions to "correct the key" after the 
installation has already happened (this wouldn't be necessary with a 
validation function).

Best regards,
Tobias

On 1/12/20 11:46 PM, Jaak Ristioja wrote:
> Hi!
>
> On 12.01.20 20:53, Greg Hellings wrote:
>> On Sun, Jan 12, 2020 at 10:32 AM Tobias Klein <contact at tklein.info> wrote:
>>
>>> Hi,
>>>
>>> I'm adding Sword module unlock support to Ezra Project and I've been
>>> wondering how you would validate a given unlock key?
>>>
>>> Basically the dialog for entering the unlock key is shown when a locked
>>> module is selected for installation. Before going through the effort of
>>> installing a module I would like to make sure that the given unlock key
>>> actually works with the selected module. Is there something in the SWORD
>>> API that supports the validation of the unlock key entered by the user?
>>>
>> The last time this came up, I believe the answer was that you just have to
>> try it and display it to the user and they have to decide if the results
>> are human readable.
>>
>> It would be possible to include a field in modules with a known-good value,
>> then the API could test if that value matched what was expected when it was
>> decrypted. Unless that functionality already exists, I don't know of any
>> other way you could accomplish this.
> I've thought about this many times myself and as far as I know Greg is
> right that there is currently no other way besides trial and error to
> verify the unlock key.
>
> Greg: Do I understand you correctly, that there would need to be an
> extra field in every such module, and extra logic must be added to SWORD
> so that this extra field does not show up in frontends? If this is so,
> it might slightly break compatiblity of modules with older versions of
> SWORD which do not contain such enhancements.
>
> As an alternative, I suggest for consideration the following approach:
>
>
> Add in the module configuration file the two extra pieces of
> information (presented here as two configuration options with bad names):
>
>    UnlockKeyVerifyValue=<Some sufficiently long random ASCII string>
>    UnlockKeyVerifyHash=<Hash of field value>
>
> When a newer version of SWORD detects these configuration options in the
> module configuration, it can verify the unlock key using the following
> algorithm:
>
>    1) Decrypt the value of the UnlockKeyVerifyValue configuration option
> (after whitespace trimming) with the unlock key
>    2) Verify that the hash of the value decrypted in step 1 matches the
> value of the UnlockKeyVerifyHash configuration option.
>
>
> Pros:
>   * Modules can easily be amended by adding new entries to their
> configuration files.
>   * No extra field in the module text is needed, so modules amended with
> these configuration options will continue to work with older versions of
> SWORD.
>   * Anyone with the key can generate this verification information.
>   * Only access to the module configuration file is needed to verify the
> unlock key, so no expensive seeking/reading/parsing the encrypted module
> content is necessary.
>   * Doesn't too leak much about the key.
>
> Cons:
>   * A hash function must be implemented, but I think this would not need
> to be cryptographically secure, but would act more like checksum, so
> even something as simple as CRC-32 might do.
>
>
> Notes:
>   * Another alternative would be to use a ciphertext/plaintext pair
> instead so that no checksum/has must be implemented at all, but this
> might potentially leak too much about the key, and will likely require
> the configuration options to include binary values (i.e.
> escaping/encoding would be needed).
>   * Another alternative would be to decrypt and verify a field from the
> encrypted module itself, but reading the ciphertext from the module file
> might be a more expensive operation.
>
>
> Hope this helps.
>
>
> Best regards,
> J
>
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20200113/1b610801/attachment-0001.html>