Update documentation and changelog.

CHANGELOG.md

@@ -1,9 +1,15 @@
 # Changelog
 
-## Version 4.0.0 (Not released)
-
-* Bump minimum PHP version to 7.2.0.
-* 
+## Version 4.0.0 (2017-09-16)
+
+* Bump minimum PHP version to **7.2.0**, which will be available before the end of 2017
+* New methods: `encryptWithAd()` and `decryptWithAd()`, for satisfying true AEAD needs
+* Encrypted password hashing through our `Password` class can also accept an optional, 
+  additional data parameter
+* `HiddenString` objects 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
 
 ## Version 3.2.0 (2016-12-08)
 

doc/Classes/Asymmetric/Crypto.md

@@ -13,7 +13,7 @@ using X25519 (Elliptic Curve Diffie Hellman key agreement over Curve25519).
 
 ### `encrypt()`
 
-> `public` encrypt(`HiddenString $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `boolean $raw = false`) : `string`
+> `public` encrypt(`HiddenString $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `string`
 
 This method will:
 
@@ -29,7 +29,7 @@ This method will:
 
 ### `decrypt()`
 
-> `public` decrypt(`string $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `boolean $raw = false`) : `HiddenString`
+> `public` decrypt(`string $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `HiddenString`
 
 This method will:
 
@@ -44,9 +44,21 @@ This method will:
    key (step 4).
 7. Return what should be the original plaintext.
 
+### `encryptWithAd()`
+
+> `public` encryptWithAd(`HiddenString $plaintext`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `string $additionalData = ''`, `$encoding = Halite::ENCODE_BASE64URLSAFE`): `string`
+
+This is similar to `encrypt()`, except the `$additionalData` string is prepended to the ciphertext (after the nonce) when calculating the Message Authentication Code (MAC).
+
+### `decryptWithAd()`
+
+> `public` decryptWithAd(`string $ciphertext`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$ourPrivateKey`, [`EncryptionPublicKey`](EncryptionPublicKey.md) `$theirPublicKey`, `string $additionalData = ''`, `$encoding = Halite::ENCODE_BASE64URLSAFE`): `HiddenString`
+
+This is similar to `decrypt()`, except the `$additionalData` string is prepended to the ciphertext (after the nonce) when calculating the Message Authentication Code (MAC).
+
 ### `seal()`
 
-> `public` seal(`HiddenString $source`,  [`EncryptionPublicKey`](EncryptionPublicKey.md) `$publicKey`, `boolean $raw = false`) : `string`
+> `public` seal(`HiddenString $source`,  [`EncryptionPublicKey`](EncryptionPublicKey.md) `$publicKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `string`
 
 Anonymous public-key encryption. Encrypt a message with your recipient's public
 key and they can use their secret key to decrypt it.
@@ -55,20 +67,20 @@ The actual underlying protocol is [`sodium_crypto_box_seal()`](https://paragonie
 
 ### `unseal()`
 
-> `public` unseal(`string $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$secretKey`, `boolean $raw = false`) : `HiddenString`
+> `public` unseal(`string $source`, [`EncryptionSecretKey`](EncryptionSecretKey.md) `$secretKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `HiddenString`
 
 Anonymous public-key decryption. Decrypt a sealed message with your secret key.
 
 The actual underlying protocol is [`sodium_crypto_box_seal_open()`](https://paragonie.com/book/pecl-libsodium/read/08-advanced.md#crypto-box-seal).
 
 ### `sign()`
 
-> `public` sign(`string $message`, [`SignatureSecretKey`](SignatureSecretKey.md) `$secretKey`, `boolean $raw = false`) : `string`
+> `public` sign(`string $message`, [`SignatureSecretKey`](SignatureSecretKey.md) `$secretKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `string`
 
 Calculates a digital signature of `$message`, using [`sodium_crypto_sign()`](https://paragonie.com/book/pecl-libsodium/read/05-publickey-crypto.md#crypto-sign).
 
 ### `verify()`
 
-> `public` verify(`string $message`, [`SignaturePublicKey`](SignaturePublicKey.md) `$secretKey`, `string $signature`, `boolean $raw = false`) : `boolean`
+> `public` verify(`string $message`, [`SignaturePublicKey`](SignaturePublicKey.md) `$secretKey`, `string $signature`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `boolean`
 
 Does the signature match the contents of the message, for the given public key?

doc/Classes/Symmetric/Crypto.md

@@ -6,13 +6,13 @@
 
 ### `authenticate()`
 
-> `public` authenticate(`string $message`, [`AuthenticationKey`](AuthenticationKey.md) `$secretKey`, `boolean $raw = false`) : `string`
+> `public` authenticate(`string $message`, [`AuthenticationKey`](AuthenticationKey.md) `$secretKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `string`
 
 Calculate a MAC for a given message, using a secret authentication key.
 
 ### `encrypt()`
 
-> `public` encrypt(`HiddenString $plaintext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `boolean $raw = false`) : `string`
+> `public` encrypt(`HiddenString $plaintext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`): `string`
 
 Encrypt-then-authenticate a message. This method will:
 
@@ -27,7 +27,7 @@ Encrypt-then-authenticate a message. This method will:
 
 ### `decrypt()`
 
-> `public` decrypt(`string $ciphertext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `boolean $raw = false`) : `HiddenString`
+> `public` decrypt(`string $ciphertext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `HiddenString`
 
 Verify-then-decrypt a message. This method will:
 
@@ -41,8 +41,20 @@ Verify-then-decrypt a message. This method will:
    key (step 3).
 6. Return what should be the original plaintext.
 
+### `encryptWithAd()`
+
+> `public` encryptWithAd(`HiddenString $plaintext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `string $additionalData = ''`, `$encoding = Halite::ENCODE_BASE64URLSAFE`): `string`
+
+This is similar to `encrypt()`, except the `$additionalData` string is prepended to the ciphertext (after the nonce) when calculating the Message Authentication Code (MAC).
+
+### `decryptWithAd()`
+
+> `public` decryptWithAd(`string $ciphertext`, [`EncryptionKey`](EncryptionKey.md) `$secretKey`, `string $additionalData = ''`, `$encoding = Halite::ENCODE_BASE64URLSAFE`): `HiddenString`
+
+This is similar to `decrypt()`, except the `$additionalData` string is prepended to the ciphertext (after the nonce) when calculating the Message Authentication Code (MAC).
+
 ### `verify()`
 
-> `public` verify(`string $message`, [`AuthenticationKey`](AuthenticationKey.md) `$secretKey`, `string $mac` `boolean $raw = false`) : `boolean`
+> `public` verify(`string $message`, [`AuthenticationKey`](AuthenticationKey.md) `$secretKey`, `string $mac`, `$encoding = Halite::ENCODE_BASE64URLSAFE`) : `boolean`
 
 Verify the MAC for a given message and secret authentication key.