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