1/*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5/**
6 * Licensed to the Apache Software Foundation (ASF) under one
7 * or more contributor license agreements. See the NOTICE file
8 * distributed with this work for additional information
9 * regarding copyright ownership. The ASF licenses this file
10 * to you under the Apache License, Version 2.0 (the
11 * "License"); you may not use this file except in compliance
12 * with the License. You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing,
17 * software distributed under the License is distributed on an
18 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19 * KIND, either express or implied. See the License for the
20 * specific language governing permissions and limitations
21 * under the License.
22 */
23package com.sun.org.apache.xml.internal.security.encryption;
24
25import java.util.Iterator;
26import com.sun.org.apache.xml.internal.security.keys.KeyInfo;
27import org.w3c.dom.Element;
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} 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} 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} element appears as the content of a
47 * {@code ds:KeyInfo} since, like other {@code ds:KeyInfo} children,
48 * it yields a key. This {@code ds:KeyInfo} is in turn a child of an
49 * {@code EncryptedData} or {@code EncryptedKey} element. The
50 * Algorithm attribute and KeySize child of the {@code EncryptionMethod}
51 * element under this {@code EncryptedData} or {@code EncryptedKey}
52 * element are implicit parameters to the key agreement computation. In cases
53 * where this {@code EncryptionMethod} algorithm {@code URI} 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} 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} would appear inside a {@code ds:KeyInfo}
62 * inside an {@code EncryptedKey} element.
63 * <p>
64 * The Schema for AgreementMethod is as follows:
65 * <pre>{@code
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 * }</pre>
78 *
79 * @author Axl Mattheus
80 */
81public interface AgreementMethod {
82
83    /**
84     * Returns a {@code byte} array.
85     * @return a {@code byte} array.
86     */
87    byte[] getKANonce();
88
89    /**
90     * Sets the KANonce.jj
91     * @param kanonce
92     */
93    void setKANonce(byte[] kanonce);
94
95    /**
96     * Returns additional information regarding the {@code AgreementMethod}.
97     * @return additional information regarding the {@code AgreementMethod}.
98     */
99    Iterator<Element> getAgreementMethodInformation();
100
101    /**
102     * Adds additional {@code AgreementMethod} information.
103     *
104     * @param info an {@code Element} that represents additional information
105     * specified by
106     *   <pre>{@code
107     *     <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
108     *   }</pre>
109     */
110    void addAgreementMethodInformation(Element info);
111
112    /**
113     * Removes additional {@code AgreementMethod} information.
114     *
115     * @param info an {@code Element} that represents additional information
116     * specified by
117     *   <pre>{@code
118     *     <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
119     *   }</pre>
120     */
121    void revoveAgreementMethodInformation(Element info);
122
123    /**
124     * Returns information relating to the originator's shared secret.
125     *
126     * @return information relating to the originator's shared secret.
127     */
128    KeyInfo getOriginatorKeyInfo();
129
130    /**
131     * Sets the information relating to the originator's shared secret.
132     *
133     * @param keyInfo information relating to the originator's shared secret.
134     */
135    void setOriginatorKeyInfo(KeyInfo keyInfo);
136
137    /**
138     * Returns information relating to the recipient's shared secret.
139     *
140     * @return information relating to the recipient's shared secret.
141     */
142    KeyInfo getRecipientKeyInfo();
143
144    /**
145     * Sets the information relating to the recipient's shared secret.
146     *
147     * @param keyInfo information relating to the recipient's shared secret.
148     */
149    void setRecipientKeyInfo(KeyInfo keyInfo);
150
151    /**
152     * Returns the algorithm URI of this {@code CryptographicMethod}.
153     *
154     * @return the algorithm URI of this {@code CryptographicMethod}
155     */
156    String getAlgorithm();
157}
158