EncryptedKey.java revision 12623:bd9629077386 
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 */
23package 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 */
53public 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
114