From 58e8195d00cf65598f76ce9d34a92085d9a686f9 Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Tue, 3 Dec 2024 16:01:35 -0100 Subject: [PATCH] fix(signatory): details on interfaces Signed-off-by: Maxence Lange --- .../Signature/Model/IncomingSignedRequest.php | 15 +++++--- .../Signature/Model/SignedRequest.php | 13 +++---- .../Signature/IIncomingSignedRequest.php | 17 ++++------ .../Signature/IOutgoingSignedRequest.php | 7 ++++ .../Security/Signature/ISignatoryManager.php | 3 ++ .../Security/Signature/ISignatureManager.php | 10 ++++++ .../Security/Signature/ISignedRequest.php | 34 +++---------------- 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 d644aa8e1c178..0f7dc7cb77154 100644 --- a/lib/private/Security/Signature/Model/IncomingSignedRequest.php +++ b/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; } /** diff --git a/lib/private/Security/Signature/Model/SignedRequest.php b/lib/private/Security/Signature/Model/SignedRequest.php index 214e43e8cb343..f30935e83b1b1 100644 --- a/lib/private/Security/Signature/Model/SignedRequest.php +++ b/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; } diff --git a/lib/unstable/Security/Signature/IIncomingSignedRequest.php b/lib/unstable/Security/Signature/IIncomingSignedRequest.php index 11a2cdde86865..5c06c41c394eb 100644 --- a/lib/unstable/Security/Signature/IIncomingSignedRequest.php +++ b/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. diff --git a/lib/unstable/Security/Signature/IOutgoingSignedRequest.php b/lib/unstable/Security/Signature/IOutgoingSignedRequest.php index 3901c9e555c02..e9af12ea4b4f4 100644 --- a/lib/unstable/Security/Signature/IOutgoingSignedRequest.php +++ b/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 */ diff --git a/lib/unstable/Security/Signature/ISignatoryManager.php b/lib/unstable/Security/Signature/ISignatoryManager.php index e265b52f75588..c16dace1bded0 100644 --- a/lib/unstable/Security/Signature/ISignatoryManager.php +++ b/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 { diff --git a/lib/unstable/Security/Signature/ISignatureManager.php b/lib/unstable/Security/Signature/ISignatureManager.php index b7a738d95ade2..655454f67e71a 100644 --- a/lib/unstable/Security/Signature/ISignatureManager.php +++ b/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 { diff --git a/lib/unstable/Security/Signature/ISignedRequest.php b/lib/unstable/Security/Signature/ISignedRequest.php index e3c77c9767a81..6bf5e7e7dbc00 100644 --- a/lib/unstable/Security/Signature/ISignedRequest.php +++ b/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 *