[v7,12/20] qcow2: extend specification to cover LUKS encryption

Update the qcow2 specification to describe how the LUKS header is
placed inside a qcow2 file, when using LUKS encryption for the
qcow2 payload instead of the legacy AES-CBC encryption

Reviewed-by: Alberto Garcia <berto@igalia.com>
Reviewed-by: Max Reitz <mreitz@redhat.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
---
 docs/specs/qcow2.txt | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

On 05/25/2017 11:38 AM, Daniel P. Berrange wrote:
> Update the qcow2 specification to describe how the LUKS header is
> placed inside a qcow2 file, when using LUKS encryption for the
> qcow2 payload instead of the legacy AES-CBC encryption
> 
> Reviewed-by: Alberto Garcia <berto@igalia.com>
> Reviewed-by: Max Reitz <mreitz@redhat.com>
> Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
> ---
>  docs/specs/qcow2.txt | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 96 insertions(+)
> 

> +
> +The first 592 bytes of the header clusters will contain the LUKS
> +partition header. This is then followed by the key material data areas.
> +The size of the key material data areas is determined by the number of
> +stripes in the key slot and key size. Refer to the LUKS format
> +specification ('docs/on-disk-format.pdf' in the cryptsetup source
> +package) for details of the LUKS partition header format.
> +
> +In the LUKS partition header, the "payload-offset" field will be
> +calculated as normal for the LUKS spec. ie the size of the LUKS
> +header, plus key material regions, plus padding, relative to the
> +start of the LUKS header. Its value is never used in the context
> +of qcow2, however, since the qcow2 file format itself defines where
> +the real payload offset is.

Is it possible/valid for the LUKS payload-offset field to NOT be
qcow2-cluster-aligned?  (I'm guessing yes, for example, if we have 2M
clusters; and that we don't care, because you documented that we don't
actually use that offset).  Is it worth documenting this?

> +== Data encryption ==
> +
> +When an encryption method is requested in the header, the image payload
> +data must be encrypted/decrypted on every write/read. The image headers
> +and metadata is never encrypted.

s/is/are/

> +
> +The algorithms used for encryption vary depending on the method
> +
> + - AES:
> +
> +   The AES cipher, in CBC mode, with 256 bit keys.
> +
> +   Initialization vectors generated using plain64 method, with
> +   the virtual disk sector as the input tweak.

Worth documenting that implementations should avoid creating new images
with this encryption (ie. make it officially part of the spec that this
is not recommended, but merely documented for back-compat data
liberation purposes)?

Reviewed-by: Eric Blake <eblake@redhat.com>

On Thu, May 25, 2017 at 02:39:56PM -0500, Eric Blake wrote:
> On 05/25/2017 11:38 AM, Daniel P. Berrange wrote:
> > Update the qcow2 specification to describe how the LUKS header is
> > placed inside a qcow2 file, when using LUKS encryption for the
> > qcow2 payload instead of the legacy AES-CBC encryption
> > 
> > Reviewed-by: Alberto Garcia <berto@igalia.com>
> > Reviewed-by: Max Reitz <mreitz@redhat.com>
> > Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
> > ---
> >  docs/specs/qcow2.txt | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 96 insertions(+)
> > 
> 
> > +
> > +The first 592 bytes of the header clusters will contain the LUKS
> > +partition header. This is then followed by the key material data areas.
> > +The size of the key material data areas is determined by the number of
> > +stripes in the key slot and key size. Refer to the LUKS format
> > +specification ('docs/on-disk-format.pdf' in the cryptsetup source
> > +package) for details of the LUKS partition header format.
> > +
> > +In the LUKS partition header, the "payload-offset" field will be
> > +calculated as normal for the LUKS spec. ie the size of the LUKS
> > +header, plus key material regions, plus padding, relative to the
> > +start of the LUKS header. Its value is never used in the context
> > +of qcow2, however, since the qcow2 file format itself defines where
> > +the real payload offset is.
> 
> Is it possible/valid for the LUKS payload-offset field to NOT be
> qcow2-cluster-aligned?  (I'm guessing yes, for example, if we have 2M
> clusters; and that we don't care, because you documented that we don't
> actually use that offset).  Is it worth documenting this?

Yeah, it is not required to be cluster aligned, and that doesn't
matter because we don't use it in context of qcow2.

Essentially the only time it would be used if is we had some
optimized way in future to convert from qcow2 w/ luks over to
file w/ luks, without having to decrypt+reencrypt the payload.
ie we could just copy out the entire luks header as-is, and
then copy out the qcow2 payload after it.

> > +== Data encryption ==
> > +
> > +When an encryption method is requested in the header, the image payload
> > +data must be encrypted/decrypted on every write/read. The image headers
> > +and metadata is never encrypted.
> 
> s/is/are/
> 
> > +
> > +The algorithms used for encryption vary depending on the method
> > +
> > + - AES:
> > +
> > +   The AES cipher, in CBC mode, with 256 bit keys.
> > +
> > +   Initialization vectors generated using plain64 method, with
> > +   the virtual disk sector as the input tweak.
> 
> Worth documenting that implementations should avoid creating new images
> with this encryption (ie. make it officially part of the spec that this
> is not recommended, but merely documented for back-compat data
> liberation purposes)?

I guess I could document that here too - I did add such a note to
the qemu-doc.texi at the end of this series.

> 
> Reviewed-by: Eric Blake <eblake@redhat.com>


Regards,
Daniel