[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace Defuse\Crypto;
   4  
   5  use Defuse\Crypto\Exception as Ex;
   6  
   7  final class KeyProtectedByPassword
   8  {
   9      const PASSWORD_KEY_CURRENT_VERSION = "\xDE\xF1\x00\x00";
  10  
  11      /**
  12       * @var string
  13       */
  14      private $encrypted_key = '';
  15  
  16      /**
  17       * Creates a random key protected by the provided password.
  18       *
  19       * @param string $password
  20       *
  21       * @throws Ex\EnvironmentIsBrokenException
  22       *
  23       * @return KeyProtectedByPassword
  24       */
  25      public static function createRandomPasswordProtectedKey($password)
  26      {
  27          $inner_key = Key::createNewRandomKey();
  28          /* The password is hashed as a form of poor-man's domain separation
  29           * between this use of encryptWithPassword() and other uses of
  30           * encryptWithPassword() that the user may also be using as part of the
  31           * same protocol. */
  32          $encrypted_key = Crypto::encryptWithPassword(
  33              $inner_key->saveToAsciiSafeString(),
  34              \hash(Core::HASH_FUNCTION_NAME, $password, true),
  35              true
  36          );
  37  
  38          return new KeyProtectedByPassword($encrypted_key);
  39      }
  40  
  41      /**
  42       * Loads a KeyProtectedByPassword from its encoded form.
  43       *
  44       * @param string $saved_key_string
  45       *
  46       * @throws Ex\BadFormatException
  47       *
  48       * @return KeyProtectedByPassword
  49       */
  50      public static function loadFromAsciiSafeString($saved_key_string)
  51      {
  52          $encrypted_key = Encoding::loadBytesFromChecksummedAsciiSafeString(
  53              self::PASSWORD_KEY_CURRENT_VERSION,
  54              $saved_key_string
  55          );
  56          return new KeyProtectedByPassword($encrypted_key);
  57      }
  58  
  59      /**
  60       * Encodes the KeyProtectedByPassword into a string of printable ASCII
  61       * characters.
  62       *
  63       * @throws Ex\EnvironmentIsBrokenException
  64       *
  65       * @return string
  66       */
  67      public function saveToAsciiSafeString()
  68      {
  69          return Encoding::saveBytesToChecksummedAsciiSafeString(
  70              self::PASSWORD_KEY_CURRENT_VERSION,
  71              $this->encrypted_key
  72          );
  73      }
  74  
  75      /**
  76       * Decrypts the protected key, returning an unprotected Key object that can
  77       * be used for encryption and decryption.
  78       *
  79       * @throws Ex\EnvironmentIsBrokenException
  80       * @throws Ex\WrongKeyOrModifiedCiphertextException
  81       *
  82       * @param string $password
  83       * @return Key
  84       */
  85      public function unlockKey($password)
  86      {
  87          try {
  88              $inner_key_encoded = Crypto::decryptWithPassword(
  89                  $this->encrypted_key,
  90                  \hash(Core::HASH_FUNCTION_NAME, $password, true),
  91                  true
  92              );
  93              return Key::loadFromAsciiSafeString($inner_key_encoded);
  94          } catch (Ex\BadFormatException $ex) {
  95              /* This should never happen unless an attacker replaced the
  96               * encrypted key ciphertext with some other ciphertext that was
  97               * encrypted with the same password. We transform the exception type
  98               * here in order to make the API simpler, avoiding the need to
  99               * document that this method might throw an Ex\BadFormatException. */
 100              throw new Ex\WrongKeyOrModifiedCiphertextException(
 101                  "The decrypted key was found to be in an invalid format. " .
 102                  "This very likely indicates it was modified by an attacker."
 103              );
 104          }
 105      }
 106  
 107      /**
 108       * Changes the password.
 109       *
 110       * @param string $current_password
 111       * @param string $new_password
 112       *
 113       * @throws Ex\EnvironmentIsBrokenException
 114       * @throws Ex\WrongKeyOrModifiedCiphertextException
 115       *
 116       * @return KeyProtectedByPassword
 117       */
 118      public function changePassword($current_password, $new_password)
 119      {
 120          $inner_key = $this->unlockKey($current_password);
 121          /* The password is hashed as a form of poor-man's domain separation
 122           * between this use of encryptWithPassword() and other uses of
 123           * encryptWithPassword() that the user may also be using as part of the
 124           * same protocol. */
 125          $encrypted_key = Crypto::encryptWithPassword(
 126              $inner_key->saveToAsciiSafeString(),
 127              \hash(Core::HASH_FUNCTION_NAME, $new_password, true),
 128              true
 129          );
 130  
 131          $this->encrypted_key = $encrypted_key;
 132  
 133          return $this;
 134      }
 135  
 136      /**
 137       * Constructor for KeyProtectedByPassword.
 138       *
 139       * @param string $encrypted_key
 140       */
 141      private function __construct($encrypted_key)
 142      {
 143          $this->encrypted_key = $encrypted_key;
 144      }
 145  }