1# Copyright 2020 Google LLC 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""This module defines the 'raw' interface for Streaming AEAD.""" 15 16import abc 17import io 18from typing import BinaryIO 19 20 21class RawStreamingAead(metaclass=abc.ABCMeta): 22 """Raw interface for streaming authenticated encryption with associated data. 23 24 Streaming encryption is typically used for encrypting large plaintexts such 25 as large files. This interface supports a streaming interface for symmetric 26 encryption with authentication. The underlying encryption modes are selected 27 so that partial plaintext can be obtained fast by decrypting and 28 authenticating just a part of the ciphertext. 29 30 This is the 'raw' interface implemented by key managers, based on 31 io.RawIOBase. Users usually don't use this directly. Instead, they should use 32 streaming_aead.StreamingAead, generated from a keyset_handle. 33 """ 34 35 @abc.abstractmethod 36 def new_raw_encrypting_stream(self, ciphertext_destination: BinaryIO, 37 associated_data: bytes) -> io.RawIOBase: 38 """Returns a raw encrypting stream that writes to ciphertext_destination. 39 40 The returned stream implements a writable io.RawIOBase interface. Users 41 usually don't use this directly, they should use 42 streaming_aead.StreamingAead instead. 43 44 The ciphertext_destination's write() method is expected to present one of 45 the following three behaviours in the case of a partial or failed write(): 46 - return a non-negative integer number of bytes written 47 - return None (equivalent to returning 0) 48 - raise BlockingIOError with characters_written set correctly to a 49 non-negative integer (equivalent to returning that integer) 50 In the case of a full write, the number of bytes written should be returned. 51 The standard io.BufferedIOBase and io.RawIOBase base classes exhibit these 52 behaviours and are hence supported. 53 54 Args: 55 ciphertext_destination: A writable binary file object to which ciphertext 56 will be written. It must support write(), close(), closed, and 57 writable(). 58 associated_data: Associated data to be used by the AEAD encryption. It is 59 not included in the ciphertext and must be passed in as a parameter for 60 decryption. 61 62 Returns: 63 A writable implementation of the io.RawIOBase interface that wraps around 64 'ciphertext_destination', such that any bytes written to the wrapper are 65 AEAD-encrypted using 'associated_data' as associated authenticated data. 66 Closing this wrapper also closes the ciphertext_source. 67 Raises: 68 tink.TinkError if the creation fails. 69 """ 70 raise NotImplementedError() 71 72 @abc.abstractmethod 73 def new_raw_decrypting_stream( 74 self, 75 ciphertext_source: BinaryIO, 76 associated_data: bytes, 77 close_ciphertext_source: bool) -> io.RawIOBase: 78 """Returns a raw decrypting stream that reads from ciphertext_source. 79 80 The returned stream implements a readable io.RawIOBase interface. Users 81 usually don't use this directly, they should use 82 streaming_aead.StreamingAead instead. 83 84 The cipertext_source's read() method is expected to return an empty bytes 85 object if the stream is already at EOF. In the case where the stream is not 86 at EOF yet but no data is available at the moment, it is expected to either 87 block until data is available, return None or raise a BlockingIOError. 88 The standard io.BufferedIOBase and io.RawIOBase base classes exhibit these 89 behaviours and are hence supported. 90 91 Args: 92 ciphertext_source: A readable binary file object from which ciphertext 93 will be read. 94 associated_data: Associated data to be used by the AEAD decryption. It 95 must match the associated_data supplied for the encryption. 96 close_ciphertext_source: Whether ciphertext_source should be closed when 97 close() is called. 98 99 Returns: 100 A readable implementation of the io.RawIOBase interface that wraps around 101 'ciphertext_source', such that any bytes read from the wrapper are 102 AEAD-decrypted using 'associated_data' as associated authenticated data. 103 Raises: 104 tink.TinkError if the creation fails. 105 """ 106 raise NotImplementedError() 107