1. /*
  2. * @(#)X509Extension.java 1.16 00/02/02
  3. *
  4. * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.security.cert;
  11. import java.util.Set;
  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.16 00/02/02
  51. */
  52. public interface X509Extension {
  53. /**
  54. * Check if there is a critical extension that is not supported.
  55. *
  56. * @return <tt>true</tt> if a critical extension is found that is
  57. * not supported, otherwise <tt>false</tt>.
  58. */
  59. public boolean hasUnsupportedCriticalExtension();
  60. /**
  61. * Gets a Set of the OID strings for the extension(s) marked
  62. * CRITICAL in the certificate/CRL managed by the object
  63. * implementing this interface.
  64. *
  65. * Here is sample code to get a Set of critical extensions from an
  66. * X509Certificate and print the OIDs:
  67. * <pre><code>
  68. * InputStream inStrm = new FileInputStream("DER-encoded-Cert");
  69. * CertificateFactory cf = CertificateFactory.getInstance("X.509");
  70. * X509Certificate cert = (X509Certificate)cf.generateCertificate(inStrm);
  71. * inStrm.close();<p>
  72. *
  73. * Set critSet = cert.getCriticalExtensionOIDs();
  74. * if (critSet != null && !critSet.isEmpty()) {
  75. * System.out.println("Set of critical extensions:");
  76. * for (Iterator i = critSet.iterator(); i.hasNext();) {
  77. * String oid = (String)i.next();
  78. * System.out.println(oid);
  79. * }
  80. * }
  81. * </code></pre>
  82. * @return a Set (or an empty Set if none are marked critical) of
  83. * the extension OID strings for extensions that are marked critical.
  84. * If there are no extensions present at all, then this method returns
  85. * null.
  86. */
  87. public Set getCriticalExtensionOIDs();
  88. /**
  89. * Gets a Set of the OID strings for the extension(s) marked
  90. * NON-CRITICAL in the certificate/CRL managed by the object
  91. * implementing this interface.
  92. *
  93. * Here is sample code to get a Set of non-critical extensions from an
  94. * X509CRL revoked certificate entry and print the OIDs:
  95. * <pre><code>
  96. * InputStream inStrm = new FileInputStream("DER-encoded-CRL");
  97. * CertificateFactory cf = CertificateFactory.getInstance("X.509");
  98. * X509CRL crl = (X509CRL)cf.generateCRL(inStrm);
  99. * inStrm.close();<p>
  100. *
  101. * byte[] certData = <DER-encoded certificate data>
  102. * ByteArrayInputStream bais = new ByteArrayInputStream(certData);
  103. * X509Certificate cert = (X509Certificate)cf.generateCertificate(bais);
  104. * bais.close();
  105. * X509CRLEntry badCert =
  106. * crl.getRevokedCertificate(cert.getSerialNumber());<p>
  107. *
  108. * if (badCert != null) {
  109. * Set nonCritSet = badCert.getNonCriticalExtensionOIDs();<p>
  110. * if (nonCritSet != null)
  111. * for (Iterator i = nonCritSet.iterator(); i.hasNext();) {
  112. * String oid = (String)i.next();
  113. * System.out.println(oid);
  114. * }
  115. * }
  116. * </code></pre>
  117. *
  118. * @return a Set (or an empty Set if none are marked non-critical) of
  119. * the extension OID strings for extensions that are marked non-critical.
  120. * If there are no extensions present at all, then this method returns
  121. * null.
  122. */
  123. public Set getNonCriticalExtensionOIDs();
  124. /**
  125. * Gets the DER-encoded OCTET string for the extension value
  126. * (<em>extnValue</em>) identified by the passed-in <code>oid</code>
  127. * String.
  128. * The <code>oid</code> string is
  129. * represented by a set of positive whole numbers separated
  130. * by periods.
  131. *
  132. * <p>For example:<br>
  133. * <table border=groove>
  134. * <tr>
  135. * <th>OID <em>(Object Identifier)</em></th>
  136. * <th>Extension Name</th></tr>
  137. * <tr><td>2.5.29.14</td>
  138. * <td>SubjectKeyIdentifier</td></tr>
  139. * <tr><td>2.5.29.15</td>
  140. * <td>KeyUsage</td></tr>
  141. * <tr><td>2.5.29.16</td>
  142. * <td>PrivateKeyUsage</td></tr>
  143. * <tr><td>2.5.29.17</td>
  144. * <td>SubjectAlternativeName</td></tr>
  145. * <tr><td>2.5.29.18</td>
  146. * <td>IssuerAlternativeName</td></tr>
  147. * <tr><td>2.5.29.19</td>
  148. * <td>BasicConstraints</td></tr>
  149. * <tr><td>2.5.29.30</td>
  150. * <td>NameConstraints</td></tr>
  151. * <tr><td>2.5.29.33</td>
  152. * <td>PolicyMappings</td></tr>
  153. * <tr><td>2.5.29.35</td>
  154. * <td>AuthorityKeyIdentifier</td></tr>
  155. * <tr><td>2.5.29.36</td>
  156. * <td>PolicyConstraints</td></tr>
  157. * </table>
  158. *
  159. * @param oid the Object Identifier value for the extension.
  160. * @return the DER-encoded octet string of the extension value or
  161. * null if it is not present.
  162. */
  163. public byte[] getExtensionValue(String oid);
  164. }