nocworx · adrian-enspired · Feb 19, 2019 · Feb 20, 2019 · Mar 11, 2019 · Mar 11, 2019
diff --git a/.coveralls.yml b/.coveralls.yml
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,11 @@
+* text=auto
+
+/.github        export-ignore
+/doc            export-ignore
+/test          export-ignore
+/.coveralls.yml export-ignore
+/.gitattributes export-ignore
+/.gitignore     export-ignore
+/phpstan*       export-ignore
+/phpunit*       export-ignore
+/psalm*         export-ignore
diff --git a/.github/output/.gitkeep b/.github/output/.gitkeep
diff --git a/.github/output/README.md b/.github/output/README.md
@@ -0,0 +1,3 @@
+# Coverage Output
+
+If you are looking at the `image-data` branch, please know that this is just a hack to get the coverage badge working.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  phpunit:
+    name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
+    runs-on: ${{ matrix.operating-system }}
+    if: "!contains(github.event.head_commit.message, '[ci]')"
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.1', '8.2', '8.3', '8.4']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: mbstring, intl, sodium
+          ini-values: error_reporting=-1, display_errors=On
+          coverage: none
+
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
+
+      - name: PHPUnit tests
+        run: vendor/bin/phpunit
+
+      - name: PHPStan analysis
+        run: vendor/bin/phpstan
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -0,0 +1,56 @@
+name: Coverage
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  coverage:
+    name: PHP ${{ matrix.php-versions }} on ${{ matrix.operating-system }}
+    runs-on: ${{ matrix.operating-system }}
+    if: "!contains(github.event.head_commit.message, '[ci]')"
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.4']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: mbstring, intl, sodium, xdebug
+          ini-values: error_reporting=-1, display_errors=On
+          coverage: xdebug
+
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
+
+      - name: Ensure XML file is being loaded
+        run: cp phpunit.xml.dist phpunit.xml
+
+      - name: PHPUnit tests with coverage
+        run: vendor/bin/phpunit --coverage-clover clover.xml --coverage-html build/coverage-report
+
+      - name: phpunit-coverage-badge
+        uses: timkrase/[email protected]
+        with:
+          coverage_badge_path: .github/output/coverage.svg
+          push_badge: false
+
+      - name: Git push to image-data branch
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_dir: .github/output
+          publish_branch: image-data
+          github_token: ${{ secrets.TOKEN }}
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
diff --git a/.github/workflows/psalm.yml b/.github/workflows/psalm.yml
@@ -0,0 +1,32 @@
+name: Psalm
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  psalm:
+    name: Psalm on PHP ${{ matrix.php-versions }}
+    runs-on: ${{ matrix.operating-system }}
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.1', '8.2', '8.3', '8.4']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          coverage: none
+
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v3"
+
+      - name: Psalm static analysis
+        run: vendor/bin/psalm
diff --git a/.gitignore b/.gitignore
@@ -14,3 +14,5 @@
 /composer.lock
 /composer.phar
 /.idea/
+/.phpunit.result.cache
+/phpstan.neon
diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,111 @@
 # Changelog
 
