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