API reference

encrypted_stream.generate_key()

Generates a new secure random key, for use with the other classes in this module. If you’re not deriving the key from some kind of other secret, this is the function you should use to make a new one.

class encrypted_stream.EncryptingReader(source, key)

File-like object that provides a transparently encrypted view over another stream.

Important

EncryptingReader has a few expectations regarding the source stream:

  • it needs to be seekable

  • it must have a definite and fixed length

  • while the reader is active (not closed), it requires exclusive access to the source stream, since the cursor position of the source is used as part of the internal state. Doing seeks, reads, writes, or anything else that will move the source stream’s cursor active will likely result in unexpected exceptions (if you’re lucky), or corrupt the output stream silently. Additionally, rewriting parts of the source stream – even if you reset the cursor – may result in a breakdown of the cryptographic security guarantees provided by this module, if you continue to use the reader afterwards.

Parameters

  • source – The file-like object you want to encrypt. See above for required properties.

  • key – The key used for encryption, must be a bytes object of length 32. Generate or derive this key in a secure way.

get_next_block()

reads, encrypts, and returns one block starting at the current source file position

readable()

Return whether object was opened for reading.

If False, read() will raise OSError.

seek(offset, whence=0)

Change stream position.

Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:

  • 0 – start of stream (the default); offset should be zero or positive

  • 1 – current stream position; offset may be negative

  • 2 – end of stream; offset is usually negative

Return the new absolute position.

seekable()

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

tell()

Return current stream position.

class encrypted_stream.DecryptingWriter(sink, key)

File-like object that transparently decrypts incoming data into an underlying buffer.

Parameters

  • sink – The file-like object into which data will be decrypted

  • key – The key used for decryption

close()

Close the writer. Note that this does not close the underlying stream, so you’ll have to do that yourself. This allows you to close the stream even if you haven’t reached the end, in case you want to pick up where you left of later. If you did reach the end, don’t forget to call end_stream() before you call this method.

end_stream()

Call this when you’ve reached the end of the encrypted source stream. It will ensure that the data you’ve received is complete and that everything is written to the sink stream, and then close the writer.

flush()

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

readable()

Return whether object was opened for reading.

If False, read() will raise OSError.

seekable()

While DecryptingWriter doesn’t support seeking, tell() still works

tell()

Return current stream position.

writable()

Return whether object was opened for writing.

If False, write() will raise OSError.