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