- Use
#[SensitiveParameter]annotation on some inputs- This is defense in depth; we already wrapped most in
HiddenString
- This is defense in depth; we already wrapped most in
- Updated dependencies
- Support both sodium_compat v1 and v2. Learn more here.
- 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.
- The 5.0.x branch will continue to function on PHP 8.0 but performance is not guaranteed.
- 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. 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 strategy from PASETO to prevent canonicalization attacks.
- Security: Halite v5 appends the random salt to HKDF's
infoparameter instead of thesaltparameter. 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
Fileclass no longer supports theresourcetype. To migrate code, wrap yourresourcearguments in aReadOnlyFileorMutableFileobject. - Added
File::asymmetricEncrypt()andFile::asymmetricDecrypt().
- Merged #158, which removes
the
finalaccess modifier from private methods and guarantees PHP 8 support. - Migrated tests off of Travis CI, onto Github Actions instead.
- Allow v2 of
paragonie/hidden-stringto be installed.
- Merged #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, #155, #156 -- Various documentation improvements.
- Merged #138, which adds
remote stream support to
ReadOnlyFile. - Merged #140, which saves some overhead on hash recalculation.
- Merged #136 and #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.
- Merged #132, which ensures
all Halite exceptions implement
Throwable. - Merged #133, which updates
the documentation for the
FileAPI. Thanks @elliot-sawyer. - Merged #134, which allows
MutableFileto be used on resources opened inwbmode. Thanks @christiaanbaartse. - Other minor documentation improvements.
- Fixed some minor nuisances with Psalm and PHPUnit.
- Added reference to Halite-Legacy to the README.
- Updated docblocks.
- Fixed #116. If the output file doesn't exist, it will be created. If it cannot be created, an exception will still be thrown.
- Use
class_alias()forParagonIE\Halite\HiddenStringto the outsourced library. This is deprecated and will be removed in version 5.
- Updated Psalm version from
^0|^1to^1|^2. - Moved
HiddenStringto a standalone library: https://travis-ci.org/paragonie/hidden-string
- Updated Psalm version from
^0|^1to^1. - Type-safety and documentation fixes.
- Miscellaneous boyscouting. No bugs were found since 4.4.1.
- Fixed #97, set the minimum chunk size to 1.
- Fixed #90:
- Introduced
WeakReadOnlyFile, an alternative toReadOnlyFilethat allows file modes other thanrb. The TOCTOU security guarantees are therefore slightly weaker with this class (hence the "Weak" part of the name). - Updated
Fileto allow stream objects (ReadOnlyFileandMutableFile) to be passed direclty instead of strings (for filenames) and resources (for open file handles).
- Introduced
- Updated the
Halite::VERSIONconstant which was previously still4.2.0. - Documentation and unit testing improvements.
- You can now quickly turn a
SignatureKeyPairobject into a birationally equivalent EncryptionKeyPair object by invoking thegetEncryptionKeyPair()method. - We now have 100% unit test coverage, in addition to our static analysis.
- Implemented
Asymmetric::signAndEncrypt()andAsymmetric::verifyAndDecrypt(), which facilitates the GPG use-case of signed-then-encrypted messages between two parties' Ed25519 keypairs. Encryption is facilitated using birationally equivalent X25519 keys. - Removed our in-house implementations of binary-safe
substrandstrlenin favor of using the ones in the constant-time encoding library.
Added support for libsodium 1.0.15, which was previously broken in 4.0.x.
Passwords should be autoamtically migrated, but if keys were being generated via
KeyFactory::derive______Key() (fill in the blank), you'll need to change your
usage of this API to get the same key as previously. Namely, you'll need to pass
the SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13 constant to the fourth argument after the
password, salt, and security level.
$key = KeyFactory::deriveEncryptionKey(
new HiddenString('correct horse barry staple'),
- "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f"
+ "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f",
+ KeyFactory::INTERACTIVE,
+ SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13
);If you previously specified a security level, your diff might look like this:
$key = KeyFactory::deriveEncryptionKey(
new HiddenString('correct horse barry staple'),
"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f",
- KeyFactory::SENSITIVE
+ KeyFactory::SENSITIVE,
+ SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13
);This is mostly a boyscouting/documentation release. However, we now pass Psalm under the
strictest setting (totallyTyped = true). This means that not only is our public interface
totally type-safe, but Halite's internals are as well.
- Prompted by #67, Halite is now available under the terms of the Mozilla Public License 2.0 (MPL-2.0). Using Halite to build products that restrict user freedom (such as DRM) is highly discouraged, but not forbidden.
- Bump minimum PHP version to 7.2.0, which will be available before the end of 2017
- New methods:
encryptWithAd()anddecryptWithAd(), for satisfying true AEAD needs - Encrypted password hashing through our
Passwordclass can also accept an optional, additional data parameter HiddenStringobjects can now be directly compared$hiddenString->equals($otherHiddenString)
- Added Psalm to our Continuous Integration to assure Halite is fully type-safe
- Updated unit tests to be compatible with PHPUnit 6
- Resolved #49, which
requested making
HiddenStringdefend againstserialize()leaks. - Fixed an encoding issue which broke legacy passwords. (Discovered in the course of CMS Airship development.)
- The
FileAPI now supports different encodings for signatures and checksums (more than just hex and binary).
- Fixed #44, which caused Halite to be unusable for Symfony users. Thanks, Usman Zafar.
- Added an
export()method toKeyFactory, and congruentimport*()methods. For example:export($key)returns aHiddenStringwith a versioned and checksummed, hex-encoded string representing the key material.importEncryptionKey($hiddenString)expects anEncryptionKeyobject or throws aTypeError
- Use paragonie/constant_time_encoding
- We now default to URL-safe Base 64 encoding (RFC 4648)
- API change: Plaintext and password inputs must be a
HiddenStringobject. - Dropped support for version 1.
- We no longer offer or use scrypt anywhere. Everything is Argon2 now.
KeyFactoryno longer accepts a$legacyargument.
- Added
TrimmedMerkleTreetoStructures. - Use
is_callable()instead offunction_exists()for better compatibility with Suhosin.
- Better docblocks, added unit test to prevent regressions.
- Prevent an undefined index error when calculating the root of an empty MerkleTree.
- Key derivation (via
KeyFactory) can now accept an extra argument to specify the security level of the derived key.- Scrypt:
INTERACTIVEorSENSITIVE - Argon2i:
INTERACTIVE,MODERATE, orSENSITIVE
- Scrypt:
Passwordcan now accept a security level argument. We recommend sticking withINTERACTIVEfor end users, but if you'd rather make administrative accounts cost more to attack, now you can make that happen within Halite.MerkleTreecan now accept a personalization string for the hash calculation.MerkleTreecan output a specific hash length (between 16 and 64).- Both
MerkleTreeandNodenow lazily calculate the Merkle root rather than calculating it eagerly. This results in less CPU waste. - Cleaned up the legacy cruft in the
Keyclasses. Now they only accept a string in their constructor.
- Fixed conflict with PHP 7 string optimizations that was causing
File::decrypt()to fail in PHP-FPM. - Introduced a new method,
Util::safeStrcpy(), to facilitate safe string duplication without triggering the optimizer.
- Halite now requires:
- PHP 7.0+
- libsodium 1.0.9+
- libsodium-php 1.0.3+
- (You can use
Halite::isLibsodiumSetupCorrectly()to verify the latter two)
- Strictly typed everywhere
- You can no longer pass a well-configured but generic
Keyobject to most methods; you must pass the appropriate child class (i.e.Symmetric\Crypto::encrypt()expects an instance ofSymmetric\Crypto\EncryptionKey. - Updated password hashing and key derivation to use Argon2i
Filenow uses a keyed BLAKE2b hash instead of HMAC-SHA256.Key->get()was renamed toKey->getRawKeyMaterial()Passwordnow has aneedsRehash()method which will returntrueif you're using an obsolete encryption and/or hashing method.Utilnow has several new methods for generating BLAKE2b hashes:hash()keyed_hash()raw_hash()raw_keyed_hash()
- Removed most of the interfaces in
Contract