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 }