Edit File: KeyProtectedByPassword.md
Class: Defuse\Crypto\KeyProtectedByPassword ============================================ The `KeyProtectedByPassword` class represents a key that is "locked" with a password. In order to obtain an instance of `Key` that you can use for encrypting and decrypting, a `KeyProtectedByPassword` must first be "unlocked" by providing the correct password. `KeyProtectedByPassword` provides an alternative to using the `encryptWithPassword()`, `decryptWithPassword()`, `encryptFileWithPassword()`, and `decryptFileWithPassword()` methods with several advantages: - The slow and computationally-expensive key stretching is run only once when you unlock a `KeyProtectedByPassword` to obtain the `Key`. - You do not have to keep the original password in memory to encrypt and decrypt things. After you've obtained the `Key` from a `KeyProtectedByPassword`, the password is no longer necessary. Instance Methods ----------------- ### saveToAsciiSafeString() **Description:** Saves the protected key to a string of printable ASCII characters, which can be loaded again into a `KeyProtectedByPassword` instance using `KeyProtectedByPassword::loadFromAsciiSafeString()`. **Parameters:** This method does not take any parameters. **Return value:** Returns a string of printable ASCII characters representing this `KeyProtectedByPassword` instance, which can be loaded back into an instance of `KeyProtectedByPassword` using `KeyProtectedByPassword::loadFromAsciiSafeString()`. **Exceptions:** - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when the platform the code is running on cannot safely perform encryption for some reason (e.g. it lacks a secure random number generator), or the runtime tests detected a bug in this library. **Side-effects and performance:** None. **Cautions:** This method currently returns a hexadecimal string. You should not rely on this behavior. For example, it may be improved in the future to return a base64 string. ### unlockKey($password) **Description:** Unlocks the password-protected key, obtaining a `Key` which can be used for encryption and decryption. **Parameters:** 1. `$password` is the password required to unlock this `KeyProtectedByPassword` to obtain the `Key`. **Return value:** If `$password` is the correct password, then this method returns an instance of the `Key` class. **Exceptions:** - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when the platform the code is running on cannot safely perform encryption for some reason (e.g. it lacks a secure random number generator), or the runtime tests detected a bug in this library. - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if either the given `$password` is not the correct password for this `KeyProtectedByPassword` or the ciphertext stored internally by this object has been modified, i.e. it was accidentally corrupted or intentionally corrupted by an attacker. There is no way for the caller to distinguish between these two cases. **Side-effects and performance:** This method runs a small and very fast set of self-tests if it is the very first time this method or one of the `Crypto` methods has been called. The performance overhead is negligible and can be safely ignored in all applications. **Cautions:** PHP stack traces display (portions of) the arguments passed to methods on the call stack. If an exception is thrown inside this call, and it is uncaught, the value of `$password` may be leaked out to an attacker through the stack trace. We recommend configuring PHP to never output stack traces (either displaying them to the user or saving them to log files). It is impossible in principle to distinguish between the case where you attempt to unlock with the wrong password and the case where you attempt to unlock a modified (corrupted) `KeyProtectedByPassword`. It is up to the caller how to best deal with this ambiguity, as it depends on the application this library is being used in. If in doubt, consult with a professional cryptographer. ### changePassword($current\_password, $new\_password) **Description:** Changes the password, so that calling `unlockKey` on this object in the future will require you to pass `$new\_password` instead of the old password. It is your responsibility to overwrite all stored copies of this `KeyProtectedByPassword`. Any copies you leave lying around can still be decrypted with the old password. **Parameters:** 1. `$current\_password` is the password that this `KeyProtectedByPassword` is currently protected with. 2. `$new\_password` is the new password, which the `KeyProtectedByPassword` will be protected with once this operation completes. **Return value:** If `$current\_password` is the correct password, then this method updates itself to be protected with the new password, and also returns itself. **Exceptions:** - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when the platform the code is running on cannot safely perform encryption for some reason (e.g. it lacks a secure random number generator), or the runtime tests detected a bug in this library. - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if either the given `$current\_password` is not the correct password for this `KeyProtectedByPassword` or the ciphertext stored internally by this object has been modified, i.e. it was accidentally corrupted or intentionally corrupted by an attacker. There is no way for the caller to distinguish between these two cases. **Side-effects and performance:** This method runs a small and very fast set of self-tests if it is the very first time this method or one of the `Crypto` methods has been called. The performance overhead is negligible and can be safely ignored in all applications. **Cautions:** PHP stack traces display (portions of) the arguments passed to methods on the call stack. If an exception is thrown inside this call, and it is uncaught, the value of `$password` may be leaked out to an attacker through the stack trace. We recommend configuring PHP to never output stack traces (either displaying them to the user or saving them to log files). It is impossible in principle to distinguish between the case where you attempt to unlock with the wrong password and the case where you attempt to unlock a modified (corrupted) `KeyProtectedByPassword`. It is up to the caller how to best deal with this ambiguity, as it depends on the application this library is being used in. If in doubt, consult with a professional cryptographer. **WARNING:** Because of the way `KeyProtectedByPassword` is implemented, knowing `SHA256($password)` is enough to decrypt a `KeyProtectedByPassword`. To be secure, your application MUST NOT EVER compute `SHA256($password)` and use or store it for any reason. You must also make sure that other libraries your application is using don't compute it either. Static Methods --------------- ### KeyProtectedByPassword::createRandomPasswordProtectedKey($password) **Description:** Generates a new random key that's protected by the string `$password` and returns an instance of `KeyProtectedByPassword`. **Parameters:** 1. `$password` is the password used to protect the random key. **Return value:** Returns an instance of `KeyProtectedByPassword` containing a randomly-generated encryption key that's protected by the password `$password`. **Exceptions:** - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when the platform the code is running on cannot safely perform encryption for some reason (e.g. it lacks a secure random number generator), or the runtime tests detected a bug in this library. **Side-effects and performance:** This method runs a small and very fast set of self-tests if it is the very first time this method or one of the `Crypto` methods has been called. The performance overhead is negligible and can be safely ignored in all applications. **Cautions:** PHP stack traces display (portions of) the arguments passed to methods on the call stack. If an exception is thrown inside this call, and it is uncaught, the value of `$password` may be leaked out to an attacker through the stack trace. We recommend configuring PHP to never output stack traces (either displaying them to the user or saving them to log files). Be aware that if you protecting multiple keys with the same password, an attacker with write access to your system will be able to swap the protected keys around so that the wrong key gets used next time it is unlocked. This could lead to data being encrypted with the wrong key, perhaps one that the attacker knows. **WARNING:** Because of the way `KeyProtectedByPassword` is implemented, knowing `SHA256($password)` is enough to decrypt a `KeyProtectedByPassword`. To be secure, your application MUST NOT EVER compute `SHA256($password)` and use or store it for any reason. You must also make sure that other libraries your application is using don't compute it either. ### KeyProtectedByPassword::loadFromAsciiSafeString($saved\_key\_string) **Description:** Loads an instance of `KeyProtectedByPassword` that was saved to a string by `saveToAsciiSafeString()`. **Parameters:** 1. `$saved_key_string` is the string returned from `saveToAsciiSafeString()` when the original `KeyProtectedByPassword` instance was saved. **Return value:** Returns an instance of `KeyProtectedByPassword` representing the same password-protected key as the one that was represented by the `KeyProtectedByPassword` instance that got saved into `$saved_key_string` by a call to `saveToAsciiSafeString()`. **Exceptions:** - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when the platform the code is running on cannot safely perform encryption for some reason (e.g. it lacks a secure random number generator), or the runtime tests detected a bug in this library. - `Defuse\Crypto\Exception\BadFormatException` is thrown whenever `$saved_key_string` does not represent a valid `KeyProtectedByPassword` instance. **Side-effects and performance:** None. **Cautions:** None.
Back to File Manager