gecko/services/crypto/component/nsISyncJPAKE.idl

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (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.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Firefox Sync.
 *
 * The Initial Developer of the Original Code is
 * the Mozilla Foundation.
 * Portions created by the Initial Developer are Copyright (C) 2010
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 * Brian Smith <bsmith@mozilla.com>
 * Philipp von Weitershausen <philipp@weitershausen.de>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

[scriptable, uuid(5ab02a98-5122-4b90-93cd-f259c4b42e3a)]
interface nsISyncJPAKE : nsISupports
{
  /**
   * Perform first round of the JPAKE exchange.
   *
   * @param aSignerID
   *        String identifying the signer.
   * @param aGX1
   *        Schnorr signature value g^x1, in hex representation.
   * @param aGV1
   *        Schnorr signature value g^v1 (v1 is a random value), in hex
   *        representation.
   * @param aR1
   *        Schnorr signature value r1 = v1 - x1 * h, in hex representation.
   * @param aGX2
   *        Schnorr signature value g^x2, in hex representation.
   * @param aGV2
   *        Schnorr signature value g^v2 (v2 is a random value), in hex
   *        representation.
   * @param aR2
   *        Schnorr signature value r2 = v2 - x2 * h, in hex representation.
   */
  void round1(in ACString aSignerID,
              out ACString aGX1,
              out ACString aGV1,
              out ACString aR1,
              out ACString aGX2,
              out ACString aGV2,
              out ACString aR2);

  /**
   * Perform second round of the JPAKE exchange.
   *
   * @param aPeerID
   *        String identifying the peer.
   * @param aPIN
   *        String containing the weak secret (PIN).
   * @param aGX3
   *        Schnorr signature value g^x3, in hex representation.
   * @param aGV3
   *        Schnorr signature value g^v3 (v3 is a random value), in hex
   *        representation.
   * @param aR3
   *        Schnorr signature value r3 = v3 - x3 * h, in hex representation.
   * @param aGX4
   *        Schnorr signature value g^x4, in hex representation.
   * @param aGV4
   *        Schnorr signature value g^v4 (v4 is a random value), in hex
   *        representation.
   * @param aR4
   *        Schnorr signature value r4 = v4 - x4 * h, in hex representation.
   * @param aA
   *        Schnorr signature value A, in hex representation.
   * @param aGVA
   *        Schnorr signature value g^va (va is a random value), in hex
   *        representation.
   * @param aRA
   *        Schnorr signature value ra = va - xa * h, in hex representation.
   */
  void round2(in ACString aPeerID,
              in ACString aPIN,
              in ACString aGX3,
              in ACString aGV3,
              in ACString aR3,
              in ACString aGX4,
              in ACString aGV4,
              in ACString aR4,
              out ACString aA,
              out ACString aGVA,
              out ACString aRA);

  /**
   * Perform the final step of the JPAKE exchange. This will compute
   * the key and expand the key to two keys, an AES256 encryption key
   * and a 256 bit HMAC key. It returns a key confirmation value
   * (SHA256d of the key) and the encryption and HMAC keys.
   *
   * @param aB
   *        Schnorr signature value B, in hex representation.
   * @param aGVB
   *        Schnorr signature value g^vb (vb is a random value), in hex
   *        representation.
   * @param aRB
   *        Schnorr signature value rb = vb - xb * h, in hex representation.
   * @param aAES256Key
   *        The AES 256 encryption key, in base64 representation.
   * @param aHMAC256Key
   *        The 256 bit HMAC key, in base64 representation.
   */
  void final(in ACString aB,
             in ACString aGVB,
             in ACString aRB,
             in ACString aHkdfInfo,
             out ACString aAES256Key,
             out ACString aHMAC256Key);
};