260 lines
10 KiB
Markdown
260 lines
10 KiB
Markdown
|
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.
|