fix(signatory): details on interfaces

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

lib/private/Security/Signature/Model/IncomingSignedRequest.php

@@ -9,6 +9,7 @@
 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\Model\Signatory;
 use OC\Security\Signature\SignatureManager;
 use OCP\IRequest;
+use ValueError;
 
 /**
  * @inheritDoc
@@ -107,6 +109,12 @@ private function verifyHeaders(): void {
 		}
 
 		// 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 @@ public function getRequest(): IRequest {
 	}
 
 	/**
-	 * @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;
 	}
 
 	/**

lib/private/Security/Signature/Model/SignedRequest.php

@@ -44,14 +44,15 @@ public function getBody(): string {
 	}
 
 	/**
-	 * @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 @@ public function getSigningElement(string $key): string { // getSignatureDetail /
 	}
 
 	/**
-	 * @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 @@ public function getSignatureData(): array {
 	}
 
 	/**
-	 * @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;
 	}

lib/unstable/Security/Signature/IIncomingSignedRequest.php

@@ -17,6 +17,13 @@
  * 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
  */
@@ -29,16 +36,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.

lib/unstable/Security/Signature/IOutgoingSignedRequest.php

@@ -15,6 +15,13 @@
 /**
  * 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
  */

lib/unstable/Security/Signature/ISignatoryManager.php

@@ -15,6 +15,9 @@
  *   - 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 {

lib/unstable/Security/Signature/ISignatureManager.php

@@ -41,6 +41,16 @@
  *      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 {

lib/unstable/Security/Signature/ISignedRequest.php

@@ -19,6 +19,10 @@
  * - 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 {
@@ -30,16 +34,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
 	 *
@@ -83,16 +77,6 @@ public function getSigningElements(): array;
 	 */
 	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
 	 *
@@ -101,16 +85,6 @@ public function setSignatureData(array $data): self;
 	 */
 	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
 	 *