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 25 /** 26 * The <code>EncryptedKey</code> element is used to transport encryption keys 27 * from the originator to a known recipient(s). It may be used as a stand-alone 28 * XML document, be placed within an application document, or appear inside an 29 * <code>EncryptedData</code> element as a child of a <code>ds:KeyInfo</code> 30 * element. The key value is always encrypted to the recipient(s). When 31 * <code>EncryptedKey</code> is decrypted the resulting octets are made 32 * available to the <code>EncryptionMethod</code> algorithm without any 33 * additional processing. 34 * <p> 35 * Its schema definition is as follows: 36 * <xmp> 37 * <element name='EncryptedKey' type='xenc:EncryptedKeyType'/> 38 * <complexType name='EncryptedKeyType'> 39 * <complexContent> 40 * <extension base='xenc:EncryptedType'> 41 * <sequence> 42 * <element ref='xenc:ReferenceList' minOccurs='0'/> 43 * <element name='CarriedKeyName' type='string' minOccurs='0'/> 44 * </sequence> 45 * <attribute name='Recipient' type='string' use='optional'/> 46 * </extension> 47 * </complexContent> 48 * </complexType> 49 * </xmp> 50 * 51 * @author Axl Mattheus 52 */ 53 public interface EncryptedKey extends EncryptedType { 54 /** 55 * Returns a hint as to which recipient this encrypted key value is intended 56 * for. 57 * 58 * @return the recipient of the <code>EncryptedKey</code>. 59 */ 60 String getRecipient(); 61 62 /** 63 * Sets the recipient for this <code>EncryptedKey</code>. 64 * 65 * @param recipient the recipient for this <code>EncryptedKey</code>. 66 */ 67 void setRecipient(String recipient); 68 69 /** 70 * Returns pointers to data and keys encrypted using this key. The reference 71 * list may contain multiple references to <code>EncryptedKey</code> and 72 * <code>EncryptedData</code> elements. This is done using 73 * <code>KeyReference</code> and <code>DataReference</code> elements 74 * respectively. 75 * 76 * @return an <code>Iterator</code> over all the <code>ReferenceList</code>s 77 * contained in this <code>EncryptedKey</code>. 78 */ 79 ReferenceList getReferenceList(); 80 81 /** 82 * Sets the <code>ReferenceList</code> to the <code>EncryptedKey</code>. 83 * 84 * @param list a list of pointers to data elements encrypted using this key. 85 */ 86 void setReferenceList(ReferenceList list); 87 88 /** 89 * Returns a user readable name with the key value. This may then be used to 90 * reference the key using the <code>ds:KeyName</code> element within 91 * <code>ds:KeyInfo</code>. The same <code>CarriedKeyName</code> label, 92 * unlike an ID type, may occur multiple times within a single document. The 93 * value of the key is to be the same in all <code>EncryptedKey</code> 94 * elements identified with the same <code>CarriedKeyName</code> label 95 * within a single XML document. 96 * <br> 97 * <b>Note</b> that because whitespace is significant in the value of 98 * the <code>ds:KeyName</code> element, whitespace is also significant in 99 * the value of the <code>CarriedKeyName</code> element. 100 * 101 * @return over all the carried names contained in 102 * this <code>EncryptedKey</code>. 103 */ 104 String getCarriedName(); 105 106 /** 107 * Sets the carried name. 108 * 109 * @param name the carried name. 110 */ 111 void setCarriedName(String name); 112 }