KDBX.4.xsd

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Copyright 2015 Jo Rabin
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~     http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<!--suppress XmlDefaultAttributeValue -->
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:annotation>
        <xs:documentation>This is an attempt to document the KDBX 3.1 and 4 XML formats as used by
            KeePass 2.x compatible programs.

            Conventions in this schema:

            KeePassFile, Group, Entry, Times and History are top level elements as they may be useful for
            creating fragments or something.

            There are types for almost everything that contains documentation as to its purpose
            and how it's used and if there are restrictions on the values.

            Everything else is simply included inline for the sake of brevity. Undoubtedly
            more documentation could most usefully be added.

            Many elements are probably optional but are not marked as such. In real life they are serialised
            as empty elements and some are serialised with content "null". You have been warned.
        </xs:documentation>
    </xs:annotation>

    <!--==++ ELEMENTS ++==-->

    <xs:element name="KeePassFile">
        <xs:annotation>
            <xs:documentation>The root element. doh.</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Meta">
                    <xs:complexType>
                        <xs:annotation>
                            <xs:documentation>This contains database settings and also contains information
                                about the last state of the program that used the database. Presumably assuming
                                that the same program will be used to open it again, or that a different program
                                would want/need the same settings.
                            </xs:documentation>
                        </xs:annotation>
                        <xs:sequence>
                            <xs:element name="Generator" type="xs:string"/>
                            <xs:element name="HeaderHash" type="xs:base64Binary" minOccurs="0">
                                <xs:annotation>
                                    <xs:documentation>Header hash removed from version 4. Hashes now contained
                                    in the kdbx header itself.
                                    </xs:documentation>
                                </xs:annotation>
                            </xs:element>
                            <xs:element name="DatabaseName" type="xs:string"/>
                            <xs:element name="DatabaseNameChanged" type="keepassDateTime"/>
                            <xs:element name="DatabaseDescription" type="xs:string"/>
                            <xs:element name="DatabaseDescriptionChanged" type="keepassDateTime"/>
                            <xs:element name="DefaultUserName" type="xs:string"/>
                            <xs:element name="DefaultUserNameChanged" type="keepassDateTime"/>
                            <xs:element name="MaintenanceHistoryDays" type="xs:int"/>
                            <xs:element name="Color" type="color"/>
                            <xs:element name="MasterKeyChanged" type="keepassDateTime"/>
                            <xs:element name="MasterKeyChangeRec" type="changeDays"/>
                            <xs:element name="MasterKeyChangeForce" type="changeDays"/>
                            <xs:element name="MemoryProtection">
                                <xs:annotation>
                                    <xs:documentation>When the XML database is loaded into memory, sensitive
                                        fields will be encrypted in that stream. This element specifies which of the
                                        standardFields are encrypted in that stream, which is decrypted using Salsa20
                                        for KDBX3 (or ChaCha20 by default for V4) and the InnerRandomStream encryption header.

                                        ./Entry/String/Value/@Protected signifies that the value of a stringField is
                                        so encrypted and applies also to customFields.

                                        Attachments are optionally memory protected in V4.
                                    </xs:documentation>
                                </xs:annotation>
                                <xs:complexType>
                                    <xs:sequence>
                                        <xs:element name="ProtectTitle" type="keepassBoolean"/>
                                        <xs:element name="ProtectUserName" type="keepassBoolean"/>
                                        <xs:element name="ProtectPassword" type="keepassBoolean"/>
                                        <xs:element name="ProtectURL" type="keepassBoolean"/>
                                        <xs:element name="ProtectNotes" type="keepassBoolean"/>
                                    </xs:sequence>
                                </xs:complexType>
                            </xs:element>
                            <xs:element name="CustomIcons" type="customIcons"/>
                            <xs:element name="RecycleBinEnabled" type="keepassBoolean"/>
                            <xs:element name="RecycleBinUUID" type="uuidRef"/>
                            <xs:element name="RecycleBinChanged" type="keepassDateTime"/>
                            <xs:element name="EntryTemplatesGroup" type="uuidRef"/>
                            <xs:element name="EntryTemplatesGroupChanged" type="keepassDateTime"/>
                            <xs:element name="LastSelectedGroup" type="uuidRef"/>
                            <xs:element name="LastTopVisibleGroup" type="uuidRef"/>
                            <xs:element name="HistoryMaxItems" type="xs:int"/>
                            <xs:element name="HistoryMaxSize" type="xs:int"/>
                            <xs:element name="Binaries" type="binaries" minOccurs="0">
                                <xs:annotation>
                                    <xs:documentation>Used to store binary values in version 3.1 - in version 4
                                        such values are now transferred as part of the KDBX inner headers.
                                    </xs:documentation>
                                </xs:annotation>
                            </xs:element>
                            <xs:element name="CustomData" type="customData"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>

                <xs:element name="Root">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element ref="Group">
                                <xs:annotation>
                                    <xs:documentation>This is the root group which contains everything.
                                    </xs:documentation>
                                </xs:annotation>
                            </xs:element>
                            <xs:element name="DeletedObjects">
                                <xs:annotation>
                                    <xs:documentation>When the user permanently deletes an wrappedEntry or a group,
                                        an item is created in this node. This allows the synchronization function
                                        to decide whether an object has been deleted or is just missing in one of
                                        the databases that are being synchronized.
                                    </xs:documentation>
                                </xs:annotation>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>

            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:complexType name="Parented" abstract="true">
        <xs:annotation>
            <xs:documentation>A parent type for Entry and Group that allows us to
                insert a superclass holding a link to a parent group during automatic
                class generation.
            </xs:documentation>
        </xs:annotation>
    </xs:complexType>

    <xs:element name="Group">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="Parented">
                    <xs:sequence>
                        <xs:element name="UUID" type="uuid"/>
                        <xs:element name="Name" type="xs:string"/>
                        <xs:element name="Notes" type="xs:string"/>
                        <xs:element name="IconID" type="iconId"/>
                        <xs:element name="CustomIconUUID" type="customIconUuidRef" minOccurs="0"/>
                        <xs:element ref="Times"/>
                        <!-- not sure what the flwg are for -->
                        <xs:element name="IsExpanded" type="keepassBoolean"/>
                        <xs:element name="DefaultAutoTypeSequence" type="xs:string"/>
                        <xs:element name="EnableAutoType" type="keepassBoolean"/>
                        <xs:element name="EnableSearching" type="keepassBoolean"/>
                        <xs:element name="LastTopVisibleEntry" type="uuidRef"/>
                        <!-- a load of entries then a load of groups -->
                        <xs:element ref="Entry" minOccurs="0" maxOccurs="unbounded"/>
                        <xs:element ref="Group" minOccurs="0" maxOccurs="unbounded"/>
                        <!-- in v4 only -->
                        <xs:element name="CustomData" type="customData" minOccurs="0"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>

    <xs:element name="Entry">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="Parented">
                    <xs:sequence>
                        <xs:element name="UUID" type="uuid"/>
                        <xs:element name="IconID" type="iconId"/>
                        <xs:element name="CustomIconUUID" type="customIconUuidRef" minOccurs="0"/>
                        <xs:element name="ForegroundColor" type="color"/>
                        <xs:element name="BackgroundColor" type="color"/>
                        <xs:element name="OverrideURL" type="overrideUrl"/>
                        <xs:element name="Tags" type="commaSeparatedList"/>
                        <xs:element ref="Times"/>
                        <xs:element name="String" type="stringField" maxOccurs="unbounded" minOccurs="0"/>
                        <xs:element name="Binary" type="binaryField" maxOccurs="unbounded" minOccurs="0"/>
                        <xs:element name="AutoType" type="autoType"/>
                        <xs:element ref="History" minOccurs="0"/>
                        <!-- in v4 only -->
                        <xs:element name="CustomData" type="customData" minOccurs="0"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>

    <xs:element name="Times">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="LastModificationTime" type="keepassDateTime">
                    <xs:annotation>
                        <xs:documentation>When it was last updated, resulting in an update to History if that is
                            active.
                        </xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="CreationTime" type="keepassDateTime">
                    <xs:annotation>
                        <xs:documentation>When it was originally created.</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="LastAccessTime" type="keepassDateTime">
                    <xs:annotation>
                        <xs:documentation>When was last used (read).</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="ExpiryTime" type="keepassDateTime">
                    <xs:annotation>
                        <xs:documentation>When it expires if it expires.</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="Expires" type="keepassBoolean">
                    <xs:annotation>
                        <xs:documentation>True if it expires.</xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="UsageCount" type="xs:int">
                    <xs:annotation>
                        <xs:documentation>How often the object has been used (e.g. by copying data of it to the
                            clipboard, performing auto-type with it, etc.). However, a change to the usage count is
                            not considered to be a database change (i.e. the database is not marked as changed by the
                            UI), thus this value is typically incorrect (and the same applies to the last access
                            time).
                        </xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="LocationChanged" type="keepassDateTime">
                    <xs:annotation>
                        <xs:documentation>The date/time when the object was last moved. This allows the
                            synchronization function to correctly determine the most recent location of the
                            object.
                        </xs:documentation>
                    </xs:annotation>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="History">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="Entry"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <!--==++ TYPES ++==-->

    <xs:simpleType name="keepassBoolean">
        <xs:restriction>
            <xs:simpleType>
                <xs:union memberTypes="keepassFalse keepassTrue"/>
            </xs:simpleType>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="keepassFalse">
        <xs:restriction base="xs:string">
            <xs:enumeration value="0"/>
            <xs:enumeration value="No"/>
            <xs:enumeration value="false"/>
            <xs:enumeration value="False"/>
            <xs:enumeration value="null"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="keepassTrue">
        <xs:restriction base="xs:string">
            <xs:enumeration value="1"/>
            <xs:enumeration value="Yes"/>
            <xs:enumeration value="true"/>
            <xs:enumeration value="True"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="keepassDateTime">
        <xs:annotation>
            <xs:documentation>This is ISO Date time stored as UTC (Z time zone). Left
                to its own devices JAXB will make a XMLGregorianCalendar for these fields
                which we don't want.

                In KDBX Version 4 this becomes a base64 encoded offset in seconds
                from 0001-01-01T00:00:00Z.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:dateTime"/>
    </xs:simpleType>

    <xs:simpleType name="commaSeparatedList">
        <xs:annotation>
            <xs:documentation>XSD doesn't do comma separated lists, so we can't model this handily.

                Assume that the format is something like [{token}{, token}*]+ where white space is ignored except
                as part of the name of the token.
            </xs:documentation>
        </xs:annotation>

        <xs:restriction base="xs:string"/>
    </xs:simpleType>

    <xs:complexType name="ValueExtender" abstract="true">
        <xs:annotation>
            <xs:documentation>Abstract parent for StringField/Value so that
                to allow creation of a custom mapping that contains extra
                non-serialised (transient) fields.
            </xs:documentation>
        </xs:annotation>
        <xs:simpleContent>
            <xs:extension base="xs:string"/>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="stringField">
        <xs:annotation>
            <xs:documentation>This is where the values of the database are actually stored. You can have String valued
                fields, and you can have Binary valued fields. There are "Default" String fields (username and so on) and
                there are custom string fields (custom only in that their names are not the names of default string
                fields). Not really clear whether the keys are case-sensitive.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="Key" type="xs:string"/>
            <xs:element name="Value">
                <xs:complexType>
                    <xs:simpleContent>
                        <xs:extension base="ValueExtender">
                            <xs:attribute type="keepassBoolean" name="Protected" default="False"/>
                            <xs:attribute type="keepassBoolean" name="ProtectInMemory" default="False"/>
                        </xs:extension>
                    </xs:simpleContent>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="binaryField">
        <xs:annotation>
            <xs:documentation>If derived from a file then the Key element conventionally contains the file name.
                I think it would be useful to add a mime type on this ...

                The Value element is the value of /./meta/binaries/binary/@ID that is referenced from this
                binary.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="Key" type="xs:string"/>
            <xs:element name="Value">
                <xs:complexType>
                    <xs:attribute type="xs:int" name="Ref"/>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <!-- IconId -->

    <xs:simpleType name="iconId">
        <xs:annotation>
            <xs:documentation>An index to one of the 69 built in icons.</xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:int">
            <xs:minInclusive value="0"/>
            <xs:maxInclusive value="68"/>
        </xs:restriction>
    </xs:simpleType>

    <!-- Color -->

    <xs:simpleType name="color">
        <xs:annotation>
            <xs:documentation>Simply put: "#rrggbb".</xs:documentation>
        </xs:annotation>
        <xs:union>
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:enumeration value="#"/>
                </xs:restriction>
            </xs:simpleType>

            <xs:simpleType>
                <xs:restriction base="xs:hexBinary">
                    <xs:length value="6"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:union>
    </xs:simpleType>

    <!-- Custom Icons -->

    <xs:complexType name="customIcons">
        <xs:sequence maxOccurs="unbounded">
            <xs:element name="Icon">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="UUID" type="uuid"/>
                        <xs:element name="Name" type="xs:string"/>
                        <xs:element name="LastModificationTime" type="keepassDateTime" />
                        <xs:element name="Data" type="xs:base64Binary"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <!-- OverrideUrl -->

    <xs:simpleType name="overrideUrl">
        <xs:annotation>
            <xs:documentation>Specifies the override URL, as documented at
                http://keepass.info/help/base/autourl.html#override
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string"/>
    </xs:simpleType>

    <!-- auto type -->

    <xs:complexType name="autoType">
        <xs:annotation>
            <xs:documentation>Stores everything related to auto-type for this wrappedEntry.
                http://keepass.info/help/base/autotype.html
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="Enabled" type="keepassBoolean"/>
            <xs:element name="DataTransferObfuscation">
                <xs:annotation>
                    <xs:documentation>1 if Two-Channel Auto-Type Obfuscation is enabled, otherwise 0.
                        http://keepass.info/help/v2/autotype_obfuscation.html
                    </xs:documentation>
                </xs:annotation>
                <xs:simpleType>
                    <xs:restriction base="xs:int">
                        <xs:enumeration value="0"/>
                        <xs:enumeration value="1"/>
                    </xs:restriction>
                </xs:simpleType>
            </xs:element>
            <xs:element name="DefaultSequence" type="xs:string"/>
            <xs:element name="Association">
                <xs:annotation>
                    <xs:documentation>Custom window/sequence association</xs:documentation>
                </xs:annotation>
                <xs:complexType>
                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
                        <xs:element name="Window" type="xs:string"/>
                        <xs:element name="KeystrokeSequence" type="xs:string"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <!-- Change Days -->

    <xs:simpleType name="changeDays">
        <xs:annotation>
            <xs:documentation>Number of days before triggering an event e.g. suggesting a password change.
                -1 means never. 0 means every time.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:int">
            <xs:minInclusive value="-1"/>
        </xs:restriction>
    </xs:simpleType>

    <!-- UUIDs -->

    <xs:simpleType name="uuid">
        <xs:annotation>
            <xs:documentation>A base64 encoded UUID. Each Group and Entry has a UUID. When added to History the same
                UUID is maintained.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:base64Binary"/>
    </xs:simpleType>

    <xs:simpleType name="uuidRef">
        <xs:annotation>
            <xs:documentation>A reference to the UUID e.g. a Group like the Recycle bin. If, for
                example, the recycle bin is enabled but has not been used, then it won't have been
                created and the value stored here is a 0 UUID.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="uuid"/>
    </xs:simpleType>

    <xs:simpleType name="customIconUuidRef">
        <xs:annotation>
            <xs:documentation>A reference to the custom icon UUID found in the meta/customIcons list.</xs:documentation>
        </xs:annotation>
        <xs:restriction base="uuid"/>
    </xs:simpleType>

    <!--- Binaries -->

    <xs:complexType name="binaries">
        <xs:annotation>
            <xs:documentation>Binary field for elements are centrally stored in this element.
                The same Binary element may be referenced from many Entries.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <xs:element name="Binary">
                <xs:annotation>
                    <xs:documentation>The ID attribute is referenced in the Ref attribute of
                        a corresponding Binary element of an Entry. The Compressed attribute specifies
                        whether the base64 encoded value is to be decompressed to recover the binary
                        data.
                    </xs:documentation>
                </xs:annotation>
                <xs:complexType>
                    <xs:simpleContent>
                        <xs:extension base="xs:base64Binary">
                            <xs:attribute name="ID" type="xs:int"/>
                            <xs:attribute name="Compressed" type="keepassBoolean" default="False"/>
                        </xs:extension>
                    </xs:simpleContent>
                </xs:complexType>
            </xs:element>

        </xs:sequence>
    </xs:complexType>

    <!--- Custom Data -->

    <xs:complexType name="customData">
        <xs:annotation>
            <xs:documentation>Third party programs and plugins can put custom data here.
                Unique element names should be used, e.g. "PluginName_ItemName".
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:any minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>