vendor/defuse/php-encryption/docs/classes/File.md

   1 Class: Defuse\Crypto\File
   2 ==========================
   3
   4 Instance Methods
   5 -----------------
   6
   7 This class has no instance methods.
   8
   9 Static Methods
  10 ---------------
  11
  12 ### File::encryptFile($inputFilename, $outputFilename, Key $key)
  13
  14 **Description:**
  15
  16 Encrypts a file using a secret key.
  17
  18 **Parameters:**
  19
  20 1. `$inputFilename` is the path to a file containing the plaintext to encrypt.
  21 2. `$outputFilename` is the path to save the ciphertext file.
  22 3. `$key` is an instance of `Key` containing the secret key for encryption.
  23
  24 **Behavior:**
  25
  26 Encrypts the contents of the input file, writing the result to the output file.
  27 If the output file already exists, it is overwritten.
  28
  29 **Return value:**
  30
  31 Does not return a value.
  32
  33 **Exceptions:**
  34
  35 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
  36
  37 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
  38   the platform the code is running on cannot safely perform encryption for some
  39   reason (e.g. it lacks a secure random number generator), or the runtime tests
  40   detected a bug in this library.
  41
  42 **Side-effects and performance:**
  43
  44 None.
  45
  46 **Cautions:**
  47
  48 The ciphertext output by this method is decryptable by anyone with knowledge of
  49 the key `$key`. It is the caller's responsibility to keep `$key` secret. Where
  50 `$key` should be stored is up to the caller and depends on the threat model the
  51 caller is designing their application under. If you are unsure where to store
  52 `$key`, consult with a professional cryptographer to get help designing your
  53 application.
  54
  55 ### File::decryptFile($inputFilename, $outputFilename, Key $key)
  56
  57 **Description:**
  58
  59 Decrypts a file using a secret key.
  60
  61 **Parameters:**
  62
  63 1. `$inputFilename` is the path to a file containing the ciphertext to decrypt.
  64 2. `$outputFilename` is the path to save the decrypted plaintext file.
  65 3. `$key` is an instance of `Key` containing the secret key for decryption.
  66
  67 **Behavior:**
  68
  69 Decrypts the contents of the input file, writing the result to the output file.
  70 If the output file already exists, it is overwritten.
  71
  72 **Return value:**
  73
  74 Does not return a value.
  75
  76 **Exceptions:**
  77
  78 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
  79
  80 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
  81   the platform the code is running on cannot safely perform encryption for some
  82   reason (e.g. it lacks a secure random number generator), or the runtime tests
  83   detected a bug in this library.
  84
  85 - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if
  86   the `$key` is not the correct key for the given ciphertext, or if the
  87   ciphertext has been modified (possibly maliciously). There is no way to
  88   distinguish between these two cases.
  89
  90 **Side-effects and performance:**
  91
  92 The input ciphertext is processed in two passes. The first pass verifies the
  93 integrity and the second pass performs the actual decryption of the file and
  94 writing to the output file. This is done in a streaming manner so that only
  95 a small part of the file is ever loaded into memory at a time.
  96
  97 **Cautions:**
  98
  99 Be aware that when `Defuse\Crypto\WrongKeyOrModifiedCiphertextException` is
 100 thrown, some partial plaintext data may have been written to the output. Any
 101 plaintext data that is output is guaranteed to be a prefix of the original
 102 plaintext (i.e. at worst it was truncated). This can only happen if an attacker
 103 modifies the input between the first pass (integrity check) and the second pass
 104 (decryption) over the file.
 105
 106 It is impossible in principle to distinguish between the case where you attempt
 107 to decrypt with the wrong key and the case where you attempt to decrypt
 108 a modified (corrupted) ciphertext. It is up to the caller how to best deal with
 109 this ambiguity, as it depends on the application this library is being used in.
 110 If in doubt, consult with a professional cryptographer.
 111
 112 ### File::encryptFileWithPassword($inputFilename, $outputFilename, $password)
 113
 114 **Description:**
 115
 116 Encrypts a file with a password.
 117
 118 **Parameters:**
 119
 120 1. `$inputFilename` is the path to a file containing the plaintext to encrypt.
 121 2. `$outputFilename` is the path to save the ciphertext file.
 122 3. `$password` is the password used for decryption.
 123
 124 **Behavior:**
 125
 126 Encrypts the contents of the input file, writing the result to the output file.
 127 If the output file already exists, it is overwritten.
 128
 129 **Return value:**
 130
 131 Does not return a value.
 132
 133 **Exceptions:**
 134
 135 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 136
 137 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 138   the platform the code is running on cannot safely perform encryption for some
 139   reason (e.g. it lacks a secure random number generator), or the runtime tests
 140   detected a bug in this library.
 141
 142 **Side-effects and performance:**
 143
 144 This method is intentionally slow, using a lot of CPU resources for a fraction
 145 of a second. It applies key stretching to the password in order to make password
 146 guessing attacks more computationally expensive. If you need a faster way to
 147 encrypt multiple ciphertexts under the same password, see the
 148 `KeyProtectedByPassword` class.
 149
 150 **Cautions:**
 151
 152 PHP stack traces display (portions of) the arguments passed to methods on the
 153 call stack. If an exception is thrown inside this call, and it is uncaught, the
 154 value of `$password` may be leaked out to an attacker through the stack trace.
 155 We recommend configuring PHP to never output stack traces (either displaying
 156 them to the user or saving them to log files).
 157
 158 ### File::decryptFileWithPassword($inputFilename, $outputFilename, $password)
 159
 160 **Description:**
 161
 162 Decrypts a file with a password.
 163
 164 **Parameters:**
 165
 166 1. `$inputFilename` is the path to a file containing the ciphertext to decrypt.
 167 2. `$outputFilename` is the path to save the decrypted plaintext file.
 168 3. `$password` is the password used for decryption.
 169
 170 **Behavior:**
 171
 172 Decrypts the contents of the input file, writing the result to the output file.
 173 If the output file already exists, it is overwritten.
 174
 175 **Return value:**
 176
 177 Does not return a value.
 178
 179 **Exceptions:**
 180
 181 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 182
 183 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 184   the platform the code is running on cannot safely perform encryption for some
 185   reason (e.g. it lacks a secure random number generator), or the runtime tests
 186   detected a bug in this library.
 187
 188 - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if
 189   the `$password` is not the correct key for the given ciphertext, or if the
 190   ciphertext has been modified (possibly maliciously). There is no way to
 191   distinguish between these two cases.
 192
 193 **Side-effects and performance:**
 194
 195 This method is intentionally slow, using a lot of CPU resources for a fraction
 196 of a second. It applies key stretching to the password in order to make password
 197 guessing attacks more computationally expensive. If you need a faster way to
 198 encrypt multiple ciphertexts under the same password, see the
 199 `KeyProtectedByPassword` class.
 200
 201 The input ciphertext is processed in two passes. The first pass verifies the
 202 integrity and the second pass performs the actual decryption of the file and
 203 writing to the output file. This is done in a streaming manner so that only
 204 a small part of the file is ever loaded into memory at a time.
 205
 206 **Cautions:**
 207
 208 PHP stack traces display (portions of) the arguments passed to methods on the
 209 call stack. If an exception is thrown inside this call, and it is uncaught, the
 210 value of `$password` may be leaked out to an attacker through the stack trace.
 211 We recommend configuring PHP to never output stack traces (either displaying
 212 them to the user or saving them to log files).
 213
 214 Be aware that when `Defuse\Crypto\WrongKeyOrModifiedCiphertextException` is
 215 thrown, some partial plaintext data may have been written to the output. Any
 216 plaintext data that is output is guaranteed to be a prefix of the original
 217 plaintext (i.e. at worst it was truncated). This can only happen if an attacker
 218 modifies the input between the first pass (integrity check) and the second pass
 219 (decryption) over the file.
 220
 221 It is impossible in principle to distinguish between the case where you attempt
 222 to decrypt with the wrong password and the case where you attempt to decrypt
 223 a modified (corrupted) ciphertext. It is up to the caller how to best deal with
 224 this ambiguity, as it depends on the application this library is being used in.
 225 If in doubt, consult with a professional cryptographer.
 226
 227 ### File::encryptResource($inputHandle, $outputHandle, Key $key)
 228
 229 **Description:**
 230
 231 Encrypts a resource (stream) with a secret key.
 232
 233 **Parameters:**
 234
 235 1. `$inputHandle` is a handle to a resource (like a file pointer) containing the
 236    plaintext to encrypt.
 237 2. `$outputHandle` is a handle to a resource (like a file pointer) that the
 238    ciphertext will be written to.
 239 3. `$key` is an instance of `Key` containing the secret key for encryption.
 240
 241 **Behavior:**
 242
 243 Encrypts the data read from the input stream and writes it to the output stream.
 244
 245 **Return value:**
 246
 247 Does not return a value.
 248
 249 **Exceptions:**
 250
 251 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 252
 253 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 254   the platform the code is running on cannot safely perform encryption for some
 255   reason (e.g. it lacks a secure random number generator), or the runtime tests
 256   detected a bug in this library.
 257
 258 **Side-effects and performance:**
 259
 260 None.
 261
 262 **Cautions:**
 263
 264 The ciphertext output by this method is decryptable by anyone with knowledge of
 265 the key `$key`. It is the caller's responsibility to keep `$key` secret. Where
 266 `$key` should be stored is up to the caller and depends on the threat model the
 267 caller is designing their application under. If you are unsure where to store
 268 `$key`, consult with a professional cryptographer to get help designing your
 269 application.
 270
 271 ### File::decryptResource($inputHandle, $outputHandle, Key $key)
 272
 273 **Description:**
 274
 275 Decrypts a resource (stream) with a secret key.
 276
 277 **Parameters:**
 278
 279 1. `$inputHandle` is a handle to a file-backed resource containing the
 280    ciphertext to decrypt. It must be a file not a network stream or standard
 281    input.
 282 2. `$outputHandle` is a handle to a resource (like a file pointer) that the
 283    plaintext will be written to.
 284 3. `$key` is an instance of `Key` containing the secret key for decryption.
 285
 286 **Behavior:**
 287
 288 Decrypts the data read from the input stream and writes it to the output stream.
 289
 290 **Return value:**
 291
 292 Does not return a value.
 293
 294 **Exceptions:**
 295
 296 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 297
 298 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 299   the platform the code is running on cannot safely perform encryption for some
 300   reason (e.g. it lacks a secure random number generator), or the runtime tests
 301   detected a bug in this library.
 302
 303 - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if
 304   the `$key` is not the correct key for the given ciphertext, or if the
 305   ciphertext has been modified (possibly maliciously). There is no way to
 306   distinguish between these two cases.
 307
 308 **Side-effects and performance:**
 309
 310 The input ciphertext is processed in two passes. The first pass verifies the
 311 integrity and the second pass performs the actual decryption of the file and
 312 writing to the output file. This is done in a streaming manner so that only
 313 a small part of the file is ever loaded into memory at a time.
 314
 315 **Cautions:**
 316
 317 Be aware that when `Defuse\Crypto\WrongKeyOrModifiedCiphertextException` is
 318 thrown, some partial plaintext data may have been written to the output. Any
 319 plaintext data that is output is guaranteed to be a prefix of the original
 320 plaintext (i.e. at worst it was truncated). This can only happen if an attacker
 321 modifies the input between the first pass (integrity check) and the second pass
 322 (decryption) over the file.
 323
 324 It is impossible in principle to distinguish between the case where you attempt
 325 to decrypt with the wrong key and the case where you attempt to decrypt
 326 a modified (corrupted) ciphertext. It is up to the caller how to best deal with
 327 this ambiguity, as it depends on the application this library is being used in.
 328 If in doubt, consult with a professional cryptographer.
 329
 330 ### File::encryptResourceWithPassword($inputHandle, $outputHandle, $password)
 331
 332 **Description:**
 333
 334 Encrypts a resource (stream) with a password.
 335
 336 **Parameters:**
 337
 338 1. `$inputHandle` is a handle to a resource (like a file pointer) containing the
 339    plaintext to encrypt.
 340 2. `$outputHandle` is a handle to a resource (like a file pointer) that the
 341    ciphertext will be written to.
 342 3. `$password` is the password used for encryption.
 343
 344 **Behavior:**
 345
 346 Encrypts the data read from the input stream and writes it to the output stream.
 347
 348 **Return value:**
 349
 350 Does not return a value.
 351
 352 **Exceptions:**
 353
 354 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 355
 356 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 357   the platform the code is running on cannot safely perform encryption for some
 358   reason (e.g. it lacks a secure random number generator), or the runtime tests
 359   detected a bug in this library.
 360
 361 **Side-effects and performance:**
 362
 363 This method is intentionally slow, using a lot of CPU resources for a fraction
 364 of a second. It applies key stretching to the password in order to make password
 365 guessing attacks more computationally expensive. If you need a faster way to
 366 encrypt multiple ciphertexts under the same password, see the
 367 `KeyProtectedByPassword` class.
 368
 369 **Cautions:**
 370
 371 PHP stack traces display (portions of) the arguments passed to methods on the
 372 call stack. If an exception is thrown inside this call, and it is uncaught, the
 373 value of `$password` may be leaked out to an attacker through the stack trace.
 374 We recommend configuring PHP to never output stack traces (either displaying
 375 them to the user or saving them to log files).
 376
 377 ### File::decryptResourceWithPassword($inputHandle, $outputHandle, $password)
 378
 379 **Description:**
 380
 381 Decrypts a resource (stream) with a password.
 382
 383 **Parameters:**
 384
 385 1. `$inputHandle` is a handle to a file-backed resource containing the
 386    ciphertext to decrypt. It must be a file not a network stream or standard
 387    input.
 388 2. `$outputHandle` is a handle to a resource (like a file pointer) that the
 389    plaintext will be written to.
 390 3. `$password` is the password used for decryption.
 391
 392 **Behavior:**
 393
 394 Decrypts the data read from the input stream and writes it to the output stream.
 395
 396 **Return value:**
 397
 398 Does not return a value.
 399
 400 **Exceptions:**
 401
 402 - `Defuse\Crypto\Exception\IOException` is thrown if there is an I/O error.
 403
 404 - `Defuse\Crypto\Exception\EnvironmentIsBrokenException` is thrown either when
 405   the platform the code is running on cannot safely perform encryption for some
 406   reason (e.g. it lacks a secure random number generator), or the runtime tests
 407   detected a bug in this library.
 408
 409 - `Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException` is thrown if
 410   the `$password` is not the correct key for the given ciphertext, or if the
 411   ciphertext has been modified (possibly maliciously). There is no way to
 412   distinguish between these two cases.
 413
 414 **Side-effects and performance:**
 415
 416 This method is intentionally slow, using a lot of CPU resources for a fraction
 417 of a second. It applies key stretching to the password in order to make password
 418 guessing attacks more computationally expensive. If you need a faster way to
 419 encrypt multiple ciphertexts under the same password, see the
 420 `KeyProtectedByPassword` class.
 421
 422 The input ciphertext is processed in two passes. The first pass verifies the
 423 integrity and the second pass performs the actual decryption of the file and
 424 writing to the output file. This is done in a streaming manner so that only
 425 a small part of the file is ever loaded into memory at a time.
 426
 427 **Cautions:**
 428
 429 PHP stack traces display (portions of) the arguments passed to methods on the
 430 call stack. If an exception is thrown inside this call, and it is uncaught, the
 431 value of `$password` may be leaked out to an attacker through the stack trace.
 432 We recommend configuring PHP to never output stack traces (either displaying
 433 them to the user or saving them to log files).
 434
 435 Be aware that when `Defuse\Crypto\WrongKeyOrModifiedCiphertextException` is
 436 thrown, some partial plaintext data may have been written to the output. Any
 437 plaintext data that is output is guaranteed to be a prefix of the original
 438 plaintext (i.e. at worst it was truncated). This can only happen if an attacker
 439 modifies the input between the first pass (integrity check) and the second pass
 440 (decryption) over the file.
 441
 442 It is impossible in principle to distinguish between the case where you attempt
 443 to decrypt with the wrong password and the case where you attempt to decrypt
 444 a modified (corrupted) ciphertext. It is up to the caller how to best deal with
 445 this ambiguity, as it depends on the application this library is being used in.
 446 If in doubt, consult with a professional cryptographer.