Add SensitiveParameter to secrets

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 1.0.3 under development
 
-- no changes in this release.
+- Enh #62: Use `SensitiveParameter` attribute to mark sensitive parameters (@dehbka, @vjik)
 
 ## 1.0.2 March 18, 2024
 

src/Crypt.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Security;
 
+use SensitiveParameter;
 use Yiisoft\Strings\StringHelper;
 
 final class Crypt
@@ -55,7 +56,7 @@
             throw new \RuntimeException('Encryption requires the OpenSSL PHP extension.');
         }
         if (!array_key_exists($cipher, self::ALLOWED_CIPHERS)) {
             throw new \RuntimeException($cipher . ' is not an allowed cipher.');
         }
 
         $this->cipher = $cipher;
@@ -123,8 +124,11 @@
      * @see decryptByPassword()
      * @see encryptByKey()
      */
-    public function encryptByPassword(string $data, string $password): string
-    {
+    public function encryptByPassword(
+        string $data,
+        #[SensitiveParameter]
+        string $password
+    ): string {
         return $this->encrypt($data, true, $password, '');
     }
 
@@ -150,8 +154,12 @@
      * @see decryptByKey()
      * @see encryptByPassword()
      */
-    public function encryptByKey(string $data, string $inputKey, string $info = ''): string
-    {
+    public function encryptByKey(
+        string $data,
+        #[SensitiveParameter]
+        string $inputKey,
+        string $info = ''
+    ): string {
         return $this->encrypt($data, false, $inputKey, $info);
     }
 
@@ -169,8 +177,11 @@
      *
      * @see encryptByPassword()
      */
-    public function decryptByPassword(string $data, string $password): string
-    {
+    public function decryptByPassword(
+        string $data,
+        #[SensitiveParameter]
+        string $password
+    ): string {
         return $this->decrypt($data, true, $password, '');
     }
 
@@ -190,8 +201,12 @@
      *
      * @see encryptByKey()
      */
-    public function decryptByKey(string $data, string $inputKey, string $info = ''): string
-    {
+    public function decryptByKey(
+        string $data,
+        #[SensitiveParameter]
+        string $inputKey,
+        string $info = ''
+    ): string {
         return $this->decrypt($data, false, $inputKey, $info);
     }
 
@@ -211,8 +226,13 @@
      *
      * @see decrypt()
      */
-    private function encrypt(string $data, bool $passwordBased, string $secret, string $info = ''): string
-    {
+    private function encrypt(
+        string $data,
+        bool $passwordBased,
+        #[SensitiveParameter]
+        string $secret,
+        string $info = ''
+    ): string {
         [$blockSize, $keySize] = self::ALLOWED_CIPHERS[$this->cipher];
 
         $keySalt = random_bytes($keySize);
@@ -226,7 +246,7 @@
 
         $encrypted = openssl_encrypt($data, $this->cipher, $key, OPENSSL_RAW_DATA, $iv);
         if ($encrypted === false) {
             throw new \RuntimeException('OpenSSL failure on encryption: ' . openssl_error_string());
         }
 
         $authKey = hash_hkdf($this->kdfAlgorithm, $key, $keySize, $this->authorizationKeyInfo);
@@ -257,8 +277,13 @@
      *
      * @see encrypt()
      */
-    private function decrypt(string $data, bool $passwordBased, string $secret, string $info): string
-    {
+    private function decrypt(
+        string $data,
+        bool $passwordBased,
+        #[SensitiveParameter]
+        string $secret,
+        string $info
+    ): string {
         [$blockSize, $keySize] = self::ALLOWED_CIPHERS[$this->cipher];
 
         $keySalt = StringHelper::byteSubstring($data, 0, $keySize);
@@ -281,7 +306,7 @@
 
         $decrypted = openssl_decrypt($encrypted, $this->cipher, $key, OPENSSL_RAW_DATA, $iv);
         if ($decrypted === false) {
             throw new \RuntimeException('OpenSSL failure on decryption: ' . openssl_error_string());
         }
 
         return $decrypted;

src/Mac.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Security;
 
+use SensitiveParameter;
 use Yiisoft\Strings\StringHelper;
 
 /**
@@ -51,8 +52,12 @@ public function __construct(string $algorithm = 'sha256')
      * @see hkdf()
      * @see pbkdf2()
      */
-    public function sign(string $data, string $key, bool $rawHash = false): string
-    {
+    public function sign(
+        string $data,
+        #[SensitiveParameter]
+        string $key,
+        bool $rawHash = false
+    ): string {
         $hash = hash_hmac($this->algorithm, $data, $key, $rawHash);
         if (!$hash) {
             throw new \RuntimeException("Failed to generate HMAC with hash algorithm: {$this->algorithm}.");
@@ -80,8 +85,12 @@ public function sign(string $data, string $key, bool $rawHash = false): string
      *
      * @see hash()
      */
-    public function getMessage(string $data, string $key, bool $rawHash = false): string
-    {
+    public function getMessage(
+        string $data,
+        #[SensitiveParameter]
+        string $key,
+        bool $rawHash = false
+    ): string {
         $test = hash_hmac($this->algorithm, '', '', $rawHash);
         if (!$test) {
             throw new \RuntimeException("Failed to generate HMAC with hash algorithm: {$this->algorithm}.");

src/PasswordHasher.php

@@ -4,6 +4,8 @@
 
 namespace Yiisoft\Security;
 
+use SensitiveParameter;
+
 /**
  * PasswordHasher allows generating password hash and verifying passwords against a hash.
  */
@@ -65,8 +67,10 @@ public function __construct(?string $algorithm = PASSWORD_DEFAULT, array $parame
      * @psalm-suppress InvalidNullableReturnType
      * @psalm-suppress NullableReturnStatement
      */
-    public function hash(string $password): string
-    {
+    public function hash(
+        #[SensitiveParameter]
+        string $password
+    ): string {
         return password_hash($password, $this->algorithm, $this->parameters);
     }
 
@@ -83,8 +87,12 @@ public function hash(string $password): string
      *
      * @see hash()
      */
-    public function validate(string $password, string $hash): bool
-    {
+    public function validate(
+        #[SensitiveParameter]
+        string $password,
+        #[SensitiveParameter]
+        string $hash
+    ): bool {
         if ($password === '') {
             throw new \InvalidArgumentException('Password must be a string and cannot be empty.');
         }

src/TokenMask.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Security;
 
+use SensitiveParameter;
 use Yiisoft\Strings\StringHelper;
 
 /**
@@ -22,12 +23,14 @@
      *
      * @return string A masked token.
      */
-    public static function apply(string $token): string
-    {
+    public static function apply(
+        #[SensitiveParameter]
+        string $token
+    ): string {
         // The number of bytes in a mask is always equal to the number of bytes in a token.
         /** @psalm-suppress ArgumentTypeCoercion */
         $mask = random_bytes(StringHelper::byteLength($token));
         return StringHelper::base64UrlEncode($mask . ($mask ^ $token));
     }
 
     /**
@@ -37,8 +40,10 @@
      *
      * @return string An unmasked token, or an empty string in case of token format is invalid.
      */
-    public static function remove(string $maskedToken): string
-    {
+    public static function remove(
+        #[SensitiveParameter]
+        string $maskedToken
+    ): string {
         $decoded = StringHelper::base64UrlDecode($maskedToken);
         $length = StringHelper::byteLength($decoded) / 2;
         // Check if the masked token has an even length.