fix(signatory): details on interfaces

Signed-off-by: Maxence Lange <maxence@artificial-owl.com>

7 files changed, 49 insertions, 50 deletions

diff --git a/lib/private/Security/Signature/Model/IncomingSignedRequest.php b/lib/private/Security/Signature/Model/IncomingSignedRequest.php
index d644aa8e1c1..0f7dc7cb771 100644
--- a/lib/private/Security/Signature/Model/IncomingSignedRequest.php
+++ b/lib/private/Security/Signature/Model/IncomingSignedRequest.php
@@ -9,6 +9,7 @@ declare(strict_types=1);
 namespace OC\Security\Signature\Model;
 
 use JsonSerializable;
+use NCU\Security\Signature\Enum\DigestAlgorithm;
 use NCU\Security\Signature\Enum\SignatureAlgorithm;
 use NCU\Security\Signature\Exceptions\IdentityNotFoundException;
 use NCU\Security\Signature\Exceptions\IncomingRequestException;
@@ -22,6 +23,7 @@ use NCU\Security\Signature\ISignatureManager;
 use NCU\Security\Signature\Model\Signatory;
 use OC\Security\Signature\SignatureManager;
 use OCP\IRequest;
+use ValueError;
 
 /**
  * @inheritDoc
@@ -107,6 +109,12 @@ class IncomingSignedRequest extends SignedRequest implements
 		}
 
 		// confirm digest value, based on body
+		[$algo, ] = explode('=', $digest);
+		try {
+			$this->setDigestAlgorithm(DigestAlgorithm::from($algo));
+		} catch (ValueError) {
+			throw new IncomingRequestException('unknown digest algorithm');
+		}
 		if ($digest !== $this->getDigest()) {
 			throw new IncomingRequestException('invalid value for digest in header');
 		}
@@ -188,15 +196,14 @@ class IncomingSignedRequest extends SignedRequest implements
 	}
 
 	/**
-	 * @inheritDoc
+	 * set the hostname at the source of the request,
+	 * based on the keyId defined in the signature header.
 	 *
 	 * @param string $origin
-	 * @return IIncomingSignedRequest
 	 * @since 31.0.0
 	 */
-	public function setOrigin(string $origin): IIncomingSignedRequest {
+	private function setOrigin(string $origin): void {
 		$this->origin = $origin;
-		return $this;
 	}
 
 	/**
diff --git a/lib/private/Security/Signature/Model/SignedRequest.php b/lib/private/Security/Signature/Model/SignedRequest.php
index 214e43e8cb3..f30935e83b1 100644
--- a/lib/private/Security/Signature/Model/SignedRequest.php
+++ b/lib/private/Security/Signature/Model/SignedRequest.php
@@ -44,14 +44,15 @@ class SignedRequest implements ISignedRequest, JsonSerializable {
 	}
 
 	/**
-	 * @inheritDoc
+	 * set algorithm used to generate digest
 	 *
 	 * @param DigestAlgorithm $algorithm
 	 *
 	 * @return self
 	 * @since 31.0.0
 	 */
-	public function setDigestAlgorithm(DigestAlgorithm $algorithm): self {
+	protected function setDigestAlgorithm(DigestAlgorithm $algorithm): self {
+		$this->digestAlgorithm = $algorithm;
 		return $this;
 	}
 
@@ -119,14 +120,14 @@ class SignedRequest implements ISignedRequest, JsonSerializable {
 	}
 
 	/**
-	 * @inheritDoc
+	 * store data used to generate signature
 	 *
 	 * @param array $data
 	 *
 	 * @return self
 	 * @since 31.0.0
 	 */
-	public function setSignatureData(array $data): self {
+	protected function setSignatureData(array $data): self {
 		$this->signatureData = $data;
 		return $this;
 	}
@@ -142,14 +143,14 @@ class SignedRequest implements ISignedRequest, JsonSerializable {
 	}
 
 	/**
-	 * @inheritDoc
+	 * set the signed version of the signature
 	 *
 	 * @param string $signature
 	 *
 	 * @return self
 	 * @since 31.0.0
 	 */
-	public function setSignature(string $signature): self {
+	protected function setSignature(string $signature): self {
 		$this->signature = $signature;
 		return $this;
 	}
diff --git a/lib/unstable/Security/Signature/IIncomingSignedRequest.php b/lib/unstable/Security/Signature/IIncomingSignedRequest.php
index 11a2cdde868..5c06c41c394 100644
--- a/lib/unstable/Security/Signature/IIncomingSignedRequest.php
+++ b/lib/unstable/Security/Signature/IIncomingSignedRequest.php
@@ -17,6 +17,13 @@ use OCP\IRequest;
  * model wrapping an actual incoming request, adding details about the signature and the
  * authenticity of the origin of the request.
  *
+ * This interface must not be implemented in your application but
+ * instead obtained from {@see ISignatureManager::getIncomingSignedRequest}.
+ *
+ *  ```php
+ *  $signedRequest = $this->signatureManager->getIncomingSignedRequest($mySignatoryManager);
+ *  ```
+ *
  * @see ISignatureManager for details on signature
  * @experimental 31.0.0
  */
@@ -30,16 +37,6 @@ interface IIncomingSignedRequest extends ISignedRequest {
 	public function getRequest(): IRequest;
 
 	/**
-	 * set the hostname at the source of the request,
-	 * based on the keyId defined in the signature header.
-	 *
-	 * @param string $origin
-	 * @return IIncomingSignedRequest
-	 * @experimental 31.0.0
-	 */
-	public function setOrigin(string $origin): IIncomingSignedRequest;
-
-	/**
 	 * get the hostname at the source of the base request.
 	 * based on the keyId defined in the signature header.
 	 *
diff --git a/lib/unstable/Security/Signature/IOutgoingSignedRequest.php b/lib/unstable/Security/Signature/IOutgoingSignedRequest.php
index 3901c9e555c..e9af12ea4b4 100644
--- a/lib/unstable/Security/Signature/IOutgoingSignedRequest.php
+++ b/lib/unstable/Security/Signature/IOutgoingSignedRequest.php
@@ -15,6 +15,13 @@ use NCU\Security\Signature\Exceptions\SignatoryNotFoundException;
 /**
  * extends ISignedRequest to add info requested at the generation of the signature
  *
+ *  This interface must not be implemented in your application but
+ *  instead obtained from {@see ISignatureManager::getIncomingSignedRequest}.
+ *
+ *   ```php
+ *   $signedRequest = $this->signatureManager->getIncomingSignedRequest($mySignatoryManager);
+ *   ```
+ *
  * @see ISignatureManager for details on signature
  * @experimental 31.0.0
  */
diff --git a/lib/unstable/Security/Signature/ISignatoryManager.php b/lib/unstable/Security/Signature/ISignatoryManager.php
index e265b52f755..c16dace1bde 100644
--- a/lib/unstable/Security/Signature/ISignatoryManager.php
+++ b/lib/unstable/Security/Signature/ISignatoryManager.php
@@ -15,6 +15,9 @@ use NCU\Security\Signature\Model\Signatory;
  *   - signing outgoing request
  *   - confirm the authenticity of incoming signed request.
  *
+ * This interface must be implemented to generate a `SignatoryManager` to
+ *  be used with {@see ISignatureManager}
+ *
  * @experimental 31.0.0
  */
 interface ISignatoryManager {
diff --git a/lib/unstable/Security/Signature/ISignatureManager.php b/lib/unstable/Security/Signature/ISignatureManager.php
index b7a738d95ad..655454f67e7 100644
--- a/lib/unstable/Security/Signature/ISignatureManager.php
+++ b/lib/unstable/Security/Signature/ISignatureManager.php
@@ -41,6 +41,16 @@ use NCU\Security\Signature\Model\Signatory;
  *      listed in 'headers' and their value. Some elements (content-length date digest host) are mandatory
  *      to ensure authenticity override protection.
  *
+ * This interface can be used to inject {@see SignatureManager} in your code:
+ *
+ * ```php
+ *    public function __construct(
+ *        private ISignatureManager $signatureManager,
+ *    ) {}
+ *  ```
+ *
+ *   instead obtained from {@see ISignatureManager::getIncomingSignedRequest}.
+ *
  * @experimental 31.0.0
  */
 interface ISignatureManager {
diff --git a/lib/unstable/Security/Signature/ISignedRequest.php b/lib/unstable/Security/Signature/ISignedRequest.php
index e3c77c9767a..6bf5e7e7dbc 100644
--- a/lib/unstable/Security/Signature/ISignedRequest.php
+++ b/lib/unstable/Security/Signature/ISignedRequest.php
@@ -19,6 +19,10 @@ use NCU\Security\Signature\Model\Signatory;
  * - to confirm authenticity of a signed incoming request
  * - to sign an outgoing request
  *
+ * This interface must not be implemented in your application:
+ * @see IIncomingSignedRequest
+ * @see IOutgoingSignedRequest
+ *
  * @experimental 31.0.0
  */
 interface ISignedRequest {
@@ -31,16 +35,6 @@ interface ISignedRequest {
 	public function getBody(): string;
 
 	/**
-	 * set algorithm used to generate digest
-	 *
-	 * @param DigestAlgorithm $algorithm
-	 *
-	 * @return self
-	 * @experimental 31.0.0
-	 */
-	public function setDigestAlgorithm(DigestAlgorithm $algorithm): self;
-
-	/**
 	 * get algorithm used to generate digest
 	 *
 	 * @return DigestAlgorithm
@@ -84,16 +78,6 @@ interface ISignedRequest {
 	public function getSigningElement(string $key): string;
 
 	/**
-	 * store data used to generate signature
-	 *
-	 * @param array $data
-	 *
-	 * @return self
-	 * @experimental 31.0.0
-	 */
-	public function setSignatureData(array $data): self;
-
-	/**
 	 * returns data used to generate signature
 	 *
 	 * @return array
@@ -102,16 +86,6 @@ interface ISignedRequest {
 	public function getSignatureData(): array;
 
 	/**
-	 * set the signed version of the signature
-	 *
-	 * @param string $signature
-	 *
-	 * @return self
-	 * @experimental 31.0.0
-	 */
-	public function setSignature(string $signature): self;
-
-	/**
 	 * get the signed version of the signature
 	 *
 	 * @return string