1 /*
   2  * reserved comment block
   3  * DO NOT REMOVE OR ALTER!
   4  */
   5 /*
   6  * Copyright  2003-2004 The Apache Software Foundation.
   7  *
   8  *  Licensed under the Apache License, Version 2.0 (the "License");
   9  *  you may not use this file except in compliance with the License.
  10  *  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *  Unless required by applicable law or agreed to in writing, software
  15  *  distributed under the License is distributed on an "AS IS" BASIS,
  16  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  *  See the License for the specific language governing permissions and
  18  *  limitations under the License.
  19  *
  20  */
  21 package com.sun.org.apache.xml.internal.security.encryption;
  22 
  23 
  24 import java.util.Iterator;
  25 import com.sun.org.apache.xml.internal.security.keys.KeyInfo;
  26 import org.w3c.dom.Element;
  27 
  28 
  29 /**
  30  * A Key Agreement algorithm provides for the derivation of a shared secret key
  31  * based on a shared secret computed from certain types of compatible public
  32  * keys from both the sender and the recipient. Information from the originator
  33  * to determine the secret is indicated by an optional OriginatorKeyInfo
  34  * parameter child of an <code>AgreementMethod</code> element while that
  35  * associated with the recipient is indicated by an optional RecipientKeyInfo. A
  36  * shared key is derived from this shared secret by a method determined by the
  37  * Key Agreement algorithm.
  38  * <p>
  39  * <b>Note:</b> XML Encryption does not provide an on-line key agreement
  40  * negotiation protocol. The <code>AgreementMethod</code> element can be used by
  41  * the originator to identify the keys and computational procedure that were
  42  * used to obtain a shared encryption key. The method used to obtain or select
  43  * the keys or algorithm used for the agreement computation is beyond the scope
  44  * of this specification.
  45  * <p>
  46  * The <code>AgreementMethod</code> element appears as the content of a
  47  * <code>ds:KeyInfo</code> since, like other <code>ds:KeyInfo</code> children,
  48  * it yields a key. This <code>ds:KeyInfo</code> is in turn a child of an
  49  * <code>EncryptedData</code> or <code>EncryptedKey</code> element. The
  50  * Algorithm attribute and KeySize child of the <code>EncryptionMethod</code>
  51  * element under this <code>EncryptedData</code> or <code>EncryptedKey</code>
  52  * element are implicit parameters to the key agreement computation. In cases
  53  * where this <code>EncryptionMethod</code> algorithm <code>URI</code> is
  54  * insufficient to determine the key length, a KeySize MUST have been included.
  55  * In addition, the sender may place a KA-Nonce element under
  56  * <code>AgreementMethod</code> to assure that different keying material is
  57  * generated even for repeated agreements using the same sender and recipient
  58  * public keys.
  59  * <p>
  60  * If the agreed key is being used to wrap a key, then
  61  * <code>AgreementMethod</code> would appear inside a <code>ds:KeyInfo</code>
  62  * inside an <code>EncryptedKey</code> element.
  63  * <p>
  64  * The Schema for AgreementMethod is as follows:
  65  * <xmp>
  66  * <element name="AgreementMethod" type="xenc:AgreementMethodType"/>
  67  * <complexType name="AgreementMethodType" mixed="true">
  68  *     <sequence>
  69  *         <element name="KA-Nonce" minOccurs="0" type="base64Binary"/>
  70  *         <!-- <element ref="ds:DigestMethod" minOccurs="0"/> -->
  71  *         <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
  72  *         <element name="OriginatorKeyInfo" minOccurs="0" type="ds:KeyInfoType"/>
  73  *         <element name="RecipientKeyInfo" minOccurs="0" type="ds:KeyInfoType"/>
  74  *     </sequence>
  75  *     <attribute name="Algorithm" type="anyURI" use="required"/>
  76  * </complexType>
  77  * </xmp>
  78  *
  79  * @author Axl Mattheus
  80  */
  81 public interface AgreementMethod {
  82     /**
  83      * Returns an <code>byte</code> array.
  84      * @return
  85      */
  86     byte[] getKANonce();
  87 
  88     /**
  89      * Sets the KANonce.jj
  90      * @param kanonce
  91      */
  92     void setKANonce(byte[] kanonce);
  93 
  94     /**
  95      * Returns aditional information regarding the <code>AgreementMethod</code>.
  96      * @return
  97      */
  98     Iterator<Element> getAgreementMethodInformation();
  99 
 100     /**
 101      * Adds additional <code>AgreementMethod</code> information.
 102      *
 103      * @param info a <code>Element</code> that represents additional information
 104      * specified by
 105      *   <xmp>
 106      *     <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
 107      *   </xmp>
 108      */
 109     void addAgreementMethodInformation(Element info);
 110 
 111     /**
 112      * Removes additional <code>AgreementMethod</code> information.
 113      *
 114      * @param info a <code>Element</code> that represents additional information
 115      * specified by
 116      *   <xmp>
 117      *     <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
 118      *   </xmp>
 119      */
 120     void revoveAgreementMethodInformation(Element info);
 121 
 122     /**
 123      * Returns information relating to the originator's shared secret.
 124      *
 125      * @return information relating to the originator's shared secret.
 126      */
 127     KeyInfo getOriginatorKeyInfo();
 128 
 129     /**
 130      * Sets the information relating to the originator's shared secret.
 131      *
 132      * @param keyInfo information relating to the originator's shared secret.
 133      */
 134     void setOriginatorKeyInfo(KeyInfo keyInfo);
 135 
 136     /**
 137      * Retruns information relating to the recipient's shared secret.
 138      *
 139      * @return information relating to the recipient's shared secret.
 140      */
 141     KeyInfo getRecipientKeyInfo();
 142 
 143     /**
 144      * Sets the information relating to the recipient's shared secret.
 145      *
 146      * @param keyInfo information relating to the recipient's shared secret.
 147      */
 148     void setRecipientKeyInfo(KeyInfo keyInfo);
 149 
 150     /**
 151      * Returns the algorithm URI of this <code>CryptographicMethod</code>.
 152      *
 153      * @return the algorithm URI of this <code>CryptographicMethod</code>
 154      */
 155     String getAlgorithm();
 156 }