hunt.security.Certificate source code

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