001: /*
002: * @(#)X509Extension.java 1.23 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security.cert;
029:
030: import java.util.Set;
031:
032: /**
033: * Interface for an X.509 extension.
034: *
035: * <p>The extensions defined for X.509 v3
036: * {@link X509Certificate Certificates} and v2
037: * {@link X509CRL CRLs} (Certificate Revocation
038: * Lists) provide methods
039: * for associating additional attributes with users or public keys,
040: * for managing the certification hierarchy, and for managing CRL
041: * distribution. The X.509 extensions format also allows communities
042: * to define private extensions to carry information unique to those
043: * communities.
044: *
045: * <p>Each extension in a certificate/CRL may be designated as
046: * critical or non-critical. A certificate/CRL-using system (an application
047: * validating a certificate/CRL) must reject the certificate/CRL if it
048: * encounters a critical extension it does not recognize. A non-critical
049: * extension may be ignored if it is not recognized.
050: * <p>
051: * The ASN.1 definition for this is:
052: * <pre>
053: * Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
054: *
055: * Extension ::= SEQUENCE {
056: * extnId OBJECT IDENTIFIER,
057: * critical BOOLEAN DEFAULT FALSE,
058: * extnValue OCTET STRING
059: * -- contains a DER encoding of a value
060: * -- of the type registered for use with
061: * -- the extnId object identifier value
062: * }
063: * </pre>
064: * Since not all extensions are known, the <code>getExtensionValue</code>
065: * method returns the DER-encoded OCTET STRING of the
066: * extension value (i.e., the <code>extnValue</code>). This can then
067: * be handled by a <em>Class</em> that understands the extension.
068: *
069: * @author Hemma Prafullchandra
070: * @version 1.16 00/02/02
071: */
072:
073: public interface X509Extension {
074:
075: /**
076: * Check if there is a critical extension that is not supported.
077: *
078: * @return <tt>true</tt> if a critical extension is found that is
079: * not supported, otherwise <tt>false</tt>.
080: */
081: public boolean hasUnsupportedCriticalExtension();
082:
083: /**
084: * Gets a Set of the OID strings for the extension(s) marked
085: * CRITICAL in the certificate/CRL managed by the object
086: * implementing this interface.
087: *
088: * Here is sample code to get a Set of critical extensions from an
089: * X509Certificate and print the OIDs:
090: * <pre><code>
091: * InputStream inStrm = new FileInputStream("DER-encoded-Cert");
092: * CertificateFactory cf = CertificateFactory.getInstance("X.509");
093: * X509Certificate cert = (X509Certificate)cf.generateCertificate(inStrm);
094: * inStrm.close();<p>
095: *
096: * Set critSet = cert.getCriticalExtensionOIDs();
097: * if (critSet != null && !critSet.isEmpty()) {
098: * System.out.println("Set of critical extensions:");
099: * for (Iterator i = critSet.iterator(); i.hasNext();) {
100: * String oid = (String)i.next();
101: * System.out.println(oid);
102: * }
103: * }
104: * </code></pre>
105: * @return a Set (or an empty Set if none are marked critical) of
106: * the extension OID strings for extensions that are marked critical.
107: * If there are no extensions present at all, then this method returns
108: * null.
109: */
110: public Set getCriticalExtensionOIDs();
111:
112: /**
113: * Gets a Set of the OID strings for the extension(s) marked
114: * NON-CRITICAL in the certificate/CRL managed by the object
115: * implementing this interface.
116: *
117: * Here is sample code to get a Set of non-critical extensions from an
118: * X509CRL revoked certificate entry and print the OIDs:
119: * <pre><code>
120: * InputStream inStrm = new FileInputStream("DER-encoded-CRL");
121: * CertificateFactory cf = CertificateFactory.getInstance("X.509");
122: * X509CRL crl = (X509CRL)cf.generateCRL(inStrm);
123: * inStrm.close();<p>
124: *
125: * byte[] certData = <DER-encoded certificate data>
126: * ByteArrayInputStream bais = new ByteArrayInputStream(certData);
127: * X509Certificate cert = (X509Certificate)cf.generateCertificate(bais);
128: * bais.close();
129: * X509CRLEntry badCert =
130: * crl.getRevokedCertificate(cert.getSerialNumber());<p>
131: *
132: * if (badCert != null) {
133: * Set nonCritSet = badCert.getNonCriticalExtensionOIDs();<p>
134: * if (nonCritSet != null)
135: * for (Iterator i = nonCritSet.iterator(); i.hasNext();) {
136: * String oid = (String)i.next();
137: * System.out.println(oid);
138: * }
139: * }
140: * </code></pre>
141: *
142: * @return a Set (or an empty Set if none are marked non-critical) of
143: * the extension OID strings for extensions that are marked non-critical.
144: * If there are no extensions present at all, then this method returns
145: * null.
146: */
147: public Set getNonCriticalExtensionOIDs();
148:
149: /**
150: * Gets the DER-encoded OCTET string for the extension value
151: * (<em>extnValue</em>) identified by the passed-in <code>oid</code>
152: * String.
153: * The <code>oid</code> string is
154: * represented by a set of nonnegative whole numbers separated
155: * by periods.
156: *
157: * <p>For example:<br>
158: * <table border=groove summary="Examples of OIDs and extension names">
159: * <tr>
160: * <th>OID <em>(Object Identifier)</em></th>
161: * <th>Extension Name</th></tr>
162: * <tr><td>2.5.29.14</td>
163: * <td>SubjectKeyIdentifier</td></tr>
164: * <tr><td>2.5.29.15</td>
165: * <td>KeyUsage</td></tr>
166: * <tr><td>2.5.29.16</td>
167: * <td>PrivateKeyUsage</td></tr>
168: * <tr><td>2.5.29.17</td>
169: * <td>SubjectAlternativeName</td></tr>
170: * <tr><td>2.5.29.18</td>
171: * <td>IssuerAlternativeName</td></tr>
172: * <tr><td>2.5.29.19</td>
173: * <td>BasicConstraints</td></tr>
174: * <tr><td>2.5.29.30</td>
175: * <td>NameConstraints</td></tr>
176: * <tr><td>2.5.29.33</td>
177: * <td>PolicyMappings</td></tr>
178: * <tr><td>2.5.29.35</td>
179: * <td>AuthorityKeyIdentifier</td></tr>
180: * <tr><td>2.5.29.36</td>
181: * <td>PolicyConstraints</td></tr>
182: * </table>
183: *
184: * @param oid the Object Identifier value for the extension.
185: * @return the DER-encoded octet string of the extension value or
186: * null if it is not present.
187: */
188: public byte[] getExtensionValue(String oid);
189: }
|