1 /*
2  * Copyright (c) 1997, 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.cert;
27 
28 import java.util.Set;
29 
30 /**
31  * Interface for an X.509 extension.
32  *
33  * <p>The extensions defined for X.509 v3
34  * {@link X509Certificate Certificates} and v2
35  * {@link X509CRL CRLs} (Certificate Revocation
36  * Lists) provide methods
37  * for associating additional attributes with users or public keys,
38  * for managing the certification hierarchy, and for managing CRL
39  * distribution. The X.509 extensions format also allows communities
40  * to define private extensions to carry information unique to those
41  * communities.
42  *
43  * <p>Each extension in a certificate/CRL may be designated as
44  * critical or non-critical.  A certificate/CRL-using system (an application
45  * validating a certificate/CRL) must reject the certificate/CRL if it
46  * encounters a critical extension it does not recognize.  A non-critical
47  * extension may be ignored if it is not recognized.
48  * <p>
49  * The ASN.1 definition for this is:
50  * <pre>
51  * Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
52  *
53  * Extension  ::=  SEQUENCE  {
54  *     extnId        OBJECT IDENTIFIER,
55  *     critical      BOOLEAN DEFAULT FALSE,
56  *     extnValue     OCTET STRING
57  *                   -- contains a DER encoding of a value
58  *                   -- of the type registered for use with
59  *                   -- the extnId object identifier value
60  * }
61  * </pre>
62  * Since not all extensions are known, the {@code getExtensionValue}
63  * method returns the DER-encoded OCTET STRING of the
64  * extension value (i.e., the {@code extnValue}). This can then
65  * be handled by a <em>Class</em> that understands the extension.
66  *
67  * @author Hemma Prafullchandra
68  */
69 
70 public interface X509Extension {
71 
72     /**
73      * Check if there is a critical extension that is not supported.
74      *
75      * @return {@code true} if a critical extension is found that is
76      * not supported, otherwise {@code false}.
77      */
hasUnsupportedCriticalExtension()78     public boolean hasUnsupportedCriticalExtension();
79 
80     /**
81      * Gets a Set of the OID strings for the extension(s) marked
82      * CRITICAL in the certificate/CRL managed by the object
83      * implementing this interface.
84      *
85      * Here is sample code to get a Set of critical extensions from an
86      * X509Certificate and print the OIDs:
87      * <pre>{@code
88      * X509Certificate cert = null;
89      * try (InputStream inStrm = new FileInputStream("DER-encoded-Cert")) {
90      *     CertificateFactory cf = CertificateFactory.getInstance("X.509");
91      *     cert = (X509Certificate)cf.generateCertificate(inStrm);
92      * }
93      *
94      * Set<String> critSet = cert.getCriticalExtensionOIDs();
95      * if (critSet != null && !critSet.isEmpty()) {
96      *     System.out.println("Set of critical extensions:");
97      *     for (String oid : critSet) {
98      *         System.out.println(oid);
99      *     }
100      * }
101      * }</pre>
102      * @return a Set (or an empty Set if none are marked critical) of
103      * the extension OID strings for extensions that are marked critical.
104      * If there are no extensions present at all, then this method returns
105      * null.
106      */
getCriticalExtensionOIDs()107     public Set<String> getCriticalExtensionOIDs();
108 
109     /**
110      * Gets a Set of the OID strings for the extension(s) marked
111      * NON-CRITICAL in the certificate/CRL managed by the object
112      * implementing this interface.
113      *
114      * Here is sample code to get a Set of non-critical extensions from an
115      * X509CRL revoked certificate entry and print the OIDs:
116      * <pre>{@code
117      * CertificateFactory cf = null;
118      * X509CRL crl = null;
119      * try (InputStream inStrm = new FileInputStream("DER-encoded-CRL")) {
120      *     cf = CertificateFactory.getInstance("X.509");
121      *     crl = (X509CRL)cf.generateCRL(inStrm);
122      * }
123      *
124      * byte[] certData = <DER-encoded certificate data>
125      * ByteArrayInputStream bais = new ByteArrayInputStream(certData);
126      * X509Certificate cert = (X509Certificate)cf.generateCertificate(bais);
127      * X509CRLEntry badCert =
128      *              crl.getRevokedCertificate(cert.getSerialNumber());
129      *
130      * if (badCert != null) {
131      *     Set<String> nonCritSet = badCert.getNonCriticalExtensionOIDs();
132      *     if (nonCritSet != null)
133      *         for (String oid : nonCritSet) {
134      *             System.out.println(oid);
135      *         }
136      * }
137      * }</pre>
138      *
139      * @return a Set (or an empty Set if none are marked non-critical) of
140      * the extension OID strings for extensions that are marked non-critical.
141      * If there are no extensions present at all, then this method returns
142      * null.
143      */
getNonCriticalExtensionOIDs()144     public Set<String> getNonCriticalExtensionOIDs();
145 
146     /**
147      * Gets the DER-encoded OCTET string for the extension value
148      * (<em>extnValue</em>) identified by the passed-in {@code oid}
149      * String.
150      * The {@code oid} string is
151      * represented by a set of nonnegative whole numbers separated
152      * by periods.
153      *
154      * <p>For example:<br>
155      * <table border=groove summary="Examples of OIDs and extension names">
156      * <tr>
157      * <th>OID <em>(Object Identifier)</em></th>
158      * <th>Extension Name</th></tr>
159      * <tr><td>2.5.29.14</td>
160      * <td>SubjectKeyIdentifier</td></tr>
161      * <tr><td>2.5.29.15</td>
162      * <td>KeyUsage</td></tr>
163      * <tr><td>2.5.29.16</td>
164      * <td>PrivateKeyUsage</td></tr>
165      * <tr><td>2.5.29.17</td>
166      * <td>SubjectAlternativeName</td></tr>
167      * <tr><td>2.5.29.18</td>
168      * <td>IssuerAlternativeName</td></tr>
169      * <tr><td>2.5.29.19</td>
170      * <td>BasicConstraints</td></tr>
171      * <tr><td>2.5.29.30</td>
172      * <td>NameConstraints</td></tr>
173      * <tr><td>2.5.29.33</td>
174      * <td>PolicyMappings</td></tr>
175      * <tr><td>2.5.29.35</td>
176      * <td>AuthorityKeyIdentifier</td></tr>
177      * <tr><td>2.5.29.36</td>
178      * <td>PolicyConstraints</td></tr>
179      * </table>
180      *
181      * @param oid the Object Identifier value for the extension.
182      * @return the DER-encoded octet string of the extension value or
183      * null if it is not present.
184      */
getExtensionValue(String oid)185     public byte[] getExtensionValue(String oid);
186 }
187