README.md

   1 ---
   2 title: "![CodeSign](etc/img/Logo.png)"
   3 ---
   4
   5
   6 Introduction
   7 ============
   8
   9 **CodeSign** is a simple file signing and verification toolkit, based on cryptographic routines from the Libcrypto (OpenSSL) library.
  10
  11 At this time, CodeSign employs the RSA signature algorithm with 15360-Bit keys and the SHA-512 hash function.
  12
  13 This software was created by LoRd_MuldeR [&lt;MuldeR2@GMX.de&gt;](mailto:MuldeR2@GMX.de). Please see <http://www.muldersoft.com> for additional information.
  14
  15
  16 Synopsis
  17 ========
  18
  19 The CodeSign suite is composed of the following tools:
  20
  21 Key Generator
  22 -------------
  23
  24 The **key generator** tool is used to generate a new key-pair. It creates the *public key* and the *private key* file. The private key will be protected by the specified *password*.
  25
  26 ```
  27 Usage:
  28   codesign_keygen.exe <passwd> <signkey.pub> <signkey.key>
  29 ```
  30
  31 File Signer
  32 -----------
  33
  34 The **file signer** tool is used to create a new signature. It creates the *signature* file for the specified *input* (original) file, using the existing *private key* protected by *password*.
  35
  36 ```
  37 Usage:
  38   codesign_sign.exe <passwd> <signkey.key> <filename.dat> <signature.sig>
  39 ```
  40
  41 File Verifier
  42 -------------
  43
  44 The **file verifier** tool is used to check whether the specified *signature* file is valid *and* matches the given (possibly tampered) *input* file, using the specified *public key*.
  45
  46 ```
  47 Usage:
  48   codesign_verify.exe <signkey.pub> <filename.dat> <signature.sig>
  49 ```
  50
  51 There is an alternative variant of the *file verifier* tool that uses an "embedded" public key (from the file's resources) and therefore does ***not*** need a separate *public key* file.
  52
  53 ```
  54 Usage:
  55   codesign_verifz.exe <filename.dat> <signature.sig>
  56 ```
  57
  58
  59 Embedding the Public Key
  60 ========================
  61
  62 In order to use the **file verifier** tool with an *embedded* public key (`codesign_verifz.exe`), the *public key* must be added to the file's resource section first:
  63
  64 * It is recommended to use the [Resource Hacker&trade;](http://www.angusj.com/resourcehacker/) utility for adding resources to the executable file. Use command *"Action"* &rarr; *"Add Image or Other Binary Resource"*.
  65
  66 * The *public* RSA key, in OpenSSL PEM format, shall be embedded as a resource of type `RT_RCDATA` with the name **`RSA_PUBLIC_KEY`**.
  67
  68 * The SHA-512 digest of the *public* RSA key, in "raw" (binary) format, shall be embedded as a resource of type `RT_RCDATA` with the name **`CHECKSUM_SHA512`**.
  69
  70   OpenSSL command to generate the required SHA-512 digest:
  71   ```
  72   openssl.exe dgst -sha512 -binary -out signkey.pub.sha512 signkey.pub
  73   ```
  74
  75
  76 Quick Start Guide
  77 =================
  78
  79 1. First of all, generate your RSA key-pair, if not already done:
  80
  81    ```
  82    codesign_keygen.exe your-password-here signkey.pub signkey.key
  83    ```
  84
  85    **Note:** This step is required only *once*. The same key-pair can be used to sign *many* files. Keep the *private* key (and the password) confidential!
  86
  87 2. Sign the file to be distributed, using the previously generated private key:
  88
  89    ```
  90    codesign_sign.exe your-password-here signkey.key my-installer.exe my-installer.exe.sig
  91    ```
  92
  93    **Note:** The generated signature file shall be distributed alongside with the signed file. The *private key* ***must not*** be distributed under any circumstances!
  94
  95 3. Verify the retrieved (e.g. downloaded) file:
  96
  97    ```
  98    codesign_verify.exe signkey.pub my-installer.exe my-installer.exe.sig
  99    ```
 100
 101    **Note:** This step is used to verify that the retrieved file was signed by the original author and that it was ***not*** tampered with since it was signed.
 102
 103
 104 Passing the Password
 105 ====================
 106
 107 Passing the password directly on the command-line is **not** recommended for security reasons!
 108
 109 The password can be passed to the CodeSign tools via pipe instead. Setting the password to `-` will cause the program to read the password from the standard input stream:
 110
 111 * For example, the password can be read from a password file:
 112
 113   ```
 114   codesign_keygen.exe - signkey.pub signkey.key < password.txt
 115   ```
 116
 117 * Alternatively, the **`passentry.exe`** helper application can be used to display a simple passwort entry dialog to the user:
 118
 119   ```
 120   passentry.exe | codesign_keygen.exe - signkey.pub signkey.key
 121   ```
 122
 123
 124 License
 125 =======
 126
 127 This work has been released under the **CC0 1.0 Universal** license.
 128
 129 For details, please refer to:
 130 <https://creativecommons.org/publicdomain/zero/1.0/legalcode>