Merge branch 'master' of https://github.com/paragonie/chronicle

# Conflicts:
#	sql/sqlite/00-local.sql
#	sql/sqlite/01-remote.sql

Author: paragonie-security

.travis.yml

@@ -12,12 +12,31 @@ matrix:
   allow_failures:
     - php: "nightly"
 
+services:
+    - mysql
+    - postgresql
+
+before_install:
+    - mysql -e 'CREATE DATABASE IF NOT EXISTS test;'
+    - psql -c 'create database travis_ci_test;' -U postgres
+
 install:
     - composer self-update
     - composer update
-    - php bin/install.php
-    - php bin/make-tables.php
 
 script:
+    # Test SQLite
+    - php bin/install.php
+    - php bin/make-tables.php
+    - composer test
+    - composer static-analysis
+    # Test MySQL
+    - php bin/install.php --mysql --host 127.0.0.1 -u root --database test
+    - php bin/make-tables.php
+    - composer test
+    - composer static-analysis
+    # Test PostgreSQL
+    - php bin/install.php --pgsql -u postgres --database travis_ci_test
+    - php bin/make-tables.php
     - composer test
     - composer static-analysis

README.md

@@ -30,6 +30,10 @@ as part of our continued efforts to make the Internet more secure.
 * [How to write (publish) to your  Chronicle](docs/02-publish.md)
 * [How to setup cross-signing to other Chronicles](docs/03-cross-signing.md)
 * [How to replicate other Chronicles](docs/04-replication.md)
+* [Concurrent Instances](docs/05-instances.md)
+* [Internal Developer Documentation](docs/internals)
+    * [Design Philosophy](docs/internals/01-design-philosophy.md)
+    * [SQL Tables](docs/internals/02-sql-tables.md)
 
 ### Client-Side Software that Interacts with Chronicle
 

bin/create-client.php

@@ -36,6 +36,9 @@
     $settings['database']['options'] ?? []
 );
 
+// Pass database instance to Chronicle
+Chronicle::setDatabase($db);
+
 /**
  * @var Getopt $getopt
  *
@@ -110,9 +113,13 @@
 /** @var string $newPublicId */
 $newPublicId = Base64UrlSafe::encode(\random_bytes(24));
 
+// Disable escaping for SQLite
+/** @var boolean $isSQLite */
+$isSQLite = strpos($settings['database']['dsn'] ?? '', 'sqlite:') !== false;
+
 $db->beginTransaction();
 $db->insert(
-    Chronicle::getTableName('clients'),
+    Chronicle::getTableName('clients', $isSQLite),
     [
         'isAdmin' => !empty($admin),
         'publicid' => $newPublicId,

bin/install.php

@@ -1,6 +1,10 @@
 <?php
 declare(strict_types=1);
 
+use GetOpt\{
+    GetOpt,
+    Option
+};
 use ParagonIE\Sapient\CryptographyKeys\SigningSecretKey;
 
 /** @var string $root */
@@ -18,11 +22,74 @@
     $signingKey->getString()
 );
 
+/**
+ * @var Getopt $getopt
+ *
+ * This defines the Command Line options.
+ *
+ * These are many examples:
+ *     php install.php
+ *     php install.php --mysql
+ *     php install.php --pgsql
+ *     php install.php --sqlite
+ *     php install.php --mysql --host localhost --port 3306 --username mysql_user --password mysql_password
+ *     php install.php --pgsql --host=localhost --port=5432 --username=pgsql_user --password=pgsql_password
+ *     php install.php --mysql --h localhost --port 3306 --u mysql_user --p mysql_password
+ *     php install.php --pgsql --h=localhost --port=5432 --u=pgsql_user --p=pgsql_password
+ *     php install.php --sqlite --database chronicle
+ *     php install.php --sqlite --database=chronicle --extension db
+ */
+$getopt = new Getopt([
+    new Option(null, 'mysql', Getopt::OPTIONAL_ARGUMENT),
+    new Option(null, 'pgsql', Getopt::OPTIONAL_ARGUMENT),
+    new Option(null, 'sqlite', Getopt::OPTIONAL_ARGUMENT),
+    new Option('h', 'host', Getopt::OPTIONAL_ARGUMENT),
+    new Option(null, 'port', Getopt::OPTIONAL_ARGUMENT),
+    new Option('d', 'database', Getopt::OPTIONAL_ARGUMENT),
+    new Option('e', 'extension', Getopt::OPTIONAL_ARGUMENT),
+    new Option('u', 'username', Getopt::OPTIONAL_ARGUMENT),
+    new Option('p', 'password', Getopt::OPTIONAL_ARGUMENT),
+]);
+$getopt->process();
+
+/** @var string $mysql */
+$mysql = $getopt->getOption('mysql') ?? false;
+/** @var string $pgsql */
+$pgsql = $getopt->getOption('pgsql') ?? false;
+/** @var string $sqlite */
+$sqlite = $getopt->getOption('sqlite') ?? (!$mysql && !$pgsql);
+/** @var string $host */
+$host = $getopt->getOption('host') ?? 'localhost';
+/** @var string $port */
+$port = $getopt->getOption('port') ?? ($mysql ? '3306' : ($pgsql ? '5432' : ''));
+/** @var string $database */
+$database = $getopt->getOption('database') ?? 'chronicle';
+/** @var string $extension */
+$extension = $getopt->getOption('extension') ?? 'db';
+/** @var string $username */
+$username = $getopt->getOption('username') ?? ($mysql ? 'mysqluser' : ($pgsql ? 'pgsqluser' : ''));
+/** @var string $password */
+$password = $getopt->getOption('password') ?? '';
+
+// default SQLite
+$databaseConfig = [
+    'dsn' => 'sqlite:' . $root . '/local/' . $database . '.' . $extension,
+];
+
+if(!$sqlite){
+
+    $dbType = $mysql ? 'mysql' : 'pgsql';
+
+    $databaseConfig = [
+        'dsn' => $dbType . ':host=' . $host . ';port=' . $port . ';dbname=' . $database,
+        'username' => $username,
+        'password' => $password,
+    ];
+}
+
 // Write the default settings to the local settings file.
 $localSettings = [
-    'database' => [
-        'dsn' => 'sqlite:' . $root . '/local/chronicle.sql'
-    ],
+    'database' => $databaseConfig,
     // Map 'channel-name' => 'table_prefix'
     'instances' => [
         '' => ''

docs/01-setup.md

@@ -9,10 +9,10 @@ General process:
 1. Clone this repository: `git clone https://github.com/paragonie/chronicle.git`
 2. Run `composer install`
    * If you don't have Composer, [go here for **Composer installation** instructions](https://getcomposer.org/download/).
-3. Run `bin/install.php` to generate a keypair and basic configuration file.
+3. Run `php bin/install.php` to generate a keypair and basic configuration file.
 4. Edit `local/settings.json` to configure your Chronicle. For example, you
    can choose a MySQL, PostgreSQL, or SQLite backend. [See below](#configuring-localsettingsjson).
-5. Run `bin/make-tables.php` to setup the database tables 
+5. Run `php bin/make-tables.php` to setup the database tables 
 6. Configure a new virtual host for Apache/nginx/etc. to point to the `public`
    directory, **OR** run `composer start` to launch the built-in web server.
 
@@ -28,6 +28,14 @@ except with information pertinent to your instance and your public key:
 
 ### MySQL
 
+To generate MySQL config simply do the following:
+
+```shell
+php bin/install.php --mysql
+```
+
+The output will be like this:
+
 ```json
 {
   "database": {
@@ -38,8 +46,35 @@ except with information pertinent to your instance and your public key:
   "signing-public-key": "gIQOvAxVbF2zLeanIZDQe7S2gBsabfxM3vP8sjBI_08="
 }
 ```
+
+There are many available options:
+
+```shell
+php bin/install.php --mysql \
+                    --host localhost \
+                    --port 3306 \
+                    --database chronicle \
+                    --username mysql_user \
+                    --password mysql_password
+```
+
+Short format options:
+
+```shell
+php bin/install.php --mysql -h localhost --port 3306 \
+                            -d chronicle -u mysql_user -p mysql_password
+```
+
 ### PostgreSQL
 
+To generate PostgreSQL config simply do the following:
+
+```shell
+php bin/install.php --pgsql
+```
+
+The output will be like this:
+
 ```json
 {
   "database": {
@@ -51,8 +86,34 @@ except with information pertinent to your instance and your public key:
 }
 ```
 
+There are many available options:
+
+```shell
+php bin/install.php --pgsql \
+                    --host localhost \
+                    --port 5432 \
+                    --database chronicle \
+                    --username pgsql_user \
+                    --password pgsql_password
+```
+
+Short format options:
+
+```shell
+php bin/install.php --pgsql -h localhost --port 5432 \
+                            -d chronicle -u pgsql_user -p mysql_password
+```
+
 ### SQLite
 
+To generate SQLite config simply do the following:
+
+```shell
+php bin/install.php
+```
+
+The output will be like this:
+
 ```json
 {
   "database": {
@@ -61,6 +122,17 @@ except with information pertinent to your instance and your public key:
   "signing-public-key": "gIQOvAxVbF2zLeanIZDQe7S2gBsabfxM3vP8sjBI_08="
 }
 ```
+There are many available options:
+
+```shell
+php bin/install.php --sqlite --database live --extension db
+```
+
+Short format options:
+
+```shell
+php bin/install.php --sqlite -d live -e db
+```
 
 
 ## How to add clients to your Chronicle

sql/mysql/00-local.sql

@@ -1,7 +1,7 @@
 CREATE TABLE chronicle_clients (
   `id` BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  `publicid` VARCHAR(128),
-  `publickey` TEXT,
+  `publicid` VARCHAR(128) NOT NULL,
+  `publickey` TEXT NOT NULL,
   `isAdmin` BOOLEAN NOT NULL DEFAULT FALSE,
   `comment` TEXT,
   `created` DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -24,5 +24,6 @@ CREATE TABLE chronicle_chain (
   INDEX(`currhash`),
   INDEX(`summaryhash`),
   FOREIGN KEY (`prevhash`) REFERENCES chronicle_chain(`currhash`) ON DELETE RESTRICT ON UPDATE RESTRICT,
-  UNIQUE(`prevhash`)
-);
+  UNIQUE(`prevhash`),
+  UNIQUE(`currhash`)
+);

sql/mysql/01-remote.sql

@@ -1,31 +1,31 @@
 CREATE TABLE chronicle_xsign_targets (
   `id` BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  `name` TEXT,
-  `url` TEXT,
-  `clientid` TEXT,
-  `publickey` TEXT,
-  `policy` TEXT,
+  `name` TEXT NOT NULL,
+  `url` TEXT NOT NULL,
+  `clientid` TEXT NOT NULL,
+  `publickey` TEXT NOT NULL,
+  `policy` TEXT NOT NULL,
   `lastrun` TEXT
 );
 
 CREATE TABLE chronicle_replication_sources (
   `id` BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  `uniqueid` TEXT,
-  `name` TEXT,
-  `url` TEXT,
-  `publickey` TEXT
+  `uniqueid` TEXT NOT NULL,
+  `name` TEXT NOT NULL,
+  `url` TEXT NOT NULL,
+  `publickey` TEXT NOT NULL
 );
 
 CREATE TABLE chronicle_replication_chain (
   `id` BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  `source` BIGINT UNSIGNED REFERENCES chronicle_replication_sources(`id`) ON DELETE RESTRICT ON UPDATE RESTRICT,
-  `data` TEXT,
+  `source` BIGINT UNSIGNED NOT NULL REFERENCES chronicle_replication_sources(`id`) ON DELETE RESTRICT ON UPDATE RESTRICT,
+  `data` TEXT NOT NULL,
   `prevhash` VARCHAR(128) NULL,
   `currhash` VARCHAR(128) NOT NULL,
-  `hashstate` TEXT,
+  `hashstate` TEXT NOT NULL,
   `summaryhash` VARCHAR(128),
-  `publickey` TEXT,
-  `signature` TEXT,
+  `publickey` TEXT NOT NULL,
+  `signature` TEXT NOT NULL,
   `created` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
   `replicated` TIMESTAMP NULL,
   INDEX(`prevhash`),

sql/pgsql/00-local.sql

@@ -1,7 +1,7 @@
 CREATE TABLE chronicle_clients (
   id BIGSERIAL PRIMARY KEY,
-  publicid TEXT,
-  publickey TEXT,
+  publicid TEXT NOT NULL,
+  publickey TEXT NOT NULL,
   "isAdmin" BOOLEAN NOT NULL DEFAULT FALSE,
   comment TEXT,
   created TIMESTAMP,
@@ -12,16 +12,17 @@ CREATE INDEX chronicle_clients_clientid_idx ON chronicle_clients(publicid);
 
 CREATE TABLE chronicle_chain (
   id BIGSERIAL PRIMARY KEY,
-  data TEXT,
+  data TEXT NOT NULL,
   prevhash TEXT NULL,
-  currhash TEXT,
-  hashstate TEXT,
-  summaryhash TEXT,
-  publickey TEXT,
-  signature TEXT,
+  currhash TEXT NOT NULL,
+  hashstate TEXT NOT NULL,
+  summaryhash TEXT NOT NULL,
+  publickey TEXT NOT NULL,
+  signature TEXT NOT NULL,
   created TIMESTAMP,
-  FOREIGN KEY (currhash) REFERENCES chronicle_chain(prevhash),
-  UNIQUE(prevhash)
+  UNIQUE(currhash),
+  UNIQUE(prevhash),
+  FOREIGN KEY (prevhash) REFERENCES chronicle_chain(currhash)
 );
 
 CREATE INDEX chronicle_chain_prevhash_idx ON chronicle_chain(prevhash);