javax.xml.crypto.dsig.keyinfo.KeyInfo Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* Copyright 2005 Sun Microsystems, Inc. All rights reserved.
*/
/*
* $Id$
*/
package javax.xml.crypto.dsig.keyinfo;
import java.util.List;
import javax.xml.crypto.MarshalException;
import javax.xml.crypto.XMLCryptoContext;
import javax.xml.crypto.XMLStructure;
/**
* A representation of the XML KeyInfo element as defined in
* the
* W3C Recommendation for XML-Signature Syntax and Processing.
* A KeyInfo contains a list of {@link XMLStructure}s, each of
* which contain information that enables the recipient(s) to obtain the key
* needed to validate an XML signature. The XML Schema Definition is defined as:
*
*
* <element name="KeyInfo" type="ds:KeyInfoType"/>
* <complexType name="KeyInfoType" mixed="true">
* <choice maxOccurs="unbounded">
* <element ref="ds:KeyName"/>
* <element ref="ds:KeyValue"/>
* <element ref="ds:RetrievalMethod"/>
* <element ref="ds:X509Data"/>
* <element ref="ds:PGPData"/>
* <element ref="ds:SPKIData"/>
* <element ref="ds:MgmtData"/>
* <any processContents="lax" namespace="##other"/>
* <!-- (1,1) elements from (0,unbounded) namespaces -->
* </choice>
* <attribute name="Id" type="ID" use="optional"/>
* </complexType>
*
*
* A KeyInfo instance may be created by invoking one of the
* {@link KeyInfoFactory#newKeyInfo newKeyInfo} methods of the
* {@link KeyInfoFactory} class, and passing it a list of one or more
* XMLStructures and an optional id parameter;
* for example:
*
* KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
* KeyInfo keyInfo = factory.newKeyInfo
* (Collections.singletonList(factory.newKeyName("Alice"), "keyinfo-1"));
*
*
* KeyInfo objects can also be marshalled to XML by invoking
* the {@link #marshal marshal} method.
*
* @author Sean Mullan
* @author JSR 105 Expert Group
* @see KeyInfoFactory#newKeyInfo(List)
* @see KeyInfoFactory#newKeyInfo(List, String)
*/
public interface KeyInfo extends XMLStructure {
/**
* Returns an {@link java.util.Collections#unmodifiableList unmodifiable
* list} containing the key information. Each entry of the list is
* an {@link XMLStructure}.
*
*
If there is a public subclass representing the type of
* XMLStructure, it is returned as an instance of that
* class (ex: an X509Data element would be returned as an
* instance of {@link javax.xml.crypto.dsig.keyinfo.X509Data}).
*
* @return an unmodifiable list of one or more XMLStructures
* in this KeyInfo. Never returns null or an
* empty list.
*/
List getContent();
/**
* Return the optional Id attribute of this KeyInfo, which
* may be useful for referencing this KeyInfo from other
* XML structures.
*
* @return the Id attribute of this KeyInfo (may be
* null if not specified)
*/
String getId();
/**
* Marshals the key info to XML.
*
* @param parent a mechanism-specific structure containing the parent node
* that the marshalled key info will be appended to
* @param context the XMLCryptoContext containing additional
* context (may be null if not applicable)
* @throws ClassCastException if the type of parent or
* context is not compatible with this key info
* @throws MarshalException if the key info cannot be marshalled
* @throws NullPointerException if parent is null
*/
void marshal(XMLStructure parent, XMLCryptoContext context)
throws MarshalException;
}