Merge pull request #16 from paragonie/v0.3-dev

Version 0.3 Development

.travis.yml

@@ -21,8 +21,7 @@ install:
   - if [[ ${TRAVIS_PHP_VERSION:0:3} == "5.6" ]]; then composer self-update --1; fi
   - if [[ ${TRAVIS_PHP_VERSION:0:3} == "7.0" ]]; then composer self-update --1; fi
   - composer update
-  - if [[ ${TRAVIS_PHP_VERSION:0:3} == "7.4" ]]; then composer require vimeo/psalm:^3.6; fi
 
 script:
   - vendor/bin/phpunit
-  - if [[ ${TRAVIS_PHP_VERSION:0:3} != "5.6" ]]; then vendor/bin/psalm; fi
+  - if [[ ${TRAVIS_PHP_VERSION:0:3} != "5.6" ]] && [[ ${TRAVIS_PHP_VERSION:0:3} != "7.0" ]]; then vendor/bin/psalm; fi

docs/README.md

@@ -24,6 +24,8 @@ This lets you write code that looks like this:
 ...and then if any keys are compromised, the $keys array will not contain the
 revoked ones.
 
+For more information, please refer to the **[security documentation](security)**.
+
 ### Components
 
 | **Documentation Name** | **Description** |

docs/reference/DbInterface.md

@@ -17,10 +17,16 @@
 
 ### `getCheckpointHash()`
 
+The hash of the latest local entry. This method is used for fetching
+new records from the cryptographic ledger.
+
 **Returns** a `string`
 
 ### `updateMeta()`
 
+Updates the checkpoint hash to the latest retrieved from the 
+cryptographic ledger.
+
 **Arguments**:
 
 1. `string` - Checkpoint Hash
@@ -29,17 +35,26 @@
 
 ### `appendKey()`
 
+Append a new key to the local store.
+
+Note: No identity verification is performed at this step.
+It **MUST** have already been checked at a higher level.
+
 **Arguments**:
 
 1. `string` - Provider
 2. `string` - Public Key
-3. `array` - Metadata
-4. `string` - Hash
+3. `bool` - Limited key?
+4. `string` - Purpose for they key.
+5. `array` - Metadata
+6. `string` - Hash
 
 **Returns** a `bool`.
 
 ### `revokeKey()`
 
+Revoke a public key.
+
 **Arguments**:
 
 1. `string` - Provider
@@ -51,6 +66,8 @@
 
 ### `appendUpdate()`
 
+Appends signature/etc. information about a software update.
+
 **Arguments**:
 
 1. `string` - Provider
@@ -65,6 +82,8 @@
 
 ### `revokeUpdate()`
 
+Revoke an existing update.
+
 **Arguments**:
 
 1. `string` - Provider
@@ -78,6 +97,8 @@
 
 ### `providerExists()`
 
+Have we seen this Provider before?
+
 **Arguments**:
 
 1. `string` - Provider Name
@@ -86,14 +107,26 @@
 
 ### `getPublicKeysForProvider()`
 
+Returns the Verification Keys (Ed25519 public keys) for a given provider.
+
 **Arguments**:
 
 1. `string` - Provider Name
+2. `?bool` - Limited keys?
+   * If you pass as TRUE, this method only returns limited keys.
+   * If you pass as FALSE, this method only returns non-limited keys.
+   * If you pass as NULL (default), it returns both kinds.
+3. `?string` - Purpose?
+   * If you pass as an empty string, this method disregards purpose.
+   * If you pass as a non-empty string, this method only returns keys that match that purpose.
+   * If you pass as NULL (default), it only returns keys without a purpose.
 
 **Returns** an `array` of `string`s. 
 
 ### `getPackageId()`
 
+Returns the database primary key for this package.
+
 **Arguments**:
 
 1. `string` - Package Name
@@ -103,6 +136,8 @@
 
 ### `getProviderId()`
 
+Returns the database primary key for this provider.
+
 **Arguments**:
 
 1. `string` - Provider Name
@@ -111,6 +146,8 @@
 
 ### `getPublicKeyId()`
 
+Returns the database primary key for this public key.
+
 **Arguments**:
 
 1. `string` - Public Key

docs/reference/HttpInterface.md

@@ -6,6 +6,8 @@
 
 ### `get()`
 
+Performs an HTTP GET request.
+
 **Arguments**:
 
 1. `string` - URL
@@ -18,6 +20,8 @@ Returns an `array`:
 
 ### `post()`
 
+Performs an HTTP POST request.
+
 **Arguments**:
 
 1. `string` - URL

docs/reference/LedgerInterface.md

@@ -6,10 +6,14 @@
 
 ### `clearInstances()`
 
+Returns a new instance of this ledger with no peer instances.
+
 Returns this object that implements `LedgerInterface`.
 
 ### `populateInstances()`
 
+Returns a new instance of this ledger with the given peers.
+
 **Arguments**:
 
 1. `array` - Instances

docs/reference/LedgerVerifierInterface.md

@@ -0,0 +1,18 @@
+# Libgossamer API Reference - LedgerVerifierInterface
+
+* **Fully Qualified Interface Name**: `ParagonIE\Gossamer\LedgerVerifierInterface`
+
+This interface extends both [`LedgerInterface`](LedgerInterface.md) and
+[`VerifierInterface`](VerifierInterface.md). 
+
+## Interface Methods
+
+### `signedMessageFound()`
+
+Was this `SignedMessage` found in the ledger?
+
+**Arguments**:
+
+1. `SignedMessage` $signedMessage
+
+Returns a `bool`.

docs/reference/Synchronizer.md

@@ -7,13 +7,24 @@ parsing [`Action`](Protocol/Action.md) objects from the
 [`SignedMessage`](Protocol/SignedMessage.md) objects defined in the ledger, and
 then performing each action against the local database.
 
+The public method most implementations will want to call is [`sync()`](#sync).
+
+### Security Note
+
+**MOST security decisions** (i.e. which public keys belong to which provider,
+whether or not to trust a "Super Provider") are the responsibility of this class,
+and the rest of the components assume that this logic has been followed.
+
+Therefore, the implementation of this class (and any code it calls) is crucial
+to the secure operation of libgossamer.
+
 ## Constructor
 
 **Arguments**:
 
 1. [`DbInterface`](DbInterface.md)
 2. [`HttpInterface`](HttpInterface.md)
-3. [`VerifierInterface`](VerifierInterface.md)
+3. [`LedgerVerifierInterface`](LedgerVerifierInterface.md)
 4. `array` - Pool of ledgers. Each item in this array must be an array with the following keys:
    1. `url`: `string`
    2. `public-key`: `string`
@@ -56,7 +67,7 @@ Both the source and each peer will an array with the following keys:
 
 1. `array` - Peers
 
-**Returns** an object that implements [`VerifierInterface`](VerifierInterface.md).
+**Returns** an object that implements [`LedgerVerifierInterface`](LedgerVerifierInterface.md).
 
 ### `sync()`
 
@@ -73,6 +84,6 @@ the Synchronizer's [`DbInterface`](DbInterface.md) object.
 **Arguments**:
 
 1. `SignedMessage[]`
-2. `VerifierInterface`
+2. `LedgerVerifierInterface`
 
 **Returns** a `bool`.

docs/security/README.md

@@ -0,0 +1,5 @@
+# Security Documentation
+
+This section contains documentation of interest to security researchers.
+
+* [Threat Model](Threat-Model.md)