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