The purpose of this class is to encapsulate strings and hide their contents
from stack traces should an unhandled exception occur in a program that uses
Halite.
The only things that should be protected:
- Passwords
- Plaintext (before encryption)
- Plaintext (after decryption)
This library makes heavy use of return-type declarations,
which are a PHP 7 only feature. Read more about them here:
/**
* @param HiddenString $keyMaterial - The actual key data
* @throws InvalidKey
*/
public function __construct(HiddenString $keyMaterial)
{
if (CryptoUtil::safeStrlen($keyMaterial->getString()) !== \Sodium\CRYPTO_BOX_SECRETKEYBYTES) {
throw new InvalidKey('Encryption secret key must be CRYPTO_BOX_SECRETKEYBYTES bytes long');
}
parent::__construct($keyMaterial);
}
/**
* @param HiddenString $keyMaterial - The actual key data
* @throws InvalidKey
*/
public function __construct(HiddenString $keyMaterial)
{
if (CryptoUtil::safeStrlen($keyMaterial->getString()) !== \Sodium\CRYPTO_AUTH_KEYBYTES) {
throw new InvalidKey('Authentication key must be CRYPTO_AUTH_KEYBYTES bytes long');
}
parent::__construct($keyMaterial);
$this->isSigningKey = true;
}
/**
* @param HiddenString $keyMaterial - The actual key data
* @throws InvalidKey
*/
public function __construct(HiddenString $keyMaterial)
{
if (CryptoUtil::safeStrlen($keyMaterial->getString()) !== \Sodium\CRYPTO_SIGN_SECRETKEYBYTES) {
throw new InvalidKey('Signature secret key must be CRYPTO_SIGN_SECRETKEYBYTES bytes long');
}
parent::__construct($keyMaterial);
$this->isSigningKey = true;
}
/**
* @covers Asymmetric::seal()
* @covers Asymmetric::unseal()
*/
public function testSeal()
{
if (\Sodium\library_version_major() < 7 || \Sodium\library_version_major() == 7 && \Sodium\library_version_minor() < 5) {
$this->markTestSkipped("Your version of libsodium is too old");
}
$alice = KeyFactory::generateEncryptionKeyPair();
$enc_secret = $alice->getSecretKey();
$enc_public = $alice->getPublicKey();
$this->assertSame(\Sodium\crypto_box_publickey_from_secretkey($enc_secret->getRawKeyMaterial()), $enc_public->getRawKeyMaterial());
$message = new HiddenString('This is for your eyes only');
$kp = \Sodium\crypto_box_keypair();
$test = \Sodium\crypto_box_seal($message->getString(), \Sodium\crypto_box_publickey($kp));
$decr = \Sodium\crypto_box_seal_open($test, $kp);
$this->assertTrue($decr !== false);
$sealed = Asymmetric::seal($message, new EncryptionPublicKey(new HiddenString(\Sodium\crypto_box_publickey($kp))));
$opened = Asymmetric::unseal($sealed, new EncryptionSecretKey(new HiddenString(\Sodium\crypto_box_secretkey($kp))));
$this->assertSame($opened->getString(), $message->getString());
$sealed = Asymmetric::seal($message, $enc_public);
$opened = Asymmetric::unseal($sealed, $enc_secret);
$this->assertSame($opened->getString(), $message->getString());
$sealed_raw = Asymmetric::seal($message, $alice->getPublicKey());
$opened_raw = Asymmetric::unseal($sealed_raw, $alice->getSecretKey());
$this->assertSame($opened_raw->getString(), $message->getString());
}
/**
* Decrypt then verify a password
*
* @param HiddenString $password The user's password
* @param string $stored The encrypted password hash
* @param EncryptionKey $secretKey The master key for all passwords
* @return bool Is this password valid?
* @throws InvalidMessage
*/
public static function verify(HiddenString $password, string $stored, EncryptionKey $secretKey) : bool
{
$config = self::getConfig($stored);
// Base64-urlsafe encoded, so 4/3 the size of raw binary
if (Util::safeStrlen($stored) < $config->SHORTEST_CIPHERTEXT_LENGTH * 4 / 3) {
throw new InvalidMessage('Encrypted password hash is too short.');
}
// First let's decrypt the hash
$hash_str = Crypto::decrypt($stored, $secretKey, $config->ENCODING);
// Upon successful decryption, verify the password is correct
return \Sodium\crypto_pwhash_str_verify($hash_str->getString(), $password->getString());
}
/**
* Load an asymmetric signature key pair from a string
*
* @param HiddenString $keyData
* @return SignatureKeyPair
*
* @throws Alerts\CannotPerformOperation
*/
public static function importSignatureKeyPair(HiddenString $keyData) : SignatureKeyPair
{
return new SignatureKeyPair(new SignatureSecretKey(new HiddenString(self::getKeyDataFromString(\Sodium\hex2bin($keyData->getString())))));
}