Changes between Version 6 and Version 7 of ProofOfOwnership


Ignore:
Timestamp:
Jun 27, 2020, 12:04:33 PM (11 months ago)
Author:
Richard
Comment:

grammar update

Legend:

Unmodified
Added
Removed
Modified
  • ProofOfOwnership

    v6 v7  
    33= Proof of Account Ownership =
    44
    5 There are a number of external systems that need to verify that a particular person is in control of a user account.  The Proof of Account Ownership mechanism enables this proof using public key cryptography (SHA512 signature).  This is done by having the user entering a message provided by the external system which is then signed alongside their account ID using the project's private key.  The external system is then able to verify the signed message using the projects public key and thus provides proof that the user does in fact control the account.
     5There are a number of external systems which require a standardized proof of BOINC account ownership verification; this BOINC server extension provides this proof using existing public key cryptography within OpenSSL.
    66
    7 This is an optional extension to the BOINC generic project website. Is is available since server version "TODO".
     7The user provides an external system's message, this is signed alongside their BOINC account ID using the BOINC project's private key then provided to the external system.
     8
     9The external system verifies the signed message using the project's public key, establishing a simple offline proof of account ownership mechanism.
     10
     11This is an optional extension which was implemented in v[https://github.com/BOINC/boinc/releases/tag/server_release%2F1.2%2F1.2.0 1.2.0] and can be easily implemented in an afternoon by a project administrator.
    812
    913== User guide ==
    1014=== Instructions ===
    1115 1. Login to the project and go to the "Your Account" page
    12  1. Click on the "Account Ownership" link (the link says "Generate ownership proof").  Note that this is only displayed if the proof of account ownership keys have been created.
     16 1. Click on the "Account Ownership" link (the link says "Generate ownership proof").
     17    1. Note that this is only displayed if this proof of account ownership mechanism has been setup by the project administrator.
    1318 1. Enter the message you wish to be signed (typically supplied by the external system that wants you to provide the proof of ownership).
    1419 1. Submit the form.
    15  1. When successful the ownership proof will be shown on the website, copy and use the full contents to proof ownership of your account.
     20 1. When successful the ownership proof will be shown on the website, copy and use the full contents to prove ownership of your account to an external system.
    1621
    1722=== Example XML output ===
     23
     24Everything you need to verify the signature is included within the XML snippet; the `signature` tag is a base64 encoded SHA512 signature of the contents of `msg`.
     25
    1826{{{
    1927<account_ownership_verification>
     
    3644html/user/account_ownership.php - new file: UI that allows a user to have a message provided by an external system signed and linked to their account
    3745
    38 html/ops/index.php - Add link to check_account_ownership_keys.php 
     46html/ops/index.php - Add link to check_account_ownership_keys.php
    3947html/ops/check_account_ownership_keys.php - new file: provides a UI for a project admin to check if the account ownership keys are setup and installed
    4048html/ops/generate_account_ownership_keys.php - new file: command line script to create the account ownership keys
    4149}}}
     50
    4251=== Changes required to integrate this functionality: ===
    43  1. Install the latest BOINC [https://github.com/BOINC/boinc/pull/2965 PR#2965] web server changes
     52 1. Update the BOINC web server to at release [https://github.com/BOINC/boinc/releases/tag/server_release%2F1.2%2F1.2.0 1.2.0] (or later).
     53   1. Alternatively cherry pick the changes introduced by PR#2965 into your homebrew BOINC server implementation.
    4454 1. (optional) Configure reCAPTCHA in your `config.xml` so the form is protected.
    45  1. Generate the account ownership public and private keys by running generate_account_ownership_keys.php using the commandline in the BOINC web server html/ops directory.
     55 1. Generate the account ownership public and private keys by running generate_account_ownership_keys.php via the command line in the BOINC web server html/ops directory.
    4656
    4757=== Security ===
     
    5060If you believe that the private key has been compromised, you can generate a new key pair using the generate_account_ownership_keys.php in the BOINC web server html/ops directory.  Existing signed messages will no longer be valid and users will need to regenerate their signed messages to maintain a current proof of account ownership on external systems. You should inform users if you need to take this action so that they understand what is happening.
    5161
     62By implementing this BOINC server extension you improve the security of all external systems which require a proof of BOINC account ownership.
    5263
    5364== External systems guide ==
    5465=== Verifying signed messages ===
    55 The content of the `signature` tag is a base64 encoded SHA512 signature of the content of the `msg` tag. See [https://boinc.berkeley.edu/trac/wiki/ProofOfOwnership#ExampleXMLoutput Example XML output] section above. Basically everything you need to verify the signature is in the XML snippet. You can use the `<master_url>` to get the public key, which is published in the XML output from `get_project_config.php`.
    5666
    57 The following scripts and procedures are just examples. You should create your own process on how the user needs to supply the generated XML snippet to you and how you do the verification. Also keep in mind that the structure of the snippet might be modified in the future and might differ slightly between projects.
     67Ask the user to sign a secret message via the proof of account ownership mechanism on an individual BOINC project basis, they will return with XML snippets which include: `master_url`, `msg`, `signature`
     68
     69Combine the `master_url` with `/get_project_config.php` to fetch XML which includes the project's `ownership_signature_public_key`.
     70
     71Verify the supplied `signature` against the base64 encoded msg signed by the `ownership_signature_public_key`.
     72
     73Create your own process for the user supplying the generated XML snippet and how you perform verification, the following sections are examples for inspiration.
    5874
    5975=== Pre-requisites ===
    60 Follow the above user guide with a project that has this feature enabled, copy the output XML text snippet and save to 'xml_data.xml'.
     76Follow the user guide with a project that has this feature enabled, copy the output XML text snippet and save to 'xml_data.xml'.
    6177
    6278Extract the PUBLIC_KEY_VALUE from the XML output produced by '<master_url>/get_project_config.php' into a file called 'ownership_sign_public.pem'. Don't include the 'ownership_signature_public_key' tags in the file, don't include trailing return/newline characters in the text file.
     
    6581<ownership_signature_public_key>PUBLIC_KEY_VALUE</ownership_signature_public_key>
    6682}}}
     83
    6784=== Python verification script ===
    6885The below script takes the public key and the saved xml file and prints whether it's valid or not. Requires the following python modules: pycryptodome, base64, xmltodict
     
    7087{{{
    7188from Crypto.PublicKey import RSA # package: pycryptodome
    72 from Crypto.Signature import PKCS1_v1_5 
     89from Crypto.Signature import PKCS1_v1_5
    7390from Crypto.Hash import SHA512
    7491from base64 import b64decode
     
    84101signature = boinc_xml_data['account_ownership_verification']['signature']
    85102
    86 rsakey = RSA.importKey(public_key_data) 
     103rsakey = RSA.importKey(public_key_data)
    87104verifier = PKCS1_v1_5.new(rsakey)
    88105digest = SHA512.new()
     
    95112
    96113}}}
     114
    97115=== Linux command line ===
    98116Create the following bash script with filename 'verify.sh'.