diff --git a/CHANGELOG.md b/CHANGELOG.md index 1976669..304b94d 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/doc/Classes/Asymmetric/Crypto.md b/doc/Classes/Asymmetric/Crypto.md index e3afc7c..d320028 100644 --- a/doc/Classes/Asymmetric/Crypto.md +++ b/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,7 +67,7 @@ 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. @@ -63,12 +75,12 @@ The actual underlying protocol is [`sodium_crypto_box_seal_open()`](https://para ### `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? diff --git a/doc/Classes/Symmetric/Crypto.md b/doc/Classes/Symmetric/Crypto.md index 61f7419..9b7d560 100644 --- a/doc/Classes/Symmetric/Crypto.md +++ b/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. \ No newline at end of file