View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, 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  package java.security;
27  
28  import java.io.*;
29  import java.util.Date;
30  
31  /**
32   * <p>This is an interface of abstract methods for managing a
33   * variety of identity certificates.
34   * An identity certificate is a guarantee by a principal that
35   * a public key is that of another principal.  (A principal represents
36   * an entity such as an individual user, a group, or a corporation.)
37   *
38   * <p>In particular, this interface is intended to be a common
39   * abstraction for constructs that have different formats but
40   * important common uses.  For example, different types of
41   * certificates, such as X.509 certificates and PGP certificates,
42   * share general certificate functionality (the need to encode and
43   * decode certificates) and some types of information, such as a
44   * public key, the principal whose key it is, and the guarantor
45   * guaranteeing that the public key is that of the specified
46   * principal. So an implementation of X.509 certificates and an
47   * implementation of PGP certificates can both utilize the Certificate
48   * interface, even though their formats and additional types and
49   * amounts of information stored are different.
50   *
51   * <p><b>Important</b>: This interface is useful for cataloging and
52   * grouping objects sharing certain common uses. It does not have any
53   * semantics of its own. In particular, a Certificate object does not
54   * make any statement as to the <i>validity</i> of the binding. It is
55   * the duty of the application implementing this interface to verify
56   * the certificate and satisfy itself of its validity.
57   *
58   * @author Benjamin Renaud
59   * @deprecated A new certificate handling package is created in the Java platform.
60   *             This Certificate interface is entirely deprecated and
61   *             is here to allow for a smooth transition to the new
62   *             package.
63   * @see java.security.cert.Certificate
64   */
65  @Deprecated
66  public interface Certificate {
67  
68      /**
69       * Returns the guarantor of the certificate, that is, the principal
70       * guaranteeing that the public key associated with this certificate
71       * is that of the principal associated with this certificate. For X.509
72       * certificates, the guarantor will typically be a Certificate Authority
73       * (such as the United States Postal Service or Verisign, Inc.).
74       *
75       * @return the guarantor which guaranteed the principal-key
76       * binding.
77       */
78      public abstract Principal getGuarantor();
79  
80      /**
81       * Returns the principal of the principal-key pair being guaranteed by
82       * the guarantor.
83       *
84       * @return the principal to which this certificate is bound.
85       */
86      public abstract Principal getPrincipal();
87  
88      /**
89       * Returns the key of the principal-key pair being guaranteed by
90       * the guarantor.
91       *
92       * @return the public key that this certificate certifies belongs
93       * to a particular principal.
94       */
95      public abstract PublicKey getPublicKey();
96  
97      /**
98       * Encodes the certificate to an output stream in a format that can
99       * be decoded by the {@code decode} method.
100      *
101      * @param stream the output stream to which to encode the
102      * certificate.
103      *
104      * @exception KeyException if the certificate is not
105      * properly initialized, or data is missing, etc.
106      *
107      * @exception IOException if a stream exception occurs while
108      * trying to output the encoded certificate to the output stream.
109      *
110      * @see #decode
111      * @see #getFormat
112      */
113     public abstract void encode(OutputStream stream)
114         throws KeyException, IOException;
115 
116     /**
117      * Decodes a certificate from an input stream. The format should be
118      * that returned by {@code getFormat} and produced by
119      * {@code encode}.
120      *
121      * @param stream the input stream from which to fetch the data
122      * being decoded.
123      *
124      * @exception KeyException if the certificate is not properly initialized,
125      * or data is missing, etc.
126      *
127      * @exception IOException if an exception occurs while trying to input
128      * the encoded certificate from the input stream.
129      *
130      * @see #encode
131      * @see #getFormat
132      */
133     public abstract void decode(InputStream stream)
134         throws KeyException, IOException;
135 
136 
137     /**
138      * Returns the name of the coding format. This is used as a hint to find
139      * an appropriate parser. It could be "X.509", "PGP", etc. This is
140      * the format produced and understood by the {@code encode}
141      * and {@code decode} methods.
142      *
143      * @return the name of the coding format.
144      */
145     public abstract String getFormat();
146 
147     /**
148      * Returns a string that represents the contents of the certificate.
149      *
150      * @param detailed whether or not to give detailed information
151      * about the certificate
152      *
153      * @return a string representing the contents of the certificate
154      */
155     public String toString(boolean detailed);
156 }