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 }