XEP-xxxx: Public Key and Signature Exchange and Verification

Abstract:This specification provide means to make key trust management easier for the end user by specifying techniques to publish signatures and public keys as well as a way to negotiate and compare key fingerprints.
Author:Fabian Beutel
Copyright:© 1999 - 2016 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:ProtoXEP
Type:Standards Track
Version:0.0.1
Last Updated:2016-04-14

WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Table of Contents


1. Introduction
    1.1. Example scenarios
2. Requirements
3. Glossary
4. Use Cases
    4.1. Publishing a key
    4.2. Publishing a signature
    4.3. Limiting Signature Lifetimes
    4.4. Revoking a key
    4.5. Verifying each others keys
       4.5.1. Fingerprint mechanisms
5. Business Rules
6. Implementation Notes
7. Security Considerations
8. IANA Considerations
9. XMPP Registrar Considerations
10. XML Schema

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

When using end to end encryption, users have to verify each other's keys before an authenticated connection can be established. Because this process is cumbersome, especially for average users, it should be kept to a minimum.

For example, when a contact adds a new device which uses a new key (e.g. because another key can't be safely transferred because it is on a smartcard that is incompatible with the new device), all contacts would have to re-verify the new key individually before they can start communicating with the user's new device. By providing a mechanism to cross-sign other keys one can eliminate the need of additional verification process: the user can sign the new key with the old key and publish the signature, so that contacts trusting the old key can safely trust the new key as well.

This specification provides a protocol-agnostic (with respect to the actual protocol used for the end-to-end encryption) method of publishing key signatures and verifying new keys.

1.1 Example scenarios

There are several example scenarios that illustrate use cases of this sepcification:

2. Requirements

3. Glossary

Key ID
A unique id of a given key. Some protocols, such as PGP, already offer unique key IDs which can be used. Otherwise, the only requirement for key ids is to keep them unique in the context of one user (there MUST not be two keys with the same id published on the same node).
Key Type
The type of a key. This specifies the technology that was used to create the key and that can be used to use the key. Types defined by this specification are:
  • "pgp" (a key as used by the OpenPGP protocols [...] and [...])
  • "omemo" (a key as used by the OMEMO protocol)
  • "x509" (a x.509 certificate)

Todo: Specify exactly how the key and signature data for each type should look like, e.g. ASCII-Armored or not...

Other types can be defined by later revisions of this specification or by additional XEPs.

4. Use Cases

4.1 Publishing a key

When a new key is generated (e.g. at client install time), it can be made available by publishing an <item/> element with the key id as 'id' attribute and containing one <key> element to the node "urn:xmpp:ksev:0:keymetadata".

The <key> element MUST have a 'type' attribute (see Glossary) and MAY contain one or more <signed> elements. A <signed> element indicates that the key has been signed by another key, which MUST be specified using the 'keyid' attribute.

Example 1. Publishing public key metadata

<iq from='juliet@capulet.lit' type='set' id='publish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:keymetadata'>
      <item id='keyid'>
        <key xmlns='urn:xmpp:ksev:0:keymetadata' type='pgp'>
          <signed sigid='' />
        </key>
      </item>
    </publish>
  </pubsub>
</iq>

Optionally, the <key> element MAY contain an <url> element which points to an external resource where the public key data can be found. If no such url is included, the key must be published to the user's PEP service as described in the following example.

The client publishes the acutal public key data by publishing an <item/> to the "urn:xmpp:ksev:0:data" node. The <item/> element MUST contain one <pubkey/> element containing the BASE64 encoded key data.

Example 2. Publishing a public key

<iq from='juliet@capulet.lit' type='set' id='publish2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:data'>
      <item id='keyid'>
        <pubkey xmlns='urn:xmpp:ksev:0:data'>
        ...BASE64 encoded public key...
        </pubkey>
      </item>
    </publish>
  </pubsub>
</iq>

4.2 Publishing a signature

A client can publish a signature of a key or other arbitrary data signed by another key.

Publishing a signature happens by publising an <item/> element with the signature id as 'id' attribute and containing one <metadata/> element to the node "urn:xmpp:ksev:0:sigmetadata". The <metadata/> element MUST have a 'keyid' attribute, specifying the id of the key that was used to generate the signature and an optional 'keyowner' attribute that contains the jid of the owner of the key that was used to generate the signature. If the 'keyowner' attribute is omitted, the key has to be one of the keys published by the user himself.

The <metadata/> element MUST have either a

Example 3. Publishing signature metadata

<iq from='juliet@capulet.lit' type='set' id='sigpublish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:sigmetadata'>
      <item id='signature_id'>
        <metadata xmlns='urn:xmpp:ksev:0:sigmetadata'
                  keyid='...id_of_the_signing_key...'
                  keyowner='romeo@juliet@capulet.lit'>
          <url>http://example.com/mydocument</url>
          or
          <key keyid='id_of_the_signed_key' keyowner='romeo@example.com'/>
        </metadata>
      </item>
    </publish>
  </pubsub>
</iq>

The <metadata/> element MAY contain one <sigurl/> element, specifying an external resource where to find the signature data. If it has no such element, the signature data MUST be published to the users "urn:xmpp:ksev:0:sig" node:

Example 4. Publishing signature metadata

<iq from='juliet@capulet.lit' type='set' id='sigpublish2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:sig'>
      <item id='signature_id'>
        <signature xmlns='urn:xmpp:ksev:0:sig'>
          ...BASE64 encoded signature..
        </signature>
      </item>
    </publish>
  </pubsub>
</iq>

4.3 Limiting Signature Lifetimes

In order to increase security, it may make sense to limit the validity of key signatures. For this purpose, the <signature/> element on the "urn:xmpp:ksev:0:sig" node may contain a 'expires' attribute, which contains a DateTime according to XMPP Date and Time Profiles (XEP-0082) [1]. In case such an 'expires' attribute exists and is non-empty, the signed data MUST be prepended with the exact content of the 'expires' attribute before signing the concatenated data and creating the signature.

Another entity can then go through the same process (concatenate datetime + data to verify) and verify the signature on the concatenated data in order to make sure that the signature has not yet expired.

Example 5. Publishing a signature with limited lifetime

<iq from='juliet@capulet.lit' type='set' id='sigpublish3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:sig'>
      <item id='signature_id'>
        <signature xmlns='urn:xmpp:ksev:0:sig' expires='2017-07-21T02:56:15Z'>
          ...BASE64 encoded signature of ['2017-07-21T02:56:15Z' + data]...
        </signature>
      </item>
    </publish>
  </pubsub>
</iq>

For security reasons, entities SHOULD limit key signatures to one year or less.

4.4 Revoking a key

When a key is lost or should not be used anymore, the client can publish an <item/> with the key id as 'id' of the <item/> element to the "urn:xmpp:ksev:0:revoke" node. The <item/> MUST contain one empty <revoked/> child element.

Example 6. Revoking a key

<iq from='juliet@capulet.lit' type='set' id='revoke1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:ksev:0:revoke'>
      <item id='key_id'>
        <revoked xmlns='urn:xmpp:ksev:0:revoke' />
      </item>
    </publish>
  </pubsub>
</iq>

4.5 Verifying each others keys

When two devices want to verify each other's keys, they have to display the same fingerprint on the screen. (The fingerprint can be encoded as QR-Code or similar, if supported, and automatically checked via Camera, but this will not be further discussed). The following section will describe a mechanism, both for two devices (resources) of the same user to verify (and optionally cross-sign) their keys, as well as for two distinct users to verify each other's keys.

To start the key verification process, one client sends a <message> stanza to the target resource. The <message> stanza MUST have one <verify> child element and MUST posess a unique message id.

The <verify> element MUST have one 'hash' attribute specifying the mechanism that will be used to hash the fingerprint (see below). [todo: specify supported hashing algorithms]. It also contains one <key> element for each key that the initiating client has the private key for. The <key> element MUST have an 'id' attribute specifying the key id:

Example 7. Initiating a key verification

<message from='juliet@capulet.lit/orchard'
         to='juliet@capulet.lit/balcony'
         id='verifymsg1'>
  <verify xmlns='urn:xmpp:ksev:0' hash='sha-256'>
    <key id='orchard_key_id' />
    <key id='another_orchard_key_id' />
  </verify>
</message>

If the message is directed to a specific resource, as in this example, the addressed resource can continue and SHOULD respond with a list of key ids that it has the private keys to:

Example 8. Responding to a key verification message

<message from='juliet@capulet.lit/balcony'
         to='juliet@capulet.lit/orchard'
         id='verifymsg2'>
  <verify xmlns='urn:xmpp:ksev:0' initial='verifymsg1'>
    <key id='balconyd_key_id' />
  </verify>
</message>

Immediately after receiving such a response, the initial client then responds with sending a <done> element referencing the id of the original message in the 'initial' attribute and the id of the response message in the 'response' attribute. This concludes the communication between the two clients:

Example 9. Concluding the key verification negotiation

<message from='juliet@capulet.lit/orchard'
         to='juliet@capulet.lit/balcony'
         id='verifymsg3'>
  <done xmlns='urn:xmpp:ksev:0' initial='verifymsg1' response='verifymsg2' />
</message>

At this point, both clients obtain the public key data of all the keys that were mention in the previous verify messages. They then generate a fingerprint by following the following procedure:

If the initial message was sent without specifying a particular receiver resource (e.g. because multiple resources are currently online), receiving resources MUST NOT respond automatically without consulting the user first (e.g. through a dialog window). Only after the user has selected to continue with the key verification process, the client MUST then continue with sending the response.

After successful (or failed) verification, the initiating entity MUST send a <done> element referring to the initial message without specifying a receiver resource, so that other resources (that may also have displayed a dialog window) know that the verification process has taken place between the contact and a different resource. This solves the problem of possible race conditions between devices by passing on responsibility for deciding the race condition to the user.

Note: If both parties, Alice and Bob, start the verification progress at the same time, there are two initiating messages and two response messages. A client SHOULD nevertheless only display the verification process once to avoid confusion (in this case both clients have the information twice, which doesn't do any harm). In this case, the hashing algorithm of the user with the "smaller" Jid wins (see above for details on JID ordering). If the losing client believes that the used hashing algorithm is not secure enough, it MAY start another verification procedure after the current one has been completed.

4.5.1 Fingerprint mechanisms

todo: specify hashing mechanisms. A fingerprint mechanism has to specify the hashing algorithm, the number of times it is applied and the form of the final data that will be displayed to the user (e.g. groups of four characters, separated by ":"). todo: consider Use of Cryptographic Hash Functions in XMPP (XEP-0300) [2]

5. Business Rules

todo

6. Implementation Notes

This specification does not mandate in which cases keys should be considered trusted. It only offers a way to publish signatures and negotiate key fingerprints, but it is up to the client and/or user to decide whether a signature or a chain of signatures is trustworthy.

7. Security Considerations

todo

8. IANA Considerations

todo

9. XMPP Registrar Considerations

todo

10. XML Schema

todo


Appendices


Appendix A: Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2016-04-14
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0163
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
This document in other formats: XML  PDF


Appendix B: Author Information

Fabian Beutel

Email: fabian.beutel@gmx.de
JabberID: fbeutel@jabber.at


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright (c) 1999 - 2014 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Appendix G: Notes

1. XEP-0082: XMPP Date and Time Profiles <http://xmpp.org/extensions/xep-0082.html>.

2. XEP-0300: Use of Cryptographic Hash Functions in XMPP <http://xmpp.org/extensions/xep-0300.html>.


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.0.1 (2016-04-14)

First draft.

(fb)

END