vendor/zendframework/zend-crypt/doc/book/files.md

   1 # Encrypt and decrypt files
   2
   3 `Zend\Crypt\FileCipher` implements file encryption and decryption using a
   4 symmetric cipher in
   5 [CBC](http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation#Cipher-block_chaining_.28CBC.29)
   6 mode with the encrypt-then-authenticate approach, using
   7 [HMAC](http://en.wikipedia.org/wiki/HMAC) to provide authentication (the same
   8 solution used by `Zend\Crypt\BlockCipher` component).
   9
  10 Encrypting and decrypting a file is not an easy task, especially with large
  11 files. For instance, in CBC mode you must be sure to handle the
  12 [IV](http://en.wikipedia.org/wiki/Initialization_vector) correctly for each
  13 block. For large files, that means that you need to use a buffer and use the
  14 last block of the buffer as the new IV for the next encryption step.
  15
  16 The `FileCipher` uses a symmetric cipher, with the `Zend\Crypt\Symmetric\Mcrypt` component.
  17
  18 The usage of this component is very simple; create an instance of `FileCipher`,
  19 specify the key, and you are ready to encrypt/decrypt any file:
  20
  21 ```php
  22 use Zend\Crypt\FileCipher;
  23
  24 $fileCipher = new FileCipher;
  25 $fileCipher->setKey('encryption key');
  26
  27 // encryption
  28 if ($fileCipher->encrypt('path/to/file_to_encrypt', 'path/to/output')) {
  29     echo "The file has been encrypted successfully\n";
  30 }
  31
  32 // decryption
  33 if ($fileCipher->decrypt('path/to/file_to_decrypt', 'path/to/output')) {
  34     echo "The file has been decrypted successfully\n";
  35 }
  36 ```
  37
  38 By default, `FileCipher` uses the [AES](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
  39 encryption algorithm (with a 256-bit key) and the [SHA-256](http://en.wikipedia.org/wiki/SHA-2)
  40 hash algorithm to authenticate the data using the HMAC function. This component uses the
  41 [PBKDF2](http://en.wikipedia.org/wiki/PBKDF2) key derivation algorithm to generate the encryption
  42 key and the authentication key, for the HMAC, based on the key specified using the method
  43 `setKey()`.
  44
  45 If you want to change the encryption algorithm, you can use the `setCipherAlgorithm()` function. For
  46 instance, you could specify the [Blowfish](http://en.wikipedia.org/wiki/Blowfish_%28cipher%29)
  47 encryption algorithm using `setCipherAlgorithm('blowfish')`. You can retrieve the list of all
  48 supported encryption algorithms in your environment using the function
  49 `getCipherSupportedAlgorithms()`.
  50
  51 If you need to customize the cipher algorithm &mdash; for instance, to change
  52 the Padding mode &mdash; you can inject your `Mcrypt` object in the `FileCipher`
  53 using the `setCipher()` method. The only parameter of the cipher that you cannot
  54 change is the cipher mode, which is hard-coded to CBC.
  55
  56 > ## Output format
  57 >
  58 > The output of the encryption file is in binary format. We used this format to
  59 > reduce impact on output size. If you encrypt a file using the `FileCipher`
  60 > component, you will notice that the output file size is almost the same as the
  61 > input size, with a few additional bytes to store the HMAC and the IV vector.
  62 > The format of the output is the concatenation of the HMAC, the IV, and the
  63 > encrypted file contents.