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 }