src/Socialbox/Classes/Cryptography.php

@@ -347,6 +347,43 @@
             }
         }
 
+        /**
+         * Signs a message using the provided private key and a timestamp.
+         *
+         * @param string $message The message to be signed.
+         * @param string $privateKey The base64-encoded private key used for signing.
+         * @param int $timestamp The timestamp to be included in the signed message.
+         * @param bool $hash True to hash the message before signing, false to use the message directly.
+         * @return string The base64-encoded digital signature.
+         * @throws CryptographyException If the message or private key is invalid, or if signing fails.
+         */
+        public static function signTimedMessage(string $message, string $privateKey, int $timestamp, bool $hash=true): string
+        {
+            if (empty($message))
+            {
+                throw new CryptographyException("Empty message provided");
+            }
+
+            if($timestamp <= 0)
+            {
+                throw new CryptographyException("Invalid timestamp provided");
+            }
+
+            if($hash)
+            {
+                $message = hash('sha512', $message);
+            }
+            else
+            {
+                if(!self::validateSha512($message))
+                {
+                    throw new CryptographyException("Invalid SHA-512 hash provided");
+                }
+            }
+
+            return self::signMessage(sprintf("digest:%s;timestamp:%d", $message, $timestamp), $privateKey);
+        }
+
         /**
          * Verifies the validity of a given signature for a message using the provided public key.
          *
@@ -405,6 +442,44 @@
             }
         }
 
+        /**
+         * Verifies the validity of a given signature for a message using the provided public key and timestamp.
+         *
+         * @param string $message The original message that was signed.
+         * @param string $signature The base64-encoded signature to be verified.
+         * @param string $publicKey The base64-encoded public key used to verify the signature.
+         * @param int $timestamp The timestamp to be included in the signed message.
+         * @param bool $hash True to hash the message before verification, false to use the message directly.
+         * @return bool True if the signature is valid; false otherwise.
+         * @throws CryptographyException If any parameter is empty, if the public key or signature is invalid, or if the verification process fails.
+         */
+        public static function verifyTimedMessage(string $message, string $signature, string $publicKey, int $timestamp, bool $hash=true): bool
+        {
+            if (empty($message) || empty($signature) || empty($publicKey))
+            {
+                throw new CryptographyException("Empty parameter(s) provided");
+            }
+
+            if($timestamp <= 0)
+            {
+                throw new CryptographyException("Invalid timestamp provided");
+            }
+
+            if($hash)
+            {
+                $message = hash('sha512', $message);
+            }
+            else
+            {
+                if(!self::validateSha512($message))
+                {
+                    throw new CryptographyException("Invalid SHA-512 hash provided");
+                }
+            }
+
+            return self::verifyMessage(sprintf("digest:%s;timestamp:%d", $message, $timestamp), $signature, $publicKey);
+        }
+
         /**
          * Determines if the provided algorithm is supported.
          *

src/Socialbox/Enums/Status/SignatureVerificationStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+    namespace Socialbox\Enums\Status;
+
+    enum SignatureVerificationStatus : string
+    {
+        /**
+         * The provided signature does not match the expected signature.
+         */
+        case INVALID = 'INVALID';
+
+        /**
+         * The provided signature was valid but the key associated with the signature has expired.
+         */
+        case EXPIRED = 'EXPIRED';
+
+        /**
+         * The provided signature was valid but unable to be verified against the peer's known public key.
+         */
+        case UNVERIFIED = 'UNVERIFIED';
+    }

src/Socialbox/Socialbox.php

@@ -18,6 +18,7 @@
     use Socialbox\Enums\StandardError;
     use Socialbox\Enums\StandardHeaders;
     use Socialbox\Enums\StandardMethods;
+    use Socialbox\Enums\Status\SignatureVerificationStatus;
     use Socialbox\Enums\Types\ContactRelationshipType;
     use Socialbox\Enums\Types\InformationFieldName;
     use Socialbox\Enums\Types\RequestType;
@@ -749,6 +750,56 @@
             }
         }
 
+        /**
+         * @param PeerAddress|string $signingPeer The peer address or string identifier of the signing peer
+         * @param string $signatureUuid The UUID of the signature key to be resolved
+         * @param string $signatureKey The public key of the signature that was used to sign the message
+         * @param string $signature  The signature to be verified
+         * @param string $messageHash The SHA-512 hash of the message that was signed
+         * @param int $signatureTime The time at which the message was signed
+         * @return SignatureVerificationStatus The status of the signature verification
+         */
+        public static function verifyPeerSignature(PeerAddress|string $signingPeer, string $signatureUuid, string $signatureKey, string $signature, string $messageHash, int $signatureTime): SignatureVerificationStatus
+        {
+            $messageHash = sprintf('%s:%d', $messageHash, $signatureTime);
+
+            // First verify the signature with the provided parameters
+            try
+            {
+                if (!Cryptography::verifyMessage($messageHash, $signature, $signatureKey, false))
+                {
+                    return SignatureVerificationStatus::INVALID;
+                }
+            }
+            catch (CryptographyException)
+            {
+                return SignatureVerificationStatus::INVALID;
+            }
+
+            // Resolve the peer signature key
+            try
+            {
+                $signingKey = self::resolvePeerSignature($peerAddress, $signatureUuid);
+            }
+            catch(StandardRpcException)
+            {
+                return SignatureVerificationStatus::UNVERIFIED;
+            }
+
+            // Verify the signature with the resolved key
+            try
+            {
+                if (!Cryptography::verifyMessage($messageHash, $signature, $signingKey->getPublicKey(), false))
+                {
+                    return SignatureVerificationStatus::INVALID;
+                }
+            }
+            catch (CryptographyException)
+            {
+                return SignatureVerificationStatus::INVALID;
+            }
+        }
+
         /**
          * Resolves a peer signature key based on the given peer address or string identifier.
          *