Merge pull request #191 from paragonie/sensitive-parameter

Use SensitiveParameter

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
           coverage: none
 
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v2"
+        uses: "ramsey/composer-install@v3"
 
       - name: PHPUnit tests
         run: vendor/bin/phpunit

.github/workflows/psalm.yml

@@ -26,7 +26,7 @@ jobs:
           coverage: none
 
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v2"
+        uses: "ramsey/composer-install@v3"
         with:
           composer-options: --no-dev
 

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Version 5.1.2 (2024-05-08)
+
+* Use `#[SensitiveParameter]` annotation on some inputs
+  * This is defense in depth; we already wrapped most in `HiddenString`
+* Updated dependencies
+
 ## Version 5.1.1 (2024-04-19)
 
 * Support both sodium_compat v1 and v2. 

psalm.xml

@@ -11,6 +11,7 @@
         <RedundantCondition errorLevel="suppress" />
         <RedundantConditionGivenDocblockType errorLevel="suppress" />
 
+        <TypeDoesNotContainType errorLevel="info" />
         <ArgumentTypeCoercion errorLevel="info" />
         <RedundantCast errorLevel="info" />
         <NonInvariantDocblockPropertyType errorLevel="info" />

src/Asymmetric/Crypto.php

@@ -84,7 +84,9 @@ final private function __construct()
      * @throws TypeError
      */
     public static function encrypt(
+        #[\SensitiveParameter]
         HiddenString $plaintext,
+        #[\SensitiveParameter]
         EncryptionSecretKey $ourPrivateKey,
         EncryptionPublicKey $theirPublicKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
@@ -118,9 +120,12 @@ public static function encrypt(
      * @throws TypeError
      */
     public static function encryptWithAD(
+        #[\SensitiveParameter]
         HiddenString $plaintext,
+        #[\SensitiveParameter]
         EncryptionSecretKey $ourPrivateKey,
         EncryptionPublicKey $theirPublicKey,
+        #[\SensitiveParameter]
         string $additionalData = '',
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
     ): string {
@@ -163,6 +168,7 @@ public static function encryptWithAD(
      */
     public static function decrypt(
         string $ciphertext,
+        #[\SensitiveParameter]
         EncryptionSecretKey $ourPrivateKey,
         EncryptionPublicKey $theirPublicKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
@@ -198,8 +204,10 @@ public static function decrypt(
      */
     public static function decryptWithAD(
         string $ciphertext,
+        #[\SensitiveParameter]
         EncryptionSecretKey $ourPrivateKey,
         EncryptionPublicKey $theirPublicKey,
+        #[\SensitiveParameter]
         string $additionalData = '',
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
     ): HiddenString {
@@ -241,6 +249,7 @@ public static function decryptWithAD(
      * @throws TypeError
      */
     public static function getSharedSecret(
+        #[\SensitiveParameter]
         EncryptionSecretKey $privateKey,
         EncryptionPublicKey $publicKey,
         bool $get_as_object = false,
@@ -291,6 +300,7 @@ public static function getSharedSecret(
      * @throws TypeError
      */
     public static function seal(
+        #[\SensitiveParameter]
         HiddenString $plaintext,
         EncryptionPublicKey $publicKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
@@ -321,6 +331,7 @@ public static function seal(
      */
     public static function sign(
         string $message,
+        #[\SensitiveParameter]
         SignatureSecretKey $privateKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
     ): string {
@@ -355,6 +366,7 @@ public static function sign(
      */
     public static function signAndEncrypt(
         HiddenString $message,
+        #[\SensitiveParameter]
         SignatureSecretKey $secretKey,
         PublicKey $recipientPublicKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
@@ -393,6 +405,7 @@ public static function signAndEncrypt(
      */
     public static function unseal(
         string $ciphertext,
+        #[\SensitiveParameter]
         EncryptionSecretKey $privateKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
     ): HiddenString {
@@ -505,6 +518,7 @@ public static function verify(
     public static function verifyAndDecrypt(
         string $ciphertext,
         SignaturePublicKey $senderPublicKey,
+        #[\SensitiveParameter]
         SecretKey $givenSecretKey,
         string|bool $encoding = Halite::ENCODE_BASE64URLSAFE
     ): HiddenString {

src/Asymmetric/EncryptionSecretKey.php

@@ -28,8 +28,11 @@ final class EncryptionSecretKey extends SecretKey
      * @throws InvalidKey
      * @throws TypeError
      */
-    public function __construct(HiddenString $keyMaterial, ?HiddenString $pk = null)
-    {
+    public function __construct(
+        #[\SensitiveParameter]
+        HiddenString $keyMaterial,
+        ?HiddenString $pk = null
+    ) {
         if (Binary::safeStrlen($keyMaterial->getString()) !== SODIUM_CRYPTO_BOX_SECRETKEYBYTES) {
             throw new InvalidKey(
                 sprintf(

src/Asymmetric/SecretKey.php

@@ -24,8 +24,11 @@ class SecretKey extends Key
      *
      * @throws TypeError
      */
-    public function __construct(HiddenString $keyMaterial, ?HiddenString $pk = null)
-    {
+    public function __construct(
+        #[\SensitiveParameter]
+        HiddenString $keyMaterial,
+        ?HiddenString $pk = null
+    ) {
         parent::__construct($keyMaterial);
         if (!is_null($pk)) {
             $this->cachedPublicKey = $pk->getString();

src/Asymmetric/SignatureSecretKey.php

@@ -33,8 +33,11 @@ final class SignatureSecretKey extends SecretKey
      * @throws InvalidKey
      * @throws TypeError
      */
-    public function __construct(HiddenString $keyMaterial, ?HiddenString $pk = null)
-    {
+    public function __construct(
+        #[\SensitiveParameter]
+        HiddenString $keyMaterial,
+        ?HiddenString $pk = null
+    ) {
         if (Binary::safeStrlen($keyMaterial->getString()) !== SODIUM_CRYPTO_SIGN_SECRETKEYBYTES) {
             throw new InvalidKey(
                 sprintf(

src/Cookie.php

@@ -86,8 +86,10 @@ public function __debugInfo()
      * @throws SodiumException
      * @throws TypeError
      */
-    public function fetch(string $name)
-    {
+    public function fetch(
+        #[\SensitiveParameter]
+        string $name
+    ) {
         if (!isset($_COOKIE[$name])) {
             return null;
         }
@@ -165,7 +167,9 @@ protected static function getConfig(string $stored): SymmetricConfig
      * @psalm-suppress MixedArgument
      */
     public function store(
+        #[\SensitiveParameter]
         string $name,
+        #[\SensitiveParameter]
         $value,
         int $expire = 0,
         string $path = '/',

src/EncryptionKeyPair.php

@@ -131,8 +131,10 @@ public function __construct(Key ...$keys)
      * @throws InvalidKey
      * @throws \TypeError
      */
-    protected function setupKeyPair(EncryptionSecretKey $secret): void
-    {
+    protected function setupKeyPair(
+        #[\SensitiveParameter]
+        EncryptionSecretKey $secret
+    ): void {
         $this->secretKey = $secret;
         $this->publicKey = $this->secretKey->derivePublicKey();
     }

src/Password.php

@@ -64,9 +64,12 @@ final class Password
      * @throws TypeError
      */
     public static function hash(
+        #[\SensitiveParameter]
         HiddenString $password,
+        #[\SensitiveParameter]
         EncryptionKey $secretKey,
         string $level = KeyFactory::INTERACTIVE,
+        #[\SensitiveParameter]
         string $additionalData = ''
     ): string {
         $kdfLimits = KeyFactory::getSecurityLevels($level);
@@ -105,9 +108,12 @@ public static function hash(
      * @throws TypeError
      */
     public static function needsRehash(
+        #[\SensitiveParameter]
         string $stored,
+        #[\SensitiveParameter]
         EncryptionKey $secretKey,
         string $level = KeyFactory::INTERACTIVE,
+        #[\SensitiveParameter]
         string $additionalData = ''
     ): bool {
         $config = self::getConfig($stored);
@@ -203,9 +209,13 @@ protected static function getConfig(string $stored): SymmetricConfig
      * @throws TypeError
      */
     public static function verify(
+        #[\SensitiveParameter]
         HiddenString $password,
+        #[\SensitiveParameter]
         string $stored,
+        #[\SensitiveParameter]
         EncryptionKey $secretKey,
+        #[\SensitiveParameter]
         string $additionalData = ''
     ): bool {
         $config = self::getConfig($stored);

src/SignatureKeyPair.php

@@ -157,8 +157,10 @@ public function getEncryptionKeyPair(): EncryptionKeyPair
      * @throws InvalidKey
      * @throws SodiumException
      */
-    protected function setupKeyPair(SignatureSecretKey $secret): void
-    {
+    protected function setupKeyPair(
+        #[\SensitiveParameter]
+        SignatureSecretKey $secret
+    ): void {
         $this->secretKey = $secret;
         $this->publicKey = $this->secretKey->derivePublicKey();
     }

src/Symmetric/AuthenticationKey.php

@@ -27,8 +27,10 @@ final class AuthenticationKey extends SecretKey
      * @throws InvalidKey
      * @throws TypeError
      */
-    public function __construct(HiddenString $keyMaterial)
-    {
+    public function __construct(
+        #[\SensitiveParameter]
+        HiddenString $keyMaterial
+    ) {
         if (Binary::safeStrlen($keyMaterial->getString()) !== SODIUM_CRYPTO_AUTH_KEYBYTES) {
             throw new InvalidKey(
                 sprintf(

src/Symmetric/EncryptionKey.php

@@ -25,8 +25,10 @@ final class EncryptionKey extends SecretKey
      * @throws InvalidKey
      * @throws TypeError
      */
-    public function __construct(HiddenString $keyMaterial)
-    {
+    public function __construct(
+        #[\SensitiveParameter]
+        HiddenString $keyMaterial
+    ) {
         if (Binary::safeStrlen($keyMaterial->getString()) !== SODIUM_CRYPTO_STREAM_KEYBYTES) {
             throw new InvalidKey(
                 sprintf(