initial commit (#1)

Co-authored-by: Marco Rieger <[email protected]>

.github/workflows/main.yml

@@ -0,0 +1,40 @@
+name: CI Tests
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php-versions: ['5.6', '7.4']
+    name: Testing PHP ${{ matrix.php-versions }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+      - name: Check PHP Version
+        run: php -v
+      - name: Install Dependencies for PHP ${{ matrix.php-versions }}
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-suggest --no-progress --prefer-dist
+      - name: Execute tests against PHP ${{ matrix.php-versions }}
+        run: composer test
+  typecheck:
+    runs-on: ubuntu-latest
+    name: Typechecks against PSALM
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Check PHP Version
+        run: php -v
+      - name: Install Dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-suggest --no-progress --prefer-dist
+      - name: Downloading
+        run: wget https://github.com/vimeo/psalm/releases/download/3.12.1/psalm.phar
+      - name: Typechecking
+        run: php psalm.phar

.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+/.idea/

README.md

@@ -1,2 +1,105 @@
-# vaultPHP
-A PHP library for vault
+# PHP Hashicorp Vault Client
+
+PHP Client Library for the Hashicorp Vault Service. 
+This Client follows the Request and Response Data equal to the Hashicorp Vault Client Documentation.
+- Authentication https://www.vaultproject.io/api-docs/auth
+- Secret Engines https://www.vaultproject.io/api-docs/secret
+
+Feel free to open Pull Requests to add improvements or missing functionality.
+
+## Implemented Functionality:
+- Auth
+  - User/Password
+  - Token
+  - Kubernetes
+- Secret Engines
+  - Transit Engine
+    - Encrypt/Decrypt
+    - Update Key Config
+    - Create Key
+    - Delete Key
+    - List Keys
+
+## Basic Usage
+
+```php
+// setting up independent http client 
+$httpClient = new Client();
+
+// setting up vault auth provider
+$auth = new Token('foo');
+
+// creating the vault request client
+$client = new VaultClient(
+    $httpClient,
+    $auth,
+    'http://127.0.0.1:8200'
+);
+
+// selecting the desired secret engine
+// e.g. Transit Secret Engine
+$api = new Transit($client);
+
+// calling specific endpoint
+$response = $api->listKeys();
+
+//reading results
+var_dump($response->getKeys());
+//...
+//...
+//Profit...
+```
+
+#### VaultClient
+
+````php
+public function __construct(
+    HttpClient $httpClient,
+    AuthenticationProviderInterface $authProvider,
+    string $apiHost
+)
+````
+
+`HttpClient` takes every PSR-18 compliant HTTP Client Adapter like `"php-http/curl-client": "^1.7"`
+
+`AuthenticationProviderInterface` Authentication Provider from `/authentication/provider/*`
+
+`$apiHost` Hashicorp Vault REST Endpoint URL
+
+## Bulk Requests
+Bulk Requests **will not** throw `InvalidDataExceptions`. Using Bulk Requests requires to iterate through the Response
+and calling `hasErrors` within the `BasicMetaResponse`.
+
+## Exceptions
+Calling library methods will throw exceptions, indicating where ever invalid data was provided
+or HTTP errors occurred or Vault Generic Endpoint Errors are encountered.
+___
+
+`VaultException`
+
+Generic Root Exception where every exception in this library extends from.
+___
+
+`VaultHttpException`
+
+Exception will thrown when something inside the HTTP handling will cause an error.
+___
+
+`VaultAuthenticationException`
+
+Will be thrown when API Endpoint Authentication fails.
+___
+
+`VaultResponseException`
+
+Will be thrown on 5xx status code errors.
+___
+
+`InvalidRouteException`
+
+Calling an Invalid/Non Existing/Disabled Vault API Endpoint will throw this Exception.
+___
+
+`InvalidDataException`
+
+Exception indicates a failed server payload validation. 

composer.json

@@ -0,0 +1,39 @@
+{
+    "name": "mittwald/vault-php",
+    "type": "library",
+    "license": "MIT",
+    "version": "1.0.0",
+    "homepage": "https://www.mittwald.de/",
+    "description": "PHP library for Vault",
+    "require": {
+        "ext-json": "*",
+        "guzzlehttp/psr7": ">=1.6",
+        "php": ">=5.6",
+        "php-http/httplug": ">=1.1.0"
+    },
+    "suggest": {
+        "php-http/curl-client": "CURL Client Adapter"
+    },
+    "require-dev": {
+        "phpunit/phpunit": ">=5.0.0"
+    },
+    "authors": [
+        {
+            "name": "Marco Rieger",
+            "email": "[email protected]"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "VaultPHP\\": "src\\VaultPHP\\"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Test\\VaultPHP\\": "tests\\VaultPHP\\"
+        }
+    },
+    "scripts": {
+        "test": "php ./vendor/bin/phpunit --configuration ./phpunit.xml.dist"
+    }
+}

docker-compose.yml

@@ -0,0 +1,17 @@
+version: "3"
+services:
+  vault:
+    image: vault:latest
+    container_name: vault
+    restart: unless-stopped
+    ports:
+      - "8200:8200"
+    environment:
+      VAULT_ADDR: 'http://0.0.0.0:8200'
+      VAULT_DEV_ROOT_TOKEN_ID: 'test'
+      VAULT_TOKEN: 'test'
+    cap_add:
+      - IPC_LOCK
+    healthcheck:
+      retries: 5
+    command: server -dev

examples/BulkOperations.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Examples;
+
+use Http\Client\Curl\Client;
+use VaultPHP\Authentication\Provider\Token;
+use VaultPHP\Exceptions\VaultException;
+use VaultPHP\Exceptions\VaultResponseException;
+use VaultPHP\SecretEngines\Engines\Transit\Request\CreateKeyRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Request\EncryptData\EncryptData;
+use VaultPHP\SecretEngines\Engines\Transit\Request\EncryptData\EncryptDataBulkRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Request\UpdateKeyConfigRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Transit;
+use VaultPHP\SecretEngines\Engines\Transit\EncryptionType;
+use VaultPHP\VaultClient;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// setting up curl http client with SSL
+$httpClient = new Client(null, null, [
+    CURLOPT_SSLCERT => './ssl.pem',
+    CURLOPT_SSLCERTTYPE => 'PEM',
+    CURLOPT_SSLCERTPASSWD => 'fooBar',
+]);
+
+// provide hashicorp vault auth
+$authenticationProvider = new Token('test');
+
+// initalize the vault request client
+$vaultClient = new VaultClient(
+    $httpClient,
+    $authenticationProvider,
+    'https://127.0.0.1:8200'
+);
+
+// choose your secret engine api
+$transitApi = new Transit($vaultClient);
+
+// do fancy stuff
+try {
+    // create key
+    $exampleKey = new CreateKeyRequest('exampleKeyName');
+    $exampleKey->setType(EncryptionType::RSA_2048);
+    $transitApi->createKey($exampleKey);
+
+    $encryptRequest = new EncryptDataBulkRequest('exampleKeyName');
+    $encryptRequest->addBulkRequests([
+        new EncryptData('cryptMeBabyOneMoreTime::1'),
+        new EncryptData('cryptMeBabyOneMoreTime::2'),
+        new EncryptData('cryptMeBabyOneMoreTime::3'),
+        new EncryptData('cryptMeBabyOneMoreTime::4'),
+    ]);
+    $encryptBulkResponse = $transitApi->encryptDataBulk($encryptRequest);
+
+    foreach($encryptBulkResponse as $bulkResult) {
+        // BULK REQUEST WON'T THROW INVALID DATA EXCEPTIONS
+        // SO YOU ARE RESPONSABLE TO CHECK IF EVERY BULK WAS
+        // SUCCESSFULLY PROCESSED
+        if (!$bulkResult->getBasicMetaResponse()->hasErrors()) {
+            var_dump($bulkResult->getCiphertext());
+        }
+    }
+
+    // update key config and allow deletion
+    $keyConfigExample = new UpdateKeyConfigRequest('exampleKeyName');
+    $keyConfigExample->setDeletionAllowed(true);
+    $transitApi->updateKeyConfig($keyConfigExample);
+
+    // delete key
+    $transitApi->deleteKey('exampleKeyName');
+
+    // list keys
+    $listKeyResponse = $transitApi->listKeys();
+    var_dump($listKeyResponse->getKeys());
+
+} catch (VaultResponseException $exception) {
+    var_dump($exception->getMessage());
+    var_dump($exception->getResponse());
+    var_dump($exception->getRequest());
+
+} catch (VaultException $exception) {
+    var_dump($exception->getMessage());
+}

examples/TransitEncryption.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Examples;
+
+use Http\Client\Curl\Client;
+use VaultPHP\Authentication\Provider\Token;
+use VaultPHP\Exceptions\VaultException;
+use VaultPHP\Exceptions\VaultResponseException;
+use VaultPHP\SecretEngines\Engines\Transit\Request\CreateKeyRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Request\DecryptData\DecryptDataRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Request\EncryptData\EncryptDataRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Request\UpdateKeyConfigRequest;
+use VaultPHP\SecretEngines\Engines\Transit\Transit;
+use VaultPHP\SecretEngines\Engines\Transit\EncryptionType;
+use VaultPHP\VaultClient;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// setting up curl http client with SSL
+$httpClient = new Client(null, null, [
+    CURLOPT_SSLCERT => './ssl.pem',
+    CURLOPT_SSLCERTTYPE => 'PEM',
+    CURLOPT_SSLCERTPASSWD => 'fooBar',
+]);
+
+// provide hashicorp vault auth
+$authenticationProvider = new Token('test');
+
+// initalize the vault request client
+$vaultClient = new VaultClient(
+    $httpClient,
+    $authenticationProvider,
+    'https://127.0.0.1:8200'
+);
+
+// choose your secret engine api
+$transitApi = new Transit($vaultClient);
+
+// do fancy stuff
+try {
+    // create key
+    $exampleKey = new CreateKeyRequest('exampleKeyName');
+    $exampleKey->setType(EncryptionType::CHA_CHA_20_POLY_1305);
+    $transitApi->createKey($exampleKey);
+
+    // list keys
+    $listKeyResponse = $transitApi->listKeys();
+    var_dump($listKeyResponse->getKeys());
+
+    // encrypt data
+    $encryptExample = new EncryptDataRequest('exampleKeyName', 'encryptMe');
+    $encryptResponse = $transitApi->encryptData($encryptExample);
+
+    var_dump($encryptResponse->getCiphertext());
+
+    // decrypt data
+    $decryptExample = new DecryptDataRequest('exampleKeyName', $encryptResponse->getCiphertext());
+    $decryptResponse = $transitApi->decryptData($decryptExample);
+
+    var_dump($decryptResponse->getPlaintext());
+
+    // update key config and allow deletion
+    $keyConfigExample = new UpdateKeyConfigRequest('exampleKeyName');
+    $keyConfigExample->setDeletionAllowed(true);
+    $transitApi->updateKeyConfig($keyConfigExample);
+
+    // delete key
+    $transitApi->deleteKey('exampleKeyName');
+
+    // list keys
+    $listKeyResponse = $transitApi->listKeys();
+    var_dump($listKeyResponse->getKeys());
+
+} catch (VaultResponseException $exception) {
+    var_dump($exception->getMessage());
+    var_dump($exception->getResponse());
+    var_dump($exception->getRequest());
+
+} catch (VaultException $exception) {
+    var_dump($exception->getMessage());
+}

phpunit.xml.dist

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<phpunit bootstrap="./tests/bootstrap.php">
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory suffix=".php">./src/</directory>
+        </whitelist>
+    </filter>
+    <testsuites>
+        <testsuite name="The project's test suite">
+            <directory>./tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>