g13/keyblob.h

   1 /* keyblob.h - Defs to describe a keyblob
   2  * Copyright (C) 2009 Free Software Foundation, Inc.
   3  *
   4  * This file is part of GnuPG.
   5  *
   6  * GnuPG is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * GnuPG is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, see <https://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef G13_KEYBLOB_H
  21 #define G13_KEYBLOB_H
  22
  23 /* The setup area (header block) is the actual core of G13.  Here is
  24    the format:
  25
  26    u8   Packet type.  Value is 61 (0x3d).
  27    u8   Constant value 255 (0xff).
  28    u32  Length of the following structure
  29           b10  Value: "GnuPG/G13\x00".
  30           u8   Version.  Value is 1.
  31           u8   reserved
  32           u8   reserved
  33           u8   OS Flag:  0 = unspecified, 1 = Linux
  34           u32  Length of the entire header.  This includes all bytes
  35                starting at the packet type and ending with the last
  36                padding byte of the header.
  37           u8   Number of copies of this header (1..255).
  38           u8   Number of copies of this header at the end of the
  39                container (usually 0).
  40           b6   reserved
  41    n bytes: OpenPGP encrypted and optionally signed keyblob.
  42    n bytes: CMS encrypted and optionally signed keyblob.  Such a CMS
  43             packet will be enclosed in a private flagged OpenPGP
  44             packet.  Either the OpenPGP encrypted packet as described
  45             above, the CMS encrypted or both packets must exist.  The
  46             encapsulation packet has this structure:
  47                 u8   Packet type.  Value is 61 (0x3d).
  48                 u8   Constant value 255 (0xff).
  49                 u32  Length of the following structure
  50                 b10  Value: "GnuPG/CMS\x00".
  51                 b(n) Regular CMS structure.
  52    n bytes: Padding. The structure resembles an OpenPGP packet.
  53                 u8   Packet type.  Value is 61 (0x3d).
  54                 u8   Constant value 255 (0xff).
  55                 u32  Length of the following structure
  56                 b10  Value: "GnuPG/PAD\x00".
  57                 b(n) Padding stuff.
  58                      (repeat the above value
  59                       or if the remaining N < 10, all 0x00).
  60             Given this structure the minimum padding is 16 bytes.
  61
  62    n bytes: File system container.
  63    (optionally followed by copies on the header).
  64 */
  65
  66 \f
  67 #define KEYBLOB_TAG_BLOBVERSION 0
  68 /* This tag is used to describe the version of the keyblob.  It must
  69    be the first tag in a keyblob and may only occur once.  Its value
  70    is a single byte giving the blob version.  The only defined version
  71    is 1.  */
  72
  73 #define KEYBLOB_TAG_CONTTYPE 1
  74 /* This tag gives the type of the container.  The value is a two byte
  75    big endian integer giving the type of the container as described by
  76    the CONTTYPE_ constants.  */
  77
  78 #define KEYBLOB_TAG_DETACHED 2
  79 /* Indicates that the actual storage is not in the same file as the
  80    keyblob.  If a value is given it is expected to be the GUID of the
  81    partition.  */
  82
  83 #define KEYBLOB_TAG_CREATED  3
  84 /* This is an ISO 8601 time string with the date the container was
  85    created.  */
  86
  87 #define KEYBLOB_TAG_CONT_NSEC 7
  88 /* Number of 512-byte sectors of the entire container including all
  89    copies of the setup area.  */
  90
  91 #define KEYBLOB_TAG_ENC_NSEC  8
  92 #define KEYBLOB_TAG_ENC_OFF   9
  93 /* Number of 512-byte sectors used for the encrypted data and its
  94    start offset in 512-byte sectors from the begin of the container.
  95    Note that these information can also be deduced from the
  96    unencrypted part of the setup area.  */
  97
  98 #define KEYBLOB_TAG_ALGOSTR 10
  99 /* For a dm-crypt container this is the used algorithm string.  For
 100    example: "aes-cbc-essiv:sha256".  */
 101
 102 #define KEYBLOB_TAG_KEYNO  16
 103 /* This tag indicates a new key.  The value is a 4 byte big endian
 104    integer giving the key number.  If the container type does only
 105    need one key this key number should be 0.  */
 106
 107 #define KEYBLOB_TAG_ENCALGO  17
 108 /* Describes the algorithm of the key.  It must follow a KEYNO tag.
 109    The value is a 2 byte big endian algorithm number.  The algorithm
 110    numbers used are those from Libgcrypt (e.g. AES 128 is described by
 111    the value 7).  This tag is optional.  */
 112
 113 #define KEYBLOB_TAG_ENCKEY  18
 114 /* This tag gives the actual encryption key.  It must follow a KEYNO
 115    tag.  The value is the plain key.  */
 116
 117 #define KEYBLOB_TAG_MACALGO  19
 118 /* Describes the MAC algorithm.  It must follow a KEYNO tag.  The
 119    value is a 2 byte big endian algorithm number describing the MAC
 120    algorithm with a value of 1 indicating HMAC.  It is followed by
 121    data specific to the MAC algorithm.  In case of HMAC this data is a
 122    2 byte big endian integer with the Libgcrypt algorithm id of the
 123    hash algorithm.  */
 124
 125 #define KEYBLOB_TAG_MACKEY  20
 126 /* This tag gives the actual MACing key.  It must follow a KEYNO tag.
 127    The value is the key used for MACing.  */
 128
 129
 130 #define KEYBLOB_TAG_HDRCOPY 21
 131 /* The value of this tag is a copy of the setup area prefix header
 132    block (packet 61 with marker "GnuPG/G13\x00".  We use it to allow
 133    signing of that cleartext data.  */
 134
 135 #define KEYBLOB_TAG_FILLER   0xffff
 136 /* This tag may be used for alignment and padding purposes.  The value
 137    has no meaning.  */
 138
 139
 140 \f
 141 #define CONTTYPE_ENCFS      1
 142 /* A EncFS based backend.  This requires a whole directory which
 143    includes the encrypted files.  Metadata is not encrypted.  */
 144
 145 #define CONTTYPE_DM_CRYPT   2
 146 /* A DM-Crypt based backend.  */
 147
 148
 149 #define CONTTYPE_TRUECRYPT  21571
 150 /* A Truecrypt (www.truecrypt.org) based container.  Due to the design
 151    of truecrypt this requires a second datafile because it is not
 152    possible to prepend a truecrypt container with our keyblob.  */
 153
 154
 155 \f
 156 /*-- keyblob.c --*/
 157 gpg_error_t g13_is_container (ctrl_t ctrl, const char *filename);
 158 gpg_error_t g13_keyblob_read (const char *filename,
 159                               void **r_enckeyblob, size_t *r_enckeybloblen);
 160
 161
 162 #endif /*G13_KEYBLOB_H*/