1   /*
    2    * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   /*
   26    * $Id: PGPData.java,v 1.4 2005/05/10 16:35:35 mullan Exp $
   27    */
   28   package javax.xml.crypto.dsig.keyinfo;
   29   
   30   import java.util.Collections;
   31   import java.util.List;
   32   import javax.xml.crypto.XMLStructure;
   33   
   34   /**
   35    * A representation of the XML <code>PGPData</code> element as defined in
   36    * the <a href="http://www.w3.org/TR/xmldsig-core/">
   37    * W3C Recommendation for XML-Signature Syntax and Processing</a>. A
   38    * <code>PGPData</code> object is used to convey information related to
   39    * PGP public key pairs and signatures on such keys. The XML Schema Definition
   40    * is defined as:
   41    *
   42    * <pre>
   43    *    &lt;element name="PGPData" type="ds:PGPDataType"/&gt;
   44    *    &lt;complexType name="PGPDataType"&gt;
   45    *      &lt;choice&gt;
   46    *        &lt;sequence&gt;
   47    *          &lt;element name="PGPKeyID" type="base64Binary"/&gt;
   48    *          &lt;element name="PGPKeyPacket" type="base64Binary" minOccurs="0"/&gt;
   49    *          &lt;any namespace="##other" processContents="lax" minOccurs="0"
   50    *           maxOccurs="unbounded"/&gt;
   51    *        &lt;/sequence&gt;
   52    *        &lt;sequence&gt;
   53    *          &lt;element name="PGPKeyPacket" type="base64Binary"/&gt;
   54    *          &lt;any namespace="##other" processContents="lax" minOccurs="0"
   55    *           maxOccurs="unbounded"/&gt;
   56    *        &lt;/sequence&gt;
   57    *      &lt;/choice&gt;
   58    *    &lt;/complexType&gt;
   59    * </pre>
   60    *
   61    * A <code>PGPData</code> instance may be created by invoking one of the
   62    * {@link KeyInfoFactory#newPGPData newPGPData} methods of the {@link
   63    * KeyInfoFactory} class, and passing it
   64    * <code>byte</code> arrays representing the contents of the PGP public key
   65    * identifier and/or PGP key material packet, and an optional list of
   66    * elements from an external namespace.
   67    *
   68    * @author Sean Mullan
   69    * @author JSR 105 Expert Group
   70    * @since 1.6
   71    * @see KeyInfoFactory#newPGPData(byte[])
   72    * @see KeyInfoFactory#newPGPData(byte[], byte[], List)
   73    * @see KeyInfoFactory#newPGPData(byte[], List)
   74    */
   75   public interface PGPData extends XMLStructure {
   76   
   77       /**
   78        * URI identifying the PGPData KeyInfo type:
   79        * http://www.w3.org/2000/09/xmldsig#PGPData. This can be specified as the
   80        * value of the <code>type</code> parameter of the {@link RetrievalMethod}
   81        * class to describe a remote <code>PGPData</code> structure.
   82        */
   83       final static String TYPE = "http://www.w3.org/2000/09/xmldsig#PGPData";
   84   
   85       /**
   86        * Returns the PGP public key identifier of this <code>PGPData</code> as
   87        * defined in <a href="http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>,
   88        * section 11.2.
   89        *
   90        * @return the PGP public key identifier (may be <code>null</code> if
   91        *    not specified). Each invocation of this method returns a new clone
   92        *    to protect against subsequent modification.
   93        */
   94       byte[] getKeyId();
   95   
   96       /**
   97        * Returns the PGP key material packet of this <code>PGPData</code> as
   98        * defined in <a href="http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>,
   99        * section 5.5.
  100        *
  101        * @return the PGP key material packet (may be <code>null</code> if not
  102        *    specified). Each invocation of this method returns a new clone to
  103        *    protect against subsequent modification.
  104        */
  105       byte[] getKeyPacket();
  106   
  107       /**
  108        * Returns an {@link Collections#unmodifiableList unmodifiable list}
  109        * of {@link XMLStructure}s representing elements from an external
  110        * namespace.
  111        *
  112        * @return an unmodifiable list of <code>XMLStructure</code>s (may be
  113        *    empty, but never <code>null</code>)
  114        */
  115       List getExternalElements();
  116   }