You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

196 lines
5.9 KiB

3 years ago
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Bjoern Schiessle <bjoern@schiessle.org>
  6. * @author Björn Schießle <bjoern@schiessle.org>
  7. * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  8. * @author Lukas Reschke <lukas@statuscode.ch>
  9. * @author Morris Jobke <hey@morrisjobke.de>
  10. * @author Thomas Müller <thomas.mueller@tmit.eu>
  11. *
  12. * @license AGPL-3.0
  13. *
  14. * This code is free software: you can redistribute it and/or modify
  15. * it under the terms of the GNU Affero General Public License, version 3,
  16. * as published by the Free Software Foundation.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License, version 3,
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>
  25. *
  26. */
  27. namespace OCP\Encryption;
  28. use Symfony\Component\Console\Input\InputInterface;
  29. use Symfony\Component\Console\Output\OutputInterface;
  30. /**
  31. * Interface IEncryptionModule
  32. *
  33. * @since 8.1.0
  34. */
  35. interface IEncryptionModule {
  36. /**
  37. * @return string defining the technical unique id
  38. * @since 8.1.0
  39. */
  40. public function getId();
  41. /**
  42. * In comparison to getKey() this function returns a human readable (maybe translated) name
  43. *
  44. * @return string
  45. * @since 8.1.0
  46. */
  47. public function getDisplayName();
  48. /**
  49. * start receiving chunks from a file. This is the place where you can
  50. * perform some initial step before starting encrypting/decrypting the
  51. * chunks
  52. *
  53. * @param string $path to the file
  54. * @param string $user who read/write the file (null for public access)
  55. * @param string $mode php stream open mode
  56. * @param array $header contains the header data read from the file
  57. * @param array $accessList who has access to the file contains the key 'users' and 'public'
  58. *
  59. * $return array $header contain data as key-value pairs which should be
  60. * written to the header, in case of a write operation
  61. * or if no additional data is needed return a empty array
  62. * @since 8.1.0
  63. */
  64. public function begin($path, $user, $mode, array $header, array $accessList);
  65. /**
  66. * last chunk received. This is the place where you can perform some final
  67. * operation and return some remaining data if something is left in your
  68. * buffer.
  69. *
  70. * @param string $path to the file
  71. * @param string $position id of the last block (looks like "<Number>end")
  72. *
  73. * @return string remained data which should be written to the file in case
  74. * of a write operation
  75. *
  76. * @since 8.1.0
  77. * @since 9.0.0 parameter $position added
  78. */
  79. public function end($path, $position);
  80. /**
  81. * encrypt data
  82. *
  83. * @param string $data you want to encrypt
  84. * @param string $position position of the block we want to encrypt (starts with '0')
  85. *
  86. * @return mixed encrypted data
  87. *
  88. * @since 8.1.0
  89. * @since 9.0.0 parameter $position added
  90. */
  91. public function encrypt($data, $position);
  92. /**
  93. * decrypt data
  94. *
  95. * @param string $data you want to decrypt
  96. * @param string $position position of the block we want to decrypt
  97. *
  98. * @return mixed decrypted data
  99. *
  100. * @since 8.1.0
  101. * @since 9.0.0 parameter $position added
  102. */
  103. public function decrypt($data, $position);
  104. /**
  105. * update encrypted file, e.g. give additional users access to the file
  106. *
  107. * @param string $path path to the file which should be updated
  108. * @param string $uid of the user who performs the operation
  109. * @param array $accessList who has access to the file contains the key 'users' and 'public'
  110. * @return boolean
  111. * @since 8.1.0
  112. */
  113. public function update($path, $uid, array $accessList);
  114. /**
  115. * should the file be encrypted or not
  116. *
  117. * @param string $path
  118. * @return boolean
  119. * @since 8.1.0
  120. */
  121. public function shouldEncrypt($path);
  122. /**
  123. * get size of the unencrypted payload per block.
  124. * ownCloud read/write files with a block size of 8192 byte
  125. *
  126. * @param bool $signed
  127. * @return int
  128. * @since 8.1.0 optional parameter $signed was added in 9.0.0
  129. */
  130. public function getUnencryptedBlockSize($signed = false);
  131. /**
  132. * check if the encryption module is able to read the file,
  133. * e.g. if all encryption keys exists
  134. *
  135. * @param string $path
  136. * @param string $uid user for whom we want to check if he can read the file
  137. * @return boolean
  138. * @since 8.1.0
  139. */
  140. public function isReadable($path, $uid);
  141. /**
  142. * Initial encryption of all files
  143. *
  144. * @param InputInterface $input
  145. * @param OutputInterface $output write some status information to the terminal during encryption
  146. * @since 8.2.0
  147. */
  148. public function encryptAll(InputInterface $input, OutputInterface $output);
  149. /**
  150. * prepare encryption module to decrypt all files
  151. *
  152. * @param InputInterface $input
  153. * @param OutputInterface $output write some status information to the terminal during encryption
  154. * @param $user (optional) for which the files should be decrypted, default = all users
  155. * @return bool return false on failure or if it isn't supported by the module
  156. * @since 8.2.0
  157. */
  158. public function prepareDecryptAll(InputInterface $input, OutputInterface $output, $user = '');
  159. /**
  160. * Check if the module is ready to be used by that specific user.
  161. * In case a module is not ready - because e.g. key pairs have not been generated
  162. * upon login this method can return false before any operation starts and might
  163. * cause issues during operations.
  164. *
  165. * @param string $user
  166. * @return boolean
  167. * @since 9.1.0
  168. */
  169. public function isReadyForUser($user);
  170. /**
  171. * Does the encryption module needs a detailed list of users with access to the file?
  172. * For example if the encryption module uses per-user encryption keys and needs to know
  173. * the users with access to the file to encrypt/decrypt it.
  174. *
  175. * @since 13.0.0
  176. * @return bool
  177. */
  178. public function needDetailedAccessList();
  179. }