1 /* 2 * Copyright (c) 1997, 2010, 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.security.NoSuchAlgorithmException; 29 import java.security.NoSuchProviderException; 30 import java.security.InvalidKeyException; 31 import java.security.SignatureException; 32 import java.security.Principal; 33 import java.security.PublicKey; 34 import javax.security.auth.x500.X500Principal; 35 36 import java.math.BigInteger; 37 import java.util.Date; 38 import java.util.Set; 39 import java.util.Arrays; 40 41 import sun.security.x509.X509CRLImpl; 42 43 /** 44 * <p> 45 * Abstract class for an X.509 Certificate Revocation List (CRL). 46 * A CRL is a time-stamped list identifying revoked certificates. 47 * It is signed by a Certificate Authority (CA) and made freely 48 * available in a public repository. 49 * 50 * <p>Each revoked certificate is 51 * identified in a CRL by its certificate serial number. When a 52 * certificate-using system uses a certificate (e.g., for verifying a 53 * remote user's digital signature), that system not only checks the 54 * certificate signature and validity but also acquires a suitably- 55 * recent CRL and checks that the certificate serial number is not on 56 * that CRL. The meaning of "suitably-recent" may vary with local 57 * policy, but it usually means the most recently-issued CRL. A CA 58 * issues a new CRL on a regular periodic basis (e.g., hourly, daily, or 59 * weekly). Entries are added to CRLs as revocations occur, and an 60 * entry may be removed when the certificate expiration date is reached. 61 * <p> 62 * The X.509 v2 CRL format is described below in ASN.1: 63 * <pre> 64 * CertificateList ::= SEQUENCE { 65 * tbsCertList TBSCertList, 66 * signatureAlgorithm AlgorithmIdentifier, 67 * signature BIT STRING } 68 * </pre> 69 * <p> 70 * More information can be found in 71 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509 72 * Public Key Infrastructure Certificate and CRL Profile</a>. 73 * <p> 74 * The ASN.1 definition of <code>tbsCertList</code> is: 75 * <pre> 76 * TBSCertList ::= SEQUENCE { 77 * version Version OPTIONAL, 78 * -- if present, must be v2 79 * signature AlgorithmIdentifier, 80 * issuer Name, 81 * thisUpdate ChoiceOfTime, 82 * nextUpdate ChoiceOfTime OPTIONAL, 83 * revokedCertificates SEQUENCE OF SEQUENCE { 84 * userCertificate CertificateSerialNumber, 85 * revocationDate ChoiceOfTime, 86 * crlEntryExtensions Extensions OPTIONAL 87 * -- if present, must be v2 88 * } OPTIONAL, 89 * crlExtensions [0] EXPLICIT Extensions OPTIONAL 90 * -- if present, must be v2 91 * } 92 * </pre> 93 * <p> 94 * CRLs are instantiated using a certificate factory. The following is an 95 * example of how to instantiate an X.509 CRL: 96 * <pre><code> 97 * InputStream inStream = null; 98 * try { 99 * inStream = new FileInputStream("fileName-of-crl"); 100 * CertificateFactory cf = CertificateFactory.getInstance("X.509"); 101 * X509CRL crl = (X509CRL)cf.generateCRL(inStream); 102 * } finally { 103 * if (inStream != null) { 104 * inStream.close(); 105 * } 106 * } 107 * </code></pre> 108 * 109 * @author Hemma Prafullchandra 110 * 111 * 112 * @see CRL 113 * @see CertificateFactory 114 * @see X509Extension 115 */ 116 117 public abstract class X509CRL extends CRL implements X509Extension { 118 119 private transient X500Principal issuerPrincipal; 120 121 /** 122 * Constructor for X.509 CRLs. 123 */ X509CRL()124 protected X509CRL() { 125 super("X.509"); 126 } 127 128 /** 129 * Compares this CRL for equality with the given 130 * object. If the <code>other</code> object is an 131 * <code>instanceof</code> <code>X509CRL</code>, then 132 * its encoded form is retrieved and compared with the 133 * encoded form of this CRL. 134 * 135 * @param other the object to test for equality with this CRL. 136 * 137 * @return true iff the encoded forms of the two CRLs 138 * match, false otherwise. 139 */ equals(Object other)140 public boolean equals(Object other) { 141 if (this == other) { 142 return true; 143 } 144 if (!(other instanceof X509CRL)) { 145 return false; 146 } 147 try { 148 byte[] thisCRL = X509CRLImpl.getEncodedInternal(this); 149 byte[] otherCRL = X509CRLImpl.getEncodedInternal((X509CRL)other); 150 151 return Arrays.equals(thisCRL, otherCRL); 152 } catch (CRLException e) { 153 return false; 154 } 155 } 156 157 /** 158 * Returns a hashcode value for this CRL from its 159 * encoded form. 160 * 161 * @return the hashcode value. 162 */ hashCode()163 public int hashCode() { 164 int retval = 0; 165 try { 166 byte[] crlData = X509CRLImpl.getEncodedInternal(this); 167 for (int i = 1; i < crlData.length; i++) { 168 retval += crlData[i] * i; 169 } 170 return retval; 171 } catch (CRLException e) { 172 return retval; 173 } 174 } 175 176 /** 177 * Returns the ASN.1 DER-encoded form of this CRL. 178 * 179 * @return the encoded form of this certificate 180 * @exception CRLException if an encoding error occurs. 181 */ getEncoded()182 public abstract byte[] getEncoded() 183 throws CRLException; 184 185 /** 186 * Verifies that this CRL was signed using the 187 * private key that corresponds to the given public key. 188 * 189 * @param key the PublicKey used to carry out the verification. 190 * 191 * @exception NoSuchAlgorithmException on unsupported signature 192 * algorithms. 193 * @exception InvalidKeyException on incorrect key. 194 * @exception NoSuchProviderException if there's no default provider. 195 * @exception SignatureException on signature errors. 196 * @exception CRLException on encoding errors. 197 */ verify(PublicKey key)198 public abstract void verify(PublicKey key) 199 throws CRLException, NoSuchAlgorithmException, 200 InvalidKeyException, NoSuchProviderException, 201 SignatureException; 202 203 /** 204 * Verifies that this CRL was signed using the 205 * private key that corresponds to the given public key. 206 * This method uses the signature verification engine 207 * supplied by the given provider. 208 * 209 * @param key the PublicKey used to carry out the verification. 210 * @param sigProvider the name of the signature provider. 211 * 212 * @exception NoSuchAlgorithmException on unsupported signature 213 * algorithms. 214 * @exception InvalidKeyException on incorrect key. 215 * @exception NoSuchProviderException on incorrect provider. 216 * @exception SignatureException on signature errors. 217 * @exception CRLException on encoding errors. 218 */ verify(PublicKey key, String sigProvider)219 public abstract void verify(PublicKey key, String sigProvider) 220 throws CRLException, NoSuchAlgorithmException, 221 InvalidKeyException, NoSuchProviderException, 222 SignatureException; 223 224 /** 225 * Gets the <code>version</code> (version number) value from the CRL. 226 * The ASN.1 definition for this is: 227 * <pre> 228 * version Version OPTIONAL, 229 * -- if present, must be v2<p> 230 * Version ::= INTEGER { v1(0), v2(1), v3(2) } 231 * -- v3 does not apply to CRLs but appears for consistency 232 * -- with definition of Version for certs 233 * </pre> 234 * 235 * @return the version number, i.e. 1 or 2. 236 */ getVersion()237 public abstract int getVersion(); 238 239 /** 240 * <strong>Denigrated</strong>, replaced by {@linkplain 241 * #getIssuerX500Principal()}. This method returns the <code>issuer</code> 242 * as an implementation specific Principal object, which should not be 243 * relied upon by portable code. 244 * 245 * <p> 246 * Gets the <code>issuer</code> (issuer distinguished name) value from 247 * the CRL. The issuer name identifies the entity that signed (and 248 * issued) the CRL. 249 * 250 * <p>The issuer name field contains an 251 * X.500 distinguished name (DN). 252 * The ASN.1 definition for this is: 253 * <pre> 254 * issuer Name 255 * 256 * Name ::= CHOICE { RDNSequence } 257 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 258 * RelativeDistinguishedName ::= 259 * SET OF AttributeValueAssertion 260 * 261 * AttributeValueAssertion ::= SEQUENCE { 262 * AttributeType, 263 * AttributeValue } 264 * AttributeType ::= OBJECT IDENTIFIER 265 * AttributeValue ::= ANY 266 * </pre> 267 * The <code>Name</code> describes a hierarchical name composed of 268 * attributes, 269 * such as country name, and corresponding values, such as US. 270 * The type of the <code>AttributeValue</code> component is determined by 271 * the <code>AttributeType</code>; in general it will be a 272 * <code>directoryString</code>. A <code>directoryString</code> is usually 273 * one of <code>PrintableString</code>, 274 * <code>TeletexString</code> or <code>UniversalString</code>. 275 * 276 * @return a Principal whose name is the issuer distinguished name. 277 */ getIssuerDN()278 public abstract Principal getIssuerDN(); 279 280 /** 281 * Returns the issuer (issuer distinguished name) value from the 282 * CRL as an <code>X500Principal</code>. 283 * <p> 284 * It is recommended that subclasses override this method. 285 * 286 * @return an <code>X500Principal</code> representing the issuer 287 * distinguished name 288 * @since 1.4 289 */ getIssuerX500Principal()290 public X500Principal getIssuerX500Principal() { 291 if (issuerPrincipal == null) { 292 issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this); 293 } 294 return issuerPrincipal; 295 } 296 297 /** 298 * Gets the <code>thisUpdate</code> date from the CRL. 299 * The ASN.1 definition for this is: 300 * <pre> 301 * thisUpdate ChoiceOfTime 302 * ChoiceOfTime ::= CHOICE { 303 * utcTime UTCTime, 304 * generalTime GeneralizedTime } 305 * </pre> 306 * 307 * @return the <code>thisUpdate</code> date from the CRL. 308 */ getThisUpdate()309 public abstract Date getThisUpdate(); 310 311 /** 312 * Gets the <code>nextUpdate</code> date from the CRL. 313 * 314 * @return the <code>nextUpdate</code> date from the CRL, or null if 315 * not present. 316 */ getNextUpdate()317 public abstract Date getNextUpdate(); 318 319 /** 320 * Gets the CRL entry, if any, with the given certificate serialNumber. 321 * 322 * @param serialNumber the serial number of the certificate for which a CRL entry 323 * is to be looked up 324 * @return the entry with the given serial number, or null if no such entry 325 * exists in this CRL. 326 * @see X509CRLEntry 327 */ 328 public abstract X509CRLEntry getRevokedCertificate(BigInteger serialNumber)329 getRevokedCertificate(BigInteger serialNumber); 330 331 /** 332 * Get the CRL entry, if any, for the given certificate. 333 * 334 * <p>This method can be used to lookup CRL entries in indirect CRLs, 335 * that means CRLs that contain entries from issuers other than the CRL 336 * issuer. The default implementation will only return entries for 337 * certificates issued by the CRL issuer. Subclasses that wish to 338 * support indirect CRLs should override this method. 339 * 340 * @param certificate the certificate for which a CRL entry is to be looked 341 * up 342 * @return the entry for the given certificate, or null if no such entry 343 * exists in this CRL. 344 * @exception NullPointerException if certificate is null 345 * 346 * @since 1.5 347 */ getRevokedCertificate(X509Certificate certificate)348 public X509CRLEntry getRevokedCertificate(X509Certificate certificate) { 349 X500Principal certIssuer = certificate.getIssuerX500Principal(); 350 X500Principal crlIssuer = getIssuerX500Principal(); 351 if (certIssuer.equals(crlIssuer) == false) { 352 return null; 353 } 354 return getRevokedCertificate(certificate.getSerialNumber()); 355 } 356 357 /** 358 * Gets all the entries from this CRL. 359 * This returns a Set of X509CRLEntry objects. 360 * 361 * @return all the entries or null if there are none present. 362 * @see X509CRLEntry 363 */ getRevokedCertificates()364 public abstract Set<? extends X509CRLEntry> getRevokedCertificates(); 365 366 /** 367 * Gets the DER-encoded CRL information, the 368 * <code>tbsCertList</code> from this CRL. 369 * This can be used to verify the signature independently. 370 * 371 * @return the DER-encoded CRL information. 372 * @exception CRLException if an encoding error occurs. 373 */ getTBSCertList()374 public abstract byte[] getTBSCertList() throws CRLException; 375 376 /** 377 * Gets the <code>signature</code> value (the raw signature bits) from 378 * the CRL. 379 * The ASN.1 definition for this is: 380 * <pre> 381 * signature BIT STRING 382 * </pre> 383 * 384 * @return the signature. 385 */ getSignature()386 public abstract byte[] getSignature(); 387 388 /** 389 * Gets the signature algorithm name for the CRL 390 * signature algorithm. An example is the string "SHA256withRSA". 391 * The ASN.1 definition for this is: 392 * <pre> 393 * signatureAlgorithm AlgorithmIdentifier<p> 394 * AlgorithmIdentifier ::= SEQUENCE { 395 * algorithm OBJECT IDENTIFIER, 396 * parameters ANY DEFINED BY algorithm OPTIONAL } 397 * -- contains a value of the type 398 * -- registered for use with the 399 * -- algorithm object identifier value 400 * </pre> 401 * 402 * <p>The algorithm name is determined from the <code>algorithm</code> 403 * OID string. 404 * 405 * @return the signature algorithm name. 406 */ getSigAlgName()407 public abstract String getSigAlgName(); 408 409 /** 410 * Gets the signature algorithm OID string from the CRL. 411 * An OID is represented by a set of nonnegative whole numbers separated 412 * by periods. 413 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1 414 * with DSA signature algorithm defined in 415 * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and 416 * Identifiers for the Internet X.509 Public Key Infrastructure Certificate 417 * and CRL Profile</a>. 418 * 419 * <p>See {@link #getSigAlgName() getSigAlgName} for 420 * relevant ASN.1 definitions. 421 * 422 * @return the signature algorithm OID string. 423 */ getSigAlgOID()424 public abstract String getSigAlgOID(); 425 426 /** 427 * Gets the DER-encoded signature algorithm parameters from this 428 * CRL's signature algorithm. In most cases, the signature 429 * algorithm parameters are null; the parameters are usually 430 * supplied with the public key. 431 * If access to individual parameter values is needed then use 432 * {@link java.security.AlgorithmParameters AlgorithmParameters} 433 * and instantiate with the name returned by 434 * {@link #getSigAlgName() getSigAlgName}. 435 * 436 * <p>See {@link #getSigAlgName() getSigAlgName} for 437 * relevant ASN.1 definitions. 438 * 439 * @return the DER-encoded signature algorithm parameters, or 440 * null if no parameters are present. 441 */ getSigAlgParams()442 public abstract byte[] getSigAlgParams(); 443 } 444