+## Version 5.1.4 (2025-09-18)
+
+* Add PHPStan analysis, level 5 by @spaze in https://github.com/paragonie/halite/pull/195
+* Replace all `http://` links with the `https://` URL they redirect to by @GrahamCampbell in https://github.com/paragonie/halite/pull/196
+* Use Psalm 6 by @spaze in https://github.com/paragonie/halite/pull/198
+* Remove access modifier `final` from private methods by @junaidbinfarooq in https://github.com/paragonie/halite/pull/204
+* Ignore tests, workflows and .MD docs with "export-ignore" on .gitattr… by @erikn69 in https://github.com/paragonie/halite/pull/205
+* Expand test coverage by @paragonie-security in https://github.com/paragonie/halite/pull/206
+* Fixed the broken test coverage badge (https://github.com/paragonie/halite/pull/207 and https://github.com/paragonie/halite/pull/208)
+
+## Version 5.1.3 (2025-01-23)
+
+* Merged [#184](https://github.com/paragonie/halite/pull/194), which fixes PHP 8.4 deprecations with nullable types.
+
+## 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. 
+  [Learn more here](https://paragonie.com/blog/2024/04/release-sodium-compat-v2-and-future-our-polyfill-libraries).
+
+## Version 5.1.0 (2022-05-23)
+
+* Dropped PHP 8.0 support, increased minimum PHP version to 8.1.
+  * This is due to the significant performance difference between ext/sodium
+    and sodium_compat, and the functions we use in 5.x aren't available until
+    PHP 8.1. See [#178](https://github.com/paragonie/halite/issues/178).
+* The 5.0.x branch will continue to *function* on PHP 8.0 but performance is
+  not guaranteed.
+
+## Version 5.0.0 (2022-01-19)
+
+* Increased minimum PHP version to 8.0.
+* **Security:** Asymmetric encryption now uses HKDF-BLAKE2b to extract a 256-bit uniformly random bit string for the
+  encryption key, rather than using the raw X25519 output directly as an encryption key. This is important because 
+  Elliptic Curve Diffie-Hellman results in a random group element, but that isn't necessarily a uniformly random bit
+  string.
+  * Because Halite v4 and earlier did not perform this step, it's superficially susceptible to
+    [Cheon's attack](https://crypto.stackexchange.com/a/67609). This reduces the effective security
+    from 125 bits (Pollard's rho) to 123 bits, but neither is a practical concern today.
+* **Security:** Halite v5 uses the [PAE](https://github.com/paseto-standard/paseto-spec/blob/master/docs/01-Protocol-Versions/Common.md#pae-definition)
+  strategy from PASETO to prevent canonicalization attacks.
+* **Security:** Halite v5 appends the random salt to HKDF's `info` parameter instead of
+  the `salt` parameter. This allows us to meet the KDF Security Definition (which is
+  stronger than a mere Pseudo-Random Function).
+* Encryption now uses XChaCha20 instead of XSalsa20.
+* The `File` class no longer supports the `resource` type. To migrate code, wrap your 
+  `resource` arguments in a `ReadOnlyFile` or `MutableFile` object.
+* Added `File::asymmetricEncrypt()` and `File::asymmetricDecrypt()`.
+
+## Version 4.8.0 (2021-04-18)
+
+* Merged [#158](https://github.com/paragonie/halite/pull/158), which removes
+  the `final` access modifier from private methods and guarantees PHP 8 support.
+* Migrated tests off of Travis CI, onto Github Actions instead.
+
+## Version 4.7.1 (2020-12-06)
+
+* Allow v2 of `paragonie/hidden-string` to be installed.
+
+## Version 4.7.0 (2020-12-03)
+
+* Merged [#154](https://github.com/paragonie/halite/pull/154), which supports
+  the SameSite cookie arguments on PHP 7.3+.
+* Create a wrapper for `sodium_memzero()` to support sodium_compat.
+* Added support for PHP 8.
+* [#146](https://github.com/paragonie/halite/pull/146),
+  [#155](https://github.com/paragonie/halite/pull/155),
+  [#156](https://github.com/paragonie/halite/pull/156) --
+  Various documentation improvements.
+
+## Version 4.6.0 (2019-09-12)
+
+* Merged [#138](https://github.com/paragonie/halite/pull/138), which adds
+  remote stream support to `ReadOnlyFile`.
+* Merged [#140](https://github.com/paragonie/halite/pull/140), which saves
+  some overhead on hash recalculation.
+* Merged [#136](https://github.com/paragonie/halite/pull/136) and 
+  [#137](https://github.com/paragonie/halite/pull/137), which updated the
+  sodium stub files. These aren't strictly necessary anymore; with the
+  adoption of libsodium in PHP 7.2 and sodium_compat, most IDEs autocomplete
+  correctly. But fixing nits is always appreciated.
+* Update minimum sodium_compat to v1.11.0.
+
+## Version 4.5.4 (2019-06-05)
+
+* Merged [#132](https://github.com/paragonie/halite/pull/132), which ensures
+  all Halite exceptions implement `Throwable`.
+* Merged [#133](https://github.com/paragonie/halite/pull/133), which updates
+  the documentation for the `File` API.
+  Thanks [@elliot-sawyer](https://github.com/elliot-sawyer). 
+* Merged [#134](https://github.com/paragonie/halite/pull/134), which allows
+  `MutableFile` to be used on resources opened in `wb` mode.
+  Thanks [@christiaanbaartse](https://github.com/christiaanbaartse).
+* Other minor documentation improvements.
+
+## Version 4.5.3 (2019-03-11)
+
+* Fixed some minor nuisances with Psalm and PHPUnit.
+* Added reference to Halite-Legacy to the README.
+* Updated docblocks.
+
 ## Version 4.5.2 (2019-02-11)
 
 * Fixed [#116](https://github.com/paragonie/halite/issues/116). If the output file

diff --git a/LICENSE b/LICENSE
@@ -357,7 +357,7 @@ Exhibit A - Source Code Form License Notice
 
   This Source Code Form is subject to the terms of the Mozilla Public
   License, v. 2.0. If a copy of the MPL was not distributed with this
-  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+  file, You can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.
 
 If it is not possible or desirable to put the notice in a particular
 file, then You may include the notice in a location (such as a LICENSE

diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
 # Halite
 
-[![Build Status](https://travis-ci.org/paragonie/halite.svg?branch=master)](https://travis-ci.org/paragonie/halite)
+[![Build Status](https://github.com/paragonie/halite/actions/workflows/ci.yml/badge.svg)](https://github.com/paragonie/halite/actions)
+[![Static Analysis](https://github.com/paragonie/halite/actions/workflows/psalm.yml/badge.svg)](https://github.com/paragonie/halite/actions)
 [![Latest Stable Version](https://poser.pugx.org/paragonie/halite/v/stable)](https://packagist.org/packages/paragonie/halite)
 [![Latest Unstable Version](https://poser.pugx.org/paragonie/halite/v/unstable)](https://packagist.org/packages/paragonie/halite)
 [![License](https://poser.pugx.org/paragonie/halite/license)](https://packagist.org/packages/paragonie/halite)
 [![Downloads](https://img.shields.io/packagist/dt/paragonie/halite.svg)](https://packagist.org/packages/paragonie/halite)
-[![Coverage Status](https://coveralls.io/repos/github/paragonie/halite/badge.svg?branch=master)](https://coveralls.io/github/paragonie/halite?branch=master)
+[![Coverage Status](https://raw.githubusercontent.com/paragonie/halite/refs/heads/image-data/coverage.svg)](https://github.com/paragonie/halite/actions/workflows/coverage.yml)
 
 **Halite** is a high-level cryptography interface that relies on [libsodium](https://pecl.php.net/package/libsodium)
 for all of its underlying cryptography operations.
@@ -34,15 +35,19 @@ Before you can use Halite, you must choose a version that fits the requirements
 of your project. The differences between the requirements for the available 
 versions of Halite are briefly highlighted below.
 
-|                                                             | PHP   | libsodium | PECL libsodium | Support                   |
-|-------------------------------------------------------------|-------|-----------|----------------|---------------------------|
-| Halite 4.1 and newer                                        | 7.2.0 | 1.0.15    | N/A (standard) | :heavy_check_mark: Active |
-| [Halite 4.0](https://github.com/paragonie/halite/tree/v4.0) | 7.2.0 | 1.0.13    | N/A (standard) | :heavy_check_mark: Active |
-| [Halite 3](https://github.com/paragonie/halite/tree/v3.x)   | 7.0.0 | 1.0.9     | 1.0.6 / 2.0.4  | :x: Not Supported         |
-| [Halite 2](https://github.com/paragonie/halite/tree/v2.2)   | 7.0.0 | 1.0.9     | 1.0.6          | :x: Not Supported         |
-| [Halite 1](https://github.com/paragonie/halite/tree/v1.x)   | 5.6.0 | 1.0.6     | 1.0.2          | :x: Not Supported         |
+|                                                              | PHP   | libsodium | PECL libsodium | Support                   |
+|--------------------------------------------------------------|-------|-----------|----------------|---------------------------|
+| Halite 5.1 and newer                                         | 8.1.0 | 1.0.18    | N/A (standard) | :heavy_check_mark: Active |
+| Halite 5.0.x                                                 | 8.0.0 | 1.0.18    | N/A (standard) | :heavy_check_mark: Active |
+| [Halite 4.1+](https://github.com/paragonie/halite/tree/v4.x) | 7.2.0 | 1.0.15    | N/A (standard) | :x: Not Supported         |
+| [Halite 4.0](https://github.com/paragonie/halite/tree/v4.0)  | 7.2.0 | 1.0.13    | N/A (standard) | :x: Not Supported         |
+| [Halite 3](https://github.com/paragonie/halite/tree/v3.x)    | 7.0.0 | 1.0.9     | 1.0.6 / 2.0.4  | :x: Not Supported         |
+| [Halite 2](https://github.com/paragonie/halite/tree/v2.2)    | 7.0.0 | 1.0.9     | 1.0.6          | :x: Not Supported         |
+| [Halite 1](https://github.com/paragonie/halite/tree/v1.x)    | 5.6.0 | 1.0.6     | 1.0.2          | :x: Not Supported         |
 
-If you need a version of Halite before 4.0, see the documentation relevant to that
+Note: Halite 5.0.x works on PHP 8.0, but performance is worse than on PHP 8.1.
+
+If you need a version of Halite before 5.1, see the documentation relevant to that
 particular branch.
 
 **To install Halite, you first need to [install libsodium](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium).**
@@ -56,31 +61,37 @@ If you're stuck, [this step-by-step guide contributed by @aolko](doc/Install-Gui
 
 Once you have the prerequisites installed, install Halite through [Composer](https://getcomposer.org/doc/00-intro.md):
 
-    composer require paragonie/halite:^4
+    composer require paragonie/halite:^5
 
 ### Commercial Support for Older Halite Versions
 
-Free (gratis) support for Halite only extends to the most recent major version (currently 4).
+Free (gratis) support for Halite only extends to the most recent major version (currently 5).
 
 If your company requires support for an older version of Halite,
 [contact Paragon Initiative Enterprises](https://paragonie.com/contact) to inquire about
 commercial support options.
 
+If you need an easy way to migrate from older versions of Halite, check out [halite-legacy](https://github.com/paragonie/halite-legacy).
+
 ## Using Halite in Your Project
 
 Check out the [documentation](doc). The basic Halite API is designed for simplicity:
 
   * Encryption
     * Symmetric
        * `Symmetric\Crypto::encrypt`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md)): `string`
+       * `Symmetric\Crypto::encryptWithAD`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md), `string`): `string`
        * `Symmetric\Crypto::decrypt`(`string`, [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
+       * `Symmetric\Crypto::decryptWithAD`(`string`, [`EncryptionKey`](doc/Classes/Symmetric/EncryptionKey.md), `string`): [`HiddenString`](doc/Classes/HiddenString.md)
     * Asymmetric
        * Anonymous
          * `Asymmetric\Crypto::seal`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): `string`
          * `Asymmetric\Crypto::unseal`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
        * Authenticated
          * `Asymmetric\Crypto::encrypt`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): `string`
+         * `Asymmetric\Crypto::encryptWithAD`([`HiddenString`](doc/Classes/HiddenString.md), [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md), `string`): `string`
          * `Asymmetric\Crypto::decrypt`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md)): [`HiddenString`](doc/Classes/HiddenString.md)
+         * `Asymmetric\Crypto::decryptWithAD`(`string`, [`EncryptionSecretKey`](doc/Classes/Asymmetric/EncryptionSecretKey.md), [`EncryptionPublicKey`](doc/Classes/Asymmetric/EncryptionPublicKey.md), `string`): [`HiddenString`](doc/Classes/HiddenString.md)
   * Authentication
     * Symmetric
        * `Symmetric\Crypto::authenticate`(`string`, [`AuthenticationKey`](doc/Classes/Symmetric/AuthenticationKey.md)): `string`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Coverage Output

		If you are looking at the `image-data` branch, please know that this is just a hack to get the coverage badge working.