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 /**

    26  * The {@code EncryptedKey} 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} element as a child of a {@code ds:KeyInfo}

    30  * element. The key value is always encrypted to the recipient(s). When

    31  * {@code EncryptedKey} is decrypted the resulting octets are made

    32  * available to the {@code EncryptionMethod} algorithm without any

    33  * additional processing.

    34  * <p>

    35  * Its schema definition is as follows:

    36  * <pre>{@code

    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  * }</pre>

    50  *

    51  * @author Axl Mattheus

    52  */

    53 public interface EncryptedKey extends EncryptedType {

    54 

    55     /**

    56      * Returns a hint as to which recipient this encrypted key value is intended for.

    57      *

    58      * @return the recipient of the {@code EncryptedKey}.

    59      */

    60     String getRecipient();

    61 

    62     /**

    63      * Sets the recipient for this {@code EncryptedKey}.

    64      *

    65      * @param recipient the recipient for this {@code EncryptedKey}.

    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} and

    72      * {@code EncryptedData} elements. This is done using

    73      * {@code KeyReference} and {@code DataReference} elements

    74      * respectively.

    75      *

    76      * @return an {@code Iterator} over all the {@code ReferenceList}s

    77      *   contained in this {@code EncryptedKey}.

    78      */

    79     ReferenceList getReferenceList();

    80 

    81     /**

    82      * Sets the {@code ReferenceList} to the {@code EncryptedKey}.

    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} element within

    91      * {@code ds:KeyInfo}. The same {@code CarriedKeyName} 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}

    94      * elements identified with the same {@code CarriedKeyName} 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} element, whitespace is also significant in

    99      * the value of the {@code CarriedKeyName} element.

   100      *

   101      * @return over all the carried names contained in

   102      *   this {@code EncryptedKey}.

   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 }

   113