Add shortcut key-store for combined PEM client certificates

.phive/phars.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phive xmlns="https://phar.io/phive">
   <phar name="psalm" version="^5.9.0" installed="5.9.0" location="./tools/psalm.phar" copy="true"/>
-  <phar name="php-cs-fixer" version="^3.13.0" installed="3.13.0" location="./tools/php-cs-fixer.phar" copy="true"/>
+  <phar name="php-cs-fixer" version="^3.30.0" installed="3.39.0" location="./tools/php-cs-fixer.phar" copy="true"/>
 </phive>

README.md

@@ -97,10 +97,30 @@ $wsseMiddleware = new WsseMiddleware(
 );
 ```
 
-#### Signing a SOAP request with PKCS12 or X509 certificate.
+### Key stores
 
-This is one of the most common implementation of WSS out there.
-You are granted a certificate by the soap service with which you need to fetch data.
+This package provides a couple of `Key` wrappers that can be used to pass private / public keys:
+
+* `KeyStore\Certificate`: Contains a public X.509 certificate in PEM format.
+* `KeyStore\Key`: Contains a PKCS_8 private key in PEM format.
+* `KeyStore\ClientCertificate`: Contains both a public X.509 certificate and PKCS_8 private key in PEM format.
+
+Example:
+
+```php
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Certificate;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\ClientCertificate;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Key;
+
+$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx'); // Regular private key (not wrapped in X509)
+$pubKey = Certificate::fromFile('security_token.pub'); // Public X509 cert
+
+// or:
+
+$bundle = ClientCertificate::fromFile('client-certificate.pem')->withPassphrase('xxx');
+$privKey = $bunlde->privateKey();
+$pubKey = $bunlde->publicCertificate();
+```
 
 In case of a p12 certificate: convert it to a private key and public X509 certificate first:
 
@@ -109,6 +129,11 @@ openssl pkcs12 -in your.p12 -out security_token.pub -clcerts -nokeys
 openssl pkcs12 -in your.p12 -out security_token.priv -nocerts -nodes
 ```
 
+#### Signing a SOAP request with PKCS12 or X509 certificate.
+
+This is one of the most common implementation of WSS out there.
+You are granted a certificate by the soap service with which you need to fetch data.
+
 Next, you can configure the middleware like this:
 
 ```php
@@ -120,8 +145,8 @@ use Soap\Psr18WsseMiddleware\WSSecurity\KeyIdentifier;
 use Soap\Psr18WsseMiddleware\WsseMiddleware;
 use Soap\Psr18WsseMiddleware\WSSecurity\Entry;
 
-$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx'); // Regular private key (not wrapped in X509)
-$pubKey = Certificate::fromFile('security_token.pub'); // Public X509 cert
+$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx');
+$pubKey = Certificate::fromFile('security_token.pub');
 
 $wsseMiddleware = new WsseMiddleware(
     outgoing: [
@@ -162,7 +187,7 @@ use Soap\Psr18WsseMiddleware\WSSecurity\Entry;
 use VeeWee\Xml\Dom\Document;
 use function VeeWee\Xml\Dom\Locator\document_element;
 
-$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx'); // Regular private key (not wrapped in X509)
+$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx');
 
 // These are provided through the STS service.
 $samlAssertion = Document::fromXmlString(<<<EOXML
@@ -227,7 +252,7 @@ use Soap\Psr18WsseMiddleware\WSSecurity\KeyIdentifier;
 use Soap\Psr18WsseMiddleware\WsseMiddleware;
 use Soap\Psr18WsseMiddleware\WSSecurity\Entry;
 
-$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx'); // Regular private key (not wrapped in X509)
+$privKey = Key::fromFile('security_token.priv')->withPassphrase('xxx'); // Private key
 $pubKey = Certificate::fromFile('security_token.pub'); // Public X509 cert
 $signKey = Certificate::fromFile('sign-key.pem'); // X509 cert for signing. Could be the same as $pubKey.
 

src/OpenSSL/Exception/InvalidKeyException.php

@@ -0,0 +1,19 @@
+<?php
+declare(strict_types=1);
+
+namespace Soap\Psr18WsseMiddleware\OpenSSL\Exception;
+
+use RuntimeException;
+
+final class InvalidKeyException extends RuntimeException
+{
+    public static function unableToReadPrivateKey(): self
+    {
+        return new self('Unable to read the format of the provided private key.');
+    }
+
+    public static function unableToReadPublicKey(): self
+    {
+        return new self('Unable to read the format of the provided public key.');
+    }
+}

src/OpenSSL/Parser/PrivateKeyParser.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace Soap\Psr18WsseMiddleware\OpenSSL\Parser;
+
+use ParagonIE\HiddenString\HiddenString;
+use Soap\Psr18WsseMiddleware\OpenSSL\Exception\InvalidKeyException;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Key;
+
+final class PrivateKeyParser
+{
+    public function __invoke(HiddenString $privateKey, ?HiddenString $password = null): Key
+    {
+        $parsed = '';
+        $key = @openssl_pkey_get_private($privateKey->getString(), $password?->getString() ?: null);
+        if (!$key) {
+            throw InvalidKeyException::unableToReadPrivateKey();
+        }
+
+        $result = @openssl_pkey_export($key, $parsed, $password?->getString() ?: null);
+        if (!$result) {
+            throw InvalidKeyException::unableToReadPrivateKey();
+        }
+
+        return (new Key($parsed))->withPassphrase($password?->getString() ?? '');
+    }
+}

src/OpenSSL/Parser/X509PublicCertificateParser.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace Soap\Psr18WsseMiddleware\OpenSSL\Parser;
+
+use ParagonIE\HiddenString\HiddenString;
+use Soap\Psr18WsseMiddleware\OpenSSL\Exception\InvalidKeyException;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Certificate;
+
+final class X509PublicCertificateParser
+{
+    public function __invoke(HiddenString $publicKey): Certificate
+    {
+        $parsed = '';
+        $key = @openssl_x509_read($publicKey->getString());
+        if (!$key) {
+            throw InvalidKeyException::unableToReadPublicKey();
+        }
+
+        $result = @openssl_x509_export($key, $parsed);
+        if (!$result) {
+            throw InvalidKeyException::unableToReadPublicKey();
+        }
+
+        return new Certificate($parsed);
+    }
+}

src/WSSecurity/KeyStore/Certificate.php

@@ -6,6 +6,9 @@
 use ParagonIE\HiddenString\HiddenString;
 use function Psl\File\read;
 
+/**
+ * Contains a PEM representation of a public X.509 Certificate.
+ */
 final class Certificate implements KeyInterface
 {
     private HiddenString $key;

src/WSSecurity/KeyStore/ClientCertificate.php

@@ -0,0 +1,74 @@
+<?php
+declare(strict_types=1);
+
+namespace Soap\Psr18WsseMiddleware\WSSecurity\KeyStore;
+
+use ParagonIE\HiddenString\HiddenString;
+use Soap\Psr18WsseMiddleware\OpenSSL\Parser\PrivateKeyParser;
+use Soap\Psr18WsseMiddleware\OpenSSL\Parser\X509PublicCertificateParser;
+use function Psl\File\read;
+
+/**
+ * Contains a PEM bundle of both public X.509 Certificate and an (un)encrypted private key PKCS_8.
+ */
+final class ClientCertificate implements KeyInterface
+{
+    private HiddenString $key;
+    private HiddenString $passphrase;
+
+    public function __construct(string $key)
+    {
+        $this->key = new HiddenString($key);
+        $this->passphrase = new HiddenString('');
+    }
+
+    /**
+     * @param non-empty-string $file
+     */
+    public static function fromFile(string $file): self
+    {
+        return new self(read($file));
+    }
+
+    /**
+     * Parse out the private part of the bundled X509 certificate.
+     */
+    public function privateKey(): Key
+    {
+        return (new PrivateKeyParser())($this->key, $this->passphrase);
+    }
+
+    /**
+     * Parse out the public part of the bundled X509 certificate.
+     */
+    public function publicCertificate(): Certificate
+    {
+        return (new X509PublicCertificateParser())($this->key);
+    }
+
+    /**
+     * Provides the full content of the bundled pem certificate.
+     */
+    public function contents(): string
+    {
+        return $this->key->getString();
+    }
+
+    public function passphrase(): string
+    {
+        return $this->passphrase->getString();
+    }
+
+    public function isCertificate(): bool
+    {
+        return true;
+    }
+
+    public function withPassphrase(string $passphrase): self
+    {
+        $new = clone $this;
+        $new->passphrase = new HiddenString($passphrase);
+
+        return $new;
+    }
+}

src/WSSecurity/KeyStore/Key.php

@@ -6,6 +6,9 @@
 use ParagonIE\HiddenString\HiddenString;
 use function Psl\File\read;
 
+/**
+ * Contains a PEM representation of an (un)encrypted private key (PKCS_8).
+ */
 final class Key implements KeyInterface
 {
     private HiddenString $key;

tests/Unit/OpenSSL/Parser/PrivateKeyParserTest.php

@@ -0,0 +1,73 @@
+<?php
+declare(strict_types=1);
+
+namespace SoapTest\Psr18WsseMiddleware\Unit\OpenSSL\Parser;
+
+use ParagonIE\HiddenString\HiddenString;
+use PHPUnit\Framework\TestCase;
+use Soap\Psr18WsseMiddleware\OpenSSL\Exception\InvalidKeyException;
+use Soap\Psr18WsseMiddleware\OpenSSL\Parser\PrivateKeyParser;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Key;
+use function Psl\File\read;
+
+final class PrivateKeyParserTest extends TestCase
+{
+
+    public function test_it_can_read_private_key(): void
+    {
+        $key = $this->createPrivateKey();
+        $parser = new PrivateKeyParser();
+
+        $actual = $parser(new HiddenString($key));
+
+        static::assertInstanceOf(Key::class, $actual);
+        static::assertSame($key, $actual->contents());
+    }
+
+    public function test_it_can_read_encrypted_private_key(): void
+    {
+        $key = $this->createPrivateKey($passPhrase = 'password');
+        $parser = new PrivateKeyParser();
+
+        static::assertStringContainsString('ENCRYPTED PRIVATE KEY', $key);
+
+        $actual = $parser(new HiddenString($key), new HiddenString($passPhrase));
+
+        static::assertInstanceOf(Key::class, $actual);
+        static::assertSame($passPhrase, $actual->passphrase());
+        static::assertStringContainsString('ENCRYPTED PRIVATE KEY', $actual->contents());
+    }
+
+    public function test_it_can_read_from_bundle(): void
+    {
+        $bundle = FIXTURE_DIR . '/certificates/wsse-client-x509.pem';
+        $parser = new PrivateKeyParser();
+
+        $actual = $parser(new HiddenString(read($bundle)));
+
+        static::assertInstanceOf(Key::class, $actual);
+        static::assertSame('', $actual->passphrase());
+        static::assertStringContainsString('PRIVATE KEY', $actual->contents());
+    }
+
+    public function test_it_can_not_read_invalid_private_key(): void
+    {
+        $key = 'notavalidkey';
+        $parser = new PrivateKeyParser();
+
+        $this->expectException(InvalidKeyException::class);
+        $parser(new HiddenString($key));
+    }
+
+    private function createPrivateKey(?string $passPhrase = null): string
+    {
+        $key = openssl_pkey_new();
+        static::assertNotFalse($key);
+
+        $parsed = '';
+        $result = openssl_pkey_export($key, $parsed, $passPhrase);
+        static::assertNotFalse($result);
+
+        return $parsed;
+    }
+}

tests/Unit/OpenSSL/Parser/X509PublicCertificateParserTest.php

@@ -0,0 +1,46 @@
+<?php
+declare(strict_types=1);
+
+namespace SoapTest\Psr18WsseMiddleware\Unit\OpenSSL\Parser;
+
+use ParagonIE\HiddenString\HiddenString;
+use PHPUnit\Framework\TestCase;
+use Soap\Psr18WsseMiddleware\OpenSSL\Exception\InvalidKeyException;
+use Soap\Psr18WsseMiddleware\OpenSSL\Parser\X509PublicCertificateParser;
+use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Certificate;
+use function Psl\File\read;
+
+final class X509PublicCertificateParserTest extends TestCase
+{
+
+    public function test_it_can_read_public_x509_key(): void
+    {
+        $parser = new X509PublicCertificateParser();
+        $file = FIXTURE_DIR . '/certificates/wsse-server-x509.crt';
+
+        $actual = $parser(new HiddenString(read($file)));
+
+        static::assertInstanceOf(Certificate::class, $actual);
+        static::assertStringEqualsFile($file, $actual->contents());
+    }
+
+    public function test_it_can_read_from_bundle(): void
+    {
+        $bundle = FIXTURE_DIR . '/certificates/wsse-client-x509.pem';
+        $parser = new X509PublicCertificateParser();
+
+        $actual = $parser(new HiddenString(read($bundle)));
+
+        static::assertInstanceOf(Certificate::class, $actual);
+        static::assertStringContainsString('CERTIFICATE', $actual->contents());
+    }
+
+    public function test_it_can_not_read_invalid_certificate(): void
+    {
+        $key = 'notavalidkey';
+        $parser = new X509PublicCertificateParser();
+
+        $this->expectException(InvalidKeyException::class);
+        $parser(new HiddenString($key));
+    }
+}