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 */
23 package com.sun.org.apache.xml.internal.security.encryption;
24
25 import java.util.Iterator;
26 import com.sun.org.apache.xml.internal.security.keys.KeyInfo;
27 import 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</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 /**
84 * Returns a <code>byte</code> array.
85 * @return a <code>byte</code> 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</code>.
97 * @return additional information regarding the <code>AgreementMethod</code>.
98 */
99 Iterator<Element> getAgreementMethodInformation();
100
101 /**
102 * Adds additional <code>AgreementMethod</code> information.
103 *
104 * @param info a <code>Element</code> that represents additional information
105 * specified by
106 * <xmp>
107 * <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
108 * </xmp>
109 */
110 void addAgreementMethodInformation(Element info);
111
112 /**
113 * Removes additional <code>AgreementMethod</code> information.
114 *
115 * @param info a <code>Element</code> that represents additional information
116 * specified by
117 * <xmp>
118 * <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
119 * </xmp>
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</code>.
153 *
154 * @return the algorithm URI of this <code>CryptographicMethod</code>
155 */
156 String getAlgorithm();
157 }