1 /*
2 * Copyright (c) 1997, 2012, 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
49 * </pre>
50 * <p>
51 * These certificates are widely used to support authentication and
52 * other functionality in Internet security systems. Common applications
53 * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
54 * code signing for trusted software distribution, and Secure Electronic
55 * Transactions (SET).
56 * <p>
57 * These certificates are managed and vouched for by <em>Certificate
58 * Authorities</em> (CAs). CAs are services which create certificates by
59 * placing data in the X.509 standard format and then digitally signing
60 * that data. CAs act as trusted third parties, making introductions
61 * between principals who have no direct knowledge of each other.
62 * CA certificates are either signed by themselves, or by some other
63 * CA such as a "root" CA.
64 * <p>
65 * More information can be found in
66 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
67 * Public Key Infrastructure Certificate and CRL Profile</a>.
68 * <p>
69 * The ASN.1 definition of <code>tbsCertificate</code> is:
70 * <pre>
71 * TBSCertificate ::= SEQUENCE {
72 * version [0] EXPLICIT Version DEFAULT v1,
73 * serialNumber CertificateSerialNumber,
74 * signature AlgorithmIdentifier,
75 * issuer Name,
76 * validity Validity,
77 * subject Name,
78 * subjectPublicKeyInfo SubjectPublicKeyInfo,
79 * issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL,
80 * -- If present, version must be v2 or v3
81 * subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL,
82 * -- If present, version must be v2 or v3
83 * extensions [3] EXPLICIT Extensions OPTIONAL
84 * -- If present, version must be v3
85 * }
86 * </pre>
87 * <p>
88 * Certificates are instantiated using a certificate factory. The following is
89 * an example of how to instantiate an X.509 certificate:
134 * utcTime UTCTime,
135 * generalTime GeneralizedTime }
136 * </pre>
137 *
138 * @exception CertificateExpiredException if the certificate has expired.
139 * @exception CertificateNotYetValidException if the certificate is not
140 * yet valid.
141 */
142 public abstract void checkValidity()
143 throws CertificateExpiredException, CertificateNotYetValidException;
144
145 /**
146 * Checks that the given date is within the certificate's
147 * validity period. In other words, this determines whether the
148 * certificate would be valid at the given date/time.
149 *
150 * @param date the Date to check against to see if this certificate
151 * is valid at that date/time.
152 *
153 * @exception CertificateExpiredException if the certificate has expired
154 * with respect to the <code>date</code> supplied.
155 * @exception CertificateNotYetValidException if the certificate is not
156 * yet valid with respect to the <code>date</code> supplied.
157 *
158 * @see #checkValidity()
159 */
160 public abstract void checkValidity(Date date)
161 throws CertificateExpiredException, CertificateNotYetValidException;
162
163 /**
164 * Gets the <code>version</code> (version number) value from the
165 * certificate.
166 * The ASN.1 definition for this is:
167 * <pre>
168 * version [0] EXPLICIT Version DEFAULT v1<p>
169 * Version ::= INTEGER { v1(0), v2(1), v3(2) }
170 * </pre>
171 * @return the version number, i.e. 1, 2 or 3.
172 */
173 public abstract int getVersion();
174
175 /**
176 * Gets the <code>serialNumber</code> value from the certificate.
177 * The serial number is an integer assigned by the certification
178 * authority to each certificate. It must be unique for each
179 * certificate issued by a given CA (i.e., the issuer name and
180 * serial number identify a unique certificate).
181 * The ASN.1 definition for this is:
182 * <pre>
183 * serialNumber CertificateSerialNumber<p>
184 *
185 * CertificateSerialNumber ::= INTEGER
186 * </pre>
187 *
188 * @return the serial number.
189 */
190 public abstract BigInteger getSerialNumber();
191
192 /**
193 * <strong>Denigrated</strong>, replaced by {@linkplain
194 * #getIssuerX500Principal()}. This method returns the <code>issuer</code>
195 * as an implementation specific Principal object, which should not be
196 * relied upon by portable code.
197 *
198 * <p>
199 * Gets the <code>issuer</code> (issuer distinguished name) value from
200 * the certificate. The issuer name identifies the entity that signed (and
201 * issued) the certificate.
202 *
203 * <p>The issuer name field contains an
204 * X.500 distinguished name (DN).
205 * The ASN.1 definition for this is:
206 * <pre>
207 * issuer Name<p>
208 *
209 * Name ::= CHOICE { RDNSequence }
210 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
211 * RelativeDistinguishedName ::=
212 * SET OF AttributeValueAssertion
213 *
214 * AttributeValueAssertion ::= SEQUENCE {
215 * AttributeType,
216 * AttributeValue }
217 * AttributeType ::= OBJECT IDENTIFIER
218 * AttributeValue ::= ANY
219 * </pre>
220 * The <code>Name</code> describes a hierarchical name composed of
221 * attributes,
222 * such as country name, and corresponding values, such as US.
223 * The type of the <code>AttributeValue</code> component is determined by
224 * the <code>AttributeType</code>; in general it will be a
225 * <code>directoryString</code>. A <code>directoryString</code> is usually
226 * one of <code>PrintableString</code>,
227 * <code>TeletexString</code> or <code>UniversalString</code>.
228 *
229 * @return a Principal whose name is the issuer distinguished name.
230 */
231 public abstract Principal getIssuerDN();
232
233 /**
234 * Returns the issuer (issuer distinguished name) value from the
235 * certificate as an <code>X500Principal</code>.
236 * <p>
237 * It is recommended that subclasses override this method.
238 *
239 * @return an <code>X500Principal</code> representing the issuer
240 * distinguished name
241 * @since 1.4
242 */
243 public X500Principal getIssuerX500Principal() {
244 if (issuerX500Principal == null) {
245 issuerX500Principal = X509CertImpl.getIssuerX500Principal(this);
246 }
247 return issuerX500Principal;
248 }
249
250 /**
251 * <strong>Denigrated</strong>, replaced by {@linkplain
252 * #getSubjectX500Principal()}. This method returns the <code>subject</code>
253 * as an implementation specific Principal object, which should not be
254 * relied upon by portable code.
255 *
256 * <p>
257 * Gets the <code>subject</code> (subject distinguished name) value
258 * from the certificate. If the <code>subject</code> value is empty,
259 * then the <code>getName()</code> method of the returned
260 * <code>Principal</code> object returns an empty string ("").
261 *
262 * <p> The ASN.1 definition for this is:
263 * <pre>
264 * subject Name
265 * </pre>
266 *
267 * <p>See {@link #getIssuerDN() getIssuerDN} for <code>Name</code>
268 * and other relevant definitions.
269 *
270 * @return a Principal whose name is the subject name.
271 */
272 public abstract Principal getSubjectDN();
273
274 /**
275 * Returns the subject (subject distinguished name) value from the
276 * certificate as an <code>X500Principal</code>. If the subject value
277 * is empty, then the <code>getName()</code> method of the returned
278 * <code>X500Principal</code> object returns an empty string ("").
279 * <p>
280 * It is recommended that subclasses override this method.
281 *
282 * @return an <code>X500Principal</code> representing the subject
283 * distinguished name
284 * @since 1.4
285 */
286 public X500Principal getSubjectX500Principal() {
287 if (subjectX500Principal == null) {
288 subjectX500Principal = X509CertImpl.getSubjectX500Principal(this);
289 }
290 return subjectX500Principal;
291 }
292
293 /**
294 * Gets the <code>notBefore</code> date from the validity period of
295 * the certificate.
296 * The relevant ASN.1 definitions are:
297 * <pre>
298 * validity Validity<p>
299 *
300 * Validity ::= SEQUENCE {
301 * notBefore CertificateValidityDate,
302 * notAfter CertificateValidityDate }<p>
303 * CertificateValidityDate ::= CHOICE {
304 * utcTime UTCTime,
305 * generalTime GeneralizedTime }
306 * </pre>
307 *
308 * @return the start date of the validity period.
309 * @see #checkValidity
310 */
311 public abstract Date getNotBefore();
312
313 /**
314 * Gets the <code>notAfter</code> date from the validity period of
315 * the certificate. See {@link #getNotBefore() getNotBefore}
316 * for relevant ASN.1 definitions.
317 *
318 * @return the end date of the validity period.
319 * @see #checkValidity
320 */
321 public abstract Date getNotAfter();
322
323 /**
324 * Gets the DER-encoded certificate information, the
325 * <code>tbsCertificate</code> from this certificate.
326 * This can be used to verify the signature independently.
327 *
328 * @return the DER-encoded certificate information.
329 * @exception CertificateEncodingException if an encoding error occurs.
330 */
331 public abstract byte[] getTBSCertificate()
332 throws CertificateEncodingException;
333
334 /**
335 * Gets the <code>signature</code> value (the raw signature bits) from
336 * the certificate.
337 * The ASN.1 definition for this is:
338 * <pre>
339 * signature BIT STRING
340 * </pre>
341 *
342 * @return the signature.
343 */
344 public abstract byte[] getSignature();
345
346 /**
347 * Gets the signature algorithm name for the certificate
348 * signature algorithm. An example is the string "SHA256withRSA".
349 * The ASN.1 definition for this is:
350 * <pre>
351 * signatureAlgorithm AlgorithmIdentifier<p>
352 * AlgorithmIdentifier ::= SEQUENCE {
353 * algorithm OBJECT IDENTIFIER,
354 * parameters ANY DEFINED BY algorithm OPTIONAL }
355 * -- contains a value of the type
356 * -- registered for use with the
357 * -- algorithm object identifier value
358 * </pre>
359 *
360 * <p>The algorithm name is determined from the <code>algorithm</code>
361 * OID string.
362 *
363 * @return the signature algorithm name.
364 */
365 public abstract String getSigAlgName();
366
367 /**
368 * Gets the signature algorithm OID string from the certificate.
369 * An OID is represented by a set of nonnegative whole numbers separated
370 * by periods.
371 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
372 * with DSA signature algorithm defined in
373 * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
374 * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
375 * and CRL Profile</a>.
376 *
377 * <p>See {@link #getSigAlgName() getSigAlgName} for
378 * relevant ASN.1 definitions.
379 *
380 * @return the signature algorithm OID string.
383
384 /**
385 * Gets the DER-encoded signature algorithm parameters from this
386 * certificate's signature algorithm. In most cases, the signature
387 * algorithm parameters are null; the parameters are usually
388 * supplied with the certificate's public key.
389 * If access to individual parameter values is needed then use
390 * {@link java.security.AlgorithmParameters AlgorithmParameters}
391 * and instantiate with the name returned by
392 * {@link #getSigAlgName() getSigAlgName}.
393 *
394 * <p>See {@link #getSigAlgName() getSigAlgName} for
395 * relevant ASN.1 definitions.
396 *
397 * @return the DER-encoded signature algorithm parameters, or
398 * null if no parameters are present.
399 */
400 public abstract byte[] getSigAlgParams();
401
402 /**
403 * Gets the <code>issuerUniqueID</code> value from the certificate.
404 * The issuer unique identifier is present in the certificate
405 * to handle the possibility of reuse of issuer names over time.
406 * RFC 3280 recommends that names not be reused and that
407 * conforming certificates not make use of unique identifiers.
408 * Applications conforming to that profile should be capable of
409 * parsing unique identifiers and making comparisons.
410 *
411 * <p>The ASN.1 definition for this is:
412 * <pre>
413 * issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL<p>
414 * UniqueIdentifier ::= BIT STRING
415 * </pre>
416 *
417 * @return the issuer unique identifier or null if it is not
418 * present in the certificate.
419 */
420 public abstract boolean[] getIssuerUniqueID();
421
422 /**
423 * Gets the <code>subjectUniqueID</code> value from the certificate.
424 *
425 * <p>The ASN.1 definition for this is:
426 * <pre>
427 * subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL<p>
428 * UniqueIdentifier ::= BIT STRING
429 * </pre>
430 *
431 * @return the subject unique identifier or null if it is not
432 * present in the certificate.
433 */
434 public abstract boolean[] getSubjectUniqueID();
435
436 /**
437 * Gets a boolean array representing bits of
438 * the <code>KeyUsage</code> extension, (OID = 2.5.29.15).
439 * The key usage extension defines the purpose (e.g., encipherment,
440 * signature, certificate signing) of the key contained in the
441 * certificate.
442 * The ASN.1 definition for this is:
443 * <pre>
444 * KeyUsage ::= BIT STRING {
445 * digitalSignature (0),
446 * nonRepudiation (1),
447 * keyEncipherment (2),
448 * dataEncipherment (3),
449 * keyAgreement (4),
450 * keyCertSign (5),
451 * cRLSign (6),
452 * encipherOnly (7),
453 * decipherOnly (8) }
454 * </pre>
455 * RFC 3280 recommends that when used, this be marked
456 * as a critical extension.
457 *
458 * @return the KeyUsage extension of this certificate, represented as
459 * an array of booleans. The order of KeyUsage values in the array is
460 * the same as in the above ASN.1 definition. The array will contain a
461 * value for each KeyUsage defined above. If the KeyUsage list encoded
462 * in the certificate is longer than the above list, it will not be
463 * truncated. Returns null if this certificate does not
464 * contain a KeyUsage extension.
465 */
466 public abstract boolean[] getKeyUsage();
467
468 /**
469 * Gets an unmodifiable list of Strings representing the OBJECT
470 * IDENTIFIERs of the <code>ExtKeyUsageSyntax</code> field of the
471 * extended key usage extension, (OID = 2.5.29.37). It indicates
472 * one or more purposes for which the certified public key may be
473 * used, in addition to or in place of the basic purposes
474 * indicated in the key usage extension field. The ASN.1
475 * definition for this is:
476 * <pre>
477 * ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId<p>
478 *
479 * KeyPurposeId ::= OBJECT IDENTIFIER<p>
480 * </pre>
481 *
482 * Key purposes may be defined by any organization with a
483 * need. Object identifiers used to identify key purposes shall be
484 * assigned in accordance with IANA or ITU-T Rec. X.660 |
485 * ISO/IEC/ITU 9834-1.
486 * <p>
487 * This method was added to version 1.4 of the Java 2 Platform Standard
488 * Edition. In order to maintain backwards compatibility with existing
489 * service providers, this method is not <code>abstract</code>
490 * and it provides a default implementation. Subclasses
491 * should override this method with a correct implementation.
492 *
493 * @return the ExtendedKeyUsage extension of this certificate,
494 * as an unmodifiable list of object identifiers represented
495 * as Strings. Returns null if this certificate does not
496 * contain an ExtendedKeyUsage extension.
497 * @throws CertificateParsingException if the extension cannot be decoded
498 * @since 1.4
499 */
500 public List<String> getExtendedKeyUsage() throws CertificateParsingException {
501 return X509CertImpl.getExtendedKeyUsage(this);
502 }
503
504 /**
505 * Gets the certificate constraints path length from the
506 * critical <code>BasicConstraints</code> extension, (OID = 2.5.29.19).
507 * <p>
508 * The basic constraints extension identifies whether the subject
509 * of the certificate is a Certificate Authority (CA) and
510 * how deep a certification path may exist through that CA. The
511 * <code>pathLenConstraint</code> field (see below) is meaningful
512 * only if <code>cA</code> is set to TRUE. In this case, it gives the
513 * maximum number of CA certificates that may follow this certificate in a
514 * certification path. A value of zero indicates that only an end-entity
515 * certificate may follow in the path.
516 * <p>
517 * The ASN.1 definition for this is:
518 * <pre>
519 * BasicConstraints ::= SEQUENCE {
520 * cA BOOLEAN DEFAULT FALSE,
521 * pathLenConstraint INTEGER (0..MAX) OPTIONAL }
522 * </pre>
523 *
524 * @return the value of <code>pathLenConstraint</code> if the
525 * BasicConstraints extension is present in the certificate and the
526 * subject of the certificate is a CA, otherwise -1.
527 * If the subject of the certificate is a CA and
528 * <code>pathLenConstraint</code> does not appear,
529 * <code>Integer.MAX_VALUE</code> is returned to indicate that there is no
530 * limit to the allowed length of the certification path.
531 */
532 public abstract int getBasicConstraints();
533
534 /**
535 * Gets an immutable collection of subject alternative names from the
536 * <code>SubjectAltName</code> extension, (OID = 2.5.29.17).
537 * <p>
538 * The ASN.1 definition of the <code>SubjectAltName</code> extension is:
539 * <pre>
540 * SubjectAltName ::= GeneralNames
541 *
542 * GeneralNames :: = SEQUENCE SIZE (1..MAX) OF GeneralName
543 *
544 * GeneralName ::= CHOICE {
545 * otherName [0] OtherName,
546 * rfc822Name [1] IA5String,
547 * dNSName [2] IA5String,
548 * x400Address [3] ORAddress,
549 * directoryName [4] Name,
550 * ediPartyName [5] EDIPartyName,
551 * uniformResourceIdentifier [6] IA5String,
552 * iPAddress [7] OCTET STRING,
553 * registeredID [8] OBJECT IDENTIFIER}
554 * </pre>
555 * <p>
556 * If this certificate does not contain a <code>SubjectAltName</code>
557 * extension, <code>null</code> is returned. Otherwise, a
558 * <code>Collection</code> is returned with an entry representing each
559 * <code>GeneralName</code> included in the extension. Each entry is a
560 * <code>List</code> whose first entry is an <code>Integer</code>
561 * (the name type, 0-8) and whose second entry is a <code>String</code>
562 * or a byte array (the name, in string or ASN.1 DER encoded form,
563 * respectively).
564 * <p>
565 * <a href="http://www.ietf.org/rfc/rfc822.txt">RFC 822</a>, DNS, and URI
566 * names are returned as <code>String</code>s,
567 * using the well-established string formats for those types (subject to
568 * the restrictions included in RFC 3280). IPv4 address names are
569 * returned using dotted quad notation. IPv6 address names are returned
570 * in the form "a1:a2:...:a8", where a1-a8 are hexadecimal values
571 * representing the eight 16-bit pieces of the address. OID names are
572 * returned as <code>String</code>s represented as a series of nonnegative
573 * integers separated by periods. And directory names (distinguished names)
574 * are returned in <a href="http://www.ietf.org/rfc/rfc2253.txt">
575 * RFC 2253</a> string format. No standard string format is
576 * defined for otherNames, X.400 names, EDI party names, or any
577 * other type of names. They are returned as byte arrays
578 * containing the ASN.1 DER encoded form of the name.
579 * <p>
580 * Note that the <code>Collection</code> returned may contain more
581 * than one name of the same type. Also, note that the returned
582 * <code>Collection</code> is immutable and any entries containing byte
583 * arrays are cloned to protect against subsequent modifications.
584 * <p>
585 * This method was added to version 1.4 of the Java 2 Platform Standard
586 * Edition. In order to maintain backwards compatibility with existing
587 * service providers, this method is not <code>abstract</code>
588 * and it provides a default implementation. Subclasses
589 * should override this method with a correct implementation.
590 *
591 * @return an immutable <code>Collection</code> of subject alternative
592 * names (or <code>null</code>)
593 * @throws CertificateParsingException if the extension cannot be decoded
594 * @since 1.4
595 */
596 public Collection<List<?>> getSubjectAlternativeNames()
597 throws CertificateParsingException {
598 return X509CertImpl.getSubjectAlternativeNames(this);
599 }
600
601 /**
602 * Gets an immutable collection of issuer alternative names from the
603 * <code>IssuerAltName</code> extension, (OID = 2.5.29.18).
604 * <p>
605 * The ASN.1 definition of the <code>IssuerAltName</code> extension is:
606 * <pre>
607 * IssuerAltName ::= GeneralNames
608 * </pre>
609 * The ASN.1 definition of <code>GeneralNames</code> is defined
610 * in {@link #getSubjectAlternativeNames getSubjectAlternativeNames}.
611 * <p>
612 * If this certificate does not contain an <code>IssuerAltName</code>
613 * extension, <code>null</code> is returned. Otherwise, a
614 * <code>Collection</code> is returned with an entry representing each
615 * <code>GeneralName</code> included in the extension. Each entry is a
616 * <code>List</code> whose first entry is an <code>Integer</code>
617 * (the name type, 0-8) and whose second entry is a <code>String</code>
618 * or a byte array (the name, in string or ASN.1 DER encoded form,
619 * respectively). For more details about the formats used for each
620 * name type, see the <code>getSubjectAlternativeNames</code> method.
621 * <p>
622 * Note that the <code>Collection</code> returned may contain more
623 * than one name of the same type. Also, note that the returned
624 * <code>Collection</code> is immutable and any entries containing byte
625 * arrays are cloned to protect against subsequent modifications.
626 * <p>
627 * This method was added to version 1.4 of the Java 2 Platform Standard
628 * Edition. In order to maintain backwards compatibility with existing
629 * service providers, this method is not <code>abstract</code>
630 * and it provides a default implementation. Subclasses
631 * should override this method with a correct implementation.
632 *
633 * @return an immutable <code>Collection</code> of issuer alternative
634 * names (or <code>null</code>)
635 * @throws CertificateParsingException if the extension cannot be decoded
636 * @since 1.4
637 */
638 public Collection<List<?>> getIssuerAlternativeNames()
639 throws CertificateParsingException {
640 return X509CertImpl.getIssuerAlternativeNames(this);
641 }
642
643 /**
644 * Verifies that this certificate was signed using the
645 * private key that corresponds to the specified public key.
646 * This method uses the signature verification engine
647 * supplied by the specified provider. Note that the specified
648 * Provider object does not have to be registered in the provider list.
649 *
650 * This method was added to version 1.8 of the Java Platform Standard
651 * Edition. In order to maintain backwards compatibility with existing
652 * service providers, this method is not <code>abstract</code>
653 * and it provides a default implementation.
654 *
655 * @param key the PublicKey used to carry out the verification.
656 * @param sigProvider the signature provider.
657 *
658 * @exception NoSuchAlgorithmException on unsupported signature
659 * algorithms.
660 * @exception InvalidKeyException on incorrect key.
661 * @exception SignatureException on signature errors.
662 * @exception CertificateException on encoding errors.
663 * @exception UnsupportedOperationException if the method is not supported
664 * @since 1.8
665 */
666 public void verify(PublicKey key, Provider sigProvider)
667 throws CertificateException, NoSuchAlgorithmException,
668 InvalidKeyException, SignatureException {
669 X509CertImpl.verify(this, key, sigProvider);
670 }
671 }
|
1 /*
2 * Copyright (c) 1997, 2013, 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
49 * </pre>
50 * <p>
51 * These certificates are widely used to support authentication and
52 * other functionality in Internet security systems. Common applications
53 * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
54 * code signing for trusted software distribution, and Secure Electronic
55 * Transactions (SET).
56 * <p>
57 * These certificates are managed and vouched for by <em>Certificate
58 * Authorities</em> (CAs). CAs are services which create certificates by
59 * placing data in the X.509 standard format and then digitally signing
60 * that data. CAs act as trusted third parties, making introductions
61 * between principals who have no direct knowledge of each other.
62 * CA certificates are either signed by themselves, or by some other
63 * CA such as a "root" CA.
64 * <p>
65 * More information can be found in
66 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
67 * Public Key Infrastructure Certificate and CRL Profile</a>.
68 * <p>
69 * The ASN.1 definition of {@code tbsCertificate} is:
70 * <pre>
71 * TBSCertificate ::= SEQUENCE {
72 * version [0] EXPLICIT Version DEFAULT v1,
73 * serialNumber CertificateSerialNumber,
74 * signature AlgorithmIdentifier,
75 * issuer Name,
76 * validity Validity,
77 * subject Name,
78 * subjectPublicKeyInfo SubjectPublicKeyInfo,
79 * issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL,
80 * -- If present, version must be v2 or v3
81 * subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL,
82 * -- If present, version must be v2 or v3
83 * extensions [3] EXPLICIT Extensions OPTIONAL
84 * -- If present, version must be v3
85 * }
86 * </pre>
87 * <p>
88 * Certificates are instantiated using a certificate factory. The following is
89 * an example of how to instantiate an X.509 certificate:
134 * utcTime UTCTime,
135 * generalTime GeneralizedTime }
136 * </pre>
137 *
138 * @exception CertificateExpiredException if the certificate has expired.
139 * @exception CertificateNotYetValidException if the certificate is not
140 * yet valid.
141 */
142 public abstract void checkValidity()
143 throws CertificateExpiredException, CertificateNotYetValidException;
144
145 /**
146 * Checks that the given date is within the certificate's
147 * validity period. In other words, this determines whether the
148 * certificate would be valid at the given date/time.
149 *
150 * @param date the Date to check against to see if this certificate
151 * is valid at that date/time.
152 *
153 * @exception CertificateExpiredException if the certificate has expired
154 * with respect to the {@code date} supplied.
155 * @exception CertificateNotYetValidException if the certificate is not
156 * yet valid with respect to the {@code date} supplied.
157 *
158 * @see #checkValidity()
159 */
160 public abstract void checkValidity(Date date)
161 throws CertificateExpiredException, CertificateNotYetValidException;
162
163 /**
164 * Gets the {@code version} (version number) value from the
165 * certificate.
166 * The ASN.1 definition for this is:
167 * <pre>
168 * version [0] EXPLICIT Version DEFAULT v1<p>
169 * Version ::= INTEGER { v1(0), v2(1), v3(2) }
170 * </pre>
171 * @return the version number, i.e. 1, 2 or 3.
172 */
173 public abstract int getVersion();
174
175 /**
176 * Gets the {@code serialNumber} value from the certificate.
177 * The serial number is an integer assigned by the certification
178 * authority to each certificate. It must be unique for each
179 * certificate issued by a given CA (i.e., the issuer name and
180 * serial number identify a unique certificate).
181 * The ASN.1 definition for this is:
182 * <pre>
183 * serialNumber CertificateSerialNumber<p>
184 *
185 * CertificateSerialNumber ::= INTEGER
186 * </pre>
187 *
188 * @return the serial number.
189 */
190 public abstract BigInteger getSerialNumber();
191
192 /**
193 * <strong>Denigrated</strong>, replaced by {@linkplain
194 * #getIssuerX500Principal()}. This method returns the {@code issuer}
195 * as an implementation specific Principal object, which should not be
196 * relied upon by portable code.
197 *
198 * <p>
199 * Gets the {@code issuer} (issuer distinguished name) value from
200 * the certificate. The issuer name identifies the entity that signed (and
201 * issued) the certificate.
202 *
203 * <p>The issuer name field contains an
204 * X.500 distinguished name (DN).
205 * The ASN.1 definition for this is:
206 * <pre>
207 * issuer Name<p>
208 *
209 * Name ::= CHOICE { RDNSequence }
210 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
211 * RelativeDistinguishedName ::=
212 * SET OF AttributeValueAssertion
213 *
214 * AttributeValueAssertion ::= SEQUENCE {
215 * AttributeType,
216 * AttributeValue }
217 * AttributeType ::= OBJECT IDENTIFIER
218 * AttributeValue ::= ANY
219 * </pre>
220 * The {@code Name} describes a hierarchical name composed of
221 * attributes,
222 * such as country name, and corresponding values, such as US.
223 * The type of the {@code AttributeValue} component is determined by
224 * the {@code AttributeType}; in general it will be a
225 * {@code directoryString}. A {@code directoryString} is usually
226 * one of {@code PrintableString},
227 * {@code TeletexString} or {@code UniversalString}.
228 *
229 * @return a Principal whose name is the issuer distinguished name.
230 */
231 public abstract Principal getIssuerDN();
232
233 /**
234 * Returns the issuer (issuer distinguished name) value from the
235 * certificate as an {@code X500Principal}.
236 * <p>
237 * It is recommended that subclasses override this method.
238 *
239 * @return an {@code X500Principal} representing the issuer
240 * distinguished name
241 * @since 1.4
242 */
243 public X500Principal getIssuerX500Principal() {
244 if (issuerX500Principal == null) {
245 issuerX500Principal = X509CertImpl.getIssuerX500Principal(this);
246 }
247 return issuerX500Principal;
248 }
249
250 /**
251 * <strong>Denigrated</strong>, replaced by {@linkplain
252 * #getSubjectX500Principal()}. This method returns the {@code subject}
253 * as an implementation specific Principal object, which should not be
254 * relied upon by portable code.
255 *
256 * <p>
257 * Gets the {@code subject} (subject distinguished name) value
258 * from the certificate. If the {@code subject} value is empty,
259 * then the {@code getName()} method of the returned
260 * {@code Principal} object returns an empty string ("").
261 *
262 * <p> The ASN.1 definition for this is:
263 * <pre>
264 * subject Name
265 * </pre>
266 *
267 * <p>See {@link #getIssuerDN() getIssuerDN} for {@code Name}
268 * and other relevant definitions.
269 *
270 * @return a Principal whose name is the subject name.
271 */
272 public abstract Principal getSubjectDN();
273
274 /**
275 * Returns the subject (subject distinguished name) value from the
276 * certificate as an {@code X500Principal}. If the subject value
277 * is empty, then the {@code getName()} method of the returned
278 * {@code X500Principal} object returns an empty string ("").
279 * <p>
280 * It is recommended that subclasses override this method.
281 *
282 * @return an {@code X500Principal} representing the subject
283 * distinguished name
284 * @since 1.4
285 */
286 public X500Principal getSubjectX500Principal() {
287 if (subjectX500Principal == null) {
288 subjectX500Principal = X509CertImpl.getSubjectX500Principal(this);
289 }
290 return subjectX500Principal;
291 }
292
293 /**
294 * Gets the {@code notBefore} date from the validity period of
295 * the certificate.
296 * The relevant ASN.1 definitions are:
297 * <pre>
298 * validity Validity<p>
299 *
300 * Validity ::= SEQUENCE {
301 * notBefore CertificateValidityDate,
302 * notAfter CertificateValidityDate }<p>
303 * CertificateValidityDate ::= CHOICE {
304 * utcTime UTCTime,
305 * generalTime GeneralizedTime }
306 * </pre>
307 *
308 * @return the start date of the validity period.
309 * @see #checkValidity
310 */
311 public abstract Date getNotBefore();
312
313 /**
314 * Gets the {@code notAfter} date from the validity period of
315 * the certificate. See {@link #getNotBefore() getNotBefore}
316 * for relevant ASN.1 definitions.
317 *
318 * @return the end date of the validity period.
319 * @see #checkValidity
320 */
321 public abstract Date getNotAfter();
322
323 /**
324 * Gets the DER-encoded certificate information, the
325 * {@code tbsCertificate} from this certificate.
326 * This can be used to verify the signature independently.
327 *
328 * @return the DER-encoded certificate information.
329 * @exception CertificateEncodingException if an encoding error occurs.
330 */
331 public abstract byte[] getTBSCertificate()
332 throws CertificateEncodingException;
333
334 /**
335 * Gets the {@code signature} value (the raw signature bits) from
336 * the certificate.
337 * The ASN.1 definition for this is:
338 * <pre>
339 * signature BIT STRING
340 * </pre>
341 *
342 * @return the signature.
343 */
344 public abstract byte[] getSignature();
345
346 /**
347 * Gets the signature algorithm name for the certificate
348 * signature algorithm. An example is the string "SHA256withRSA".
349 * The ASN.1 definition for this is:
350 * <pre>
351 * signatureAlgorithm AlgorithmIdentifier<p>
352 * AlgorithmIdentifier ::= SEQUENCE {
353 * algorithm OBJECT IDENTIFIER,
354 * parameters ANY DEFINED BY algorithm OPTIONAL }
355 * -- contains a value of the type
356 * -- registered for use with the
357 * -- algorithm object identifier value
358 * </pre>
359 *
360 * <p>The algorithm name is determined from the {@code algorithm}
361 * OID string.
362 *
363 * @return the signature algorithm name.
364 */
365 public abstract String getSigAlgName();
366
367 /**
368 * Gets the signature algorithm OID string from the certificate.
369 * An OID is represented by a set of nonnegative whole numbers separated
370 * by periods.
371 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
372 * with DSA signature algorithm defined in
373 * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
374 * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
375 * and CRL Profile</a>.
376 *
377 * <p>See {@link #getSigAlgName() getSigAlgName} for
378 * relevant ASN.1 definitions.
379 *
380 * @return the signature algorithm OID string.
383
384 /**
385 * Gets the DER-encoded signature algorithm parameters from this
386 * certificate's signature algorithm. In most cases, the signature
387 * algorithm parameters are null; the parameters are usually
388 * supplied with the certificate's public key.
389 * If access to individual parameter values is needed then use
390 * {@link java.security.AlgorithmParameters AlgorithmParameters}
391 * and instantiate with the name returned by
392 * {@link #getSigAlgName() getSigAlgName}.
393 *
394 * <p>See {@link #getSigAlgName() getSigAlgName} for
395 * relevant ASN.1 definitions.
396 *
397 * @return the DER-encoded signature algorithm parameters, or
398 * null if no parameters are present.
399 */
400 public abstract byte[] getSigAlgParams();
401
402 /**
403 * Gets the {@code issuerUniqueID} value from the certificate.
404 * The issuer unique identifier is present in the certificate
405 * to handle the possibility of reuse of issuer names over time.
406 * RFC 3280 recommends that names not be reused and that
407 * conforming certificates not make use of unique identifiers.
408 * Applications conforming to that profile should be capable of
409 * parsing unique identifiers and making comparisons.
410 *
411 * <p>The ASN.1 definition for this is:
412 * <pre>
413 * issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL<p>
414 * UniqueIdentifier ::= BIT STRING
415 * </pre>
416 *
417 * @return the issuer unique identifier or null if it is not
418 * present in the certificate.
419 */
420 public abstract boolean[] getIssuerUniqueID();
421
422 /**
423 * Gets the {@code subjectUniqueID} value from the certificate.
424 *
425 * <p>The ASN.1 definition for this is:
426 * <pre>
427 * subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL<p>
428 * UniqueIdentifier ::= BIT STRING
429 * </pre>
430 *
431 * @return the subject unique identifier or null if it is not
432 * present in the certificate.
433 */
434 public abstract boolean[] getSubjectUniqueID();
435
436 /**
437 * Gets a boolean array representing bits of
438 * the {@code KeyUsage} extension, (OID = 2.5.29.15).
439 * The key usage extension defines the purpose (e.g., encipherment,
440 * signature, certificate signing) of the key contained in the
441 * certificate.
442 * The ASN.1 definition for this is:
443 * <pre>
444 * KeyUsage ::= BIT STRING {
445 * digitalSignature (0),
446 * nonRepudiation (1),
447 * keyEncipherment (2),
448 * dataEncipherment (3),
449 * keyAgreement (4),
450 * keyCertSign (5),
451 * cRLSign (6),
452 * encipherOnly (7),
453 * decipherOnly (8) }
454 * </pre>
455 * RFC 3280 recommends that when used, this be marked
456 * as a critical extension.
457 *
458 * @return the KeyUsage extension of this certificate, represented as
459 * an array of booleans. The order of KeyUsage values in the array is
460 * the same as in the above ASN.1 definition. The array will contain a
461 * value for each KeyUsage defined above. If the KeyUsage list encoded
462 * in the certificate is longer than the above list, it will not be
463 * truncated. Returns null if this certificate does not
464 * contain a KeyUsage extension.
465 */
466 public abstract boolean[] getKeyUsage();
467
468 /**
469 * Gets an unmodifiable list of Strings representing the OBJECT
470 * IDENTIFIERs of the {@code ExtKeyUsageSyntax} field of the
471 * extended key usage extension, (OID = 2.5.29.37). It indicates
472 * one or more purposes for which the certified public key may be
473 * used, in addition to or in place of the basic purposes
474 * indicated in the key usage extension field. The ASN.1
475 * definition for this is:
476 * <pre>
477 * ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId<p>
478 *
479 * KeyPurposeId ::= OBJECT IDENTIFIER<p>
480 * </pre>
481 *
482 * Key purposes may be defined by any organization with a
483 * need. Object identifiers used to identify key purposes shall be
484 * assigned in accordance with IANA or ITU-T Rec. X.660 |
485 * ISO/IEC/ITU 9834-1.
486 * <p>
487 * This method was added to version 1.4 of the Java 2 Platform Standard
488 * Edition. In order to maintain backwards compatibility with existing
489 * service providers, this method is not {@code abstract}
490 * and it provides a default implementation. Subclasses
491 * should override this method with a correct implementation.
492 *
493 * @return the ExtendedKeyUsage extension of this certificate,
494 * as an unmodifiable list of object identifiers represented
495 * as Strings. Returns null if this certificate does not
496 * contain an ExtendedKeyUsage extension.
497 * @throws CertificateParsingException if the extension cannot be decoded
498 * @since 1.4
499 */
500 public List<String> getExtendedKeyUsage() throws CertificateParsingException {
501 return X509CertImpl.getExtendedKeyUsage(this);
502 }
503
504 /**
505 * Gets the certificate constraints path length from the
506 * critical {@code BasicConstraints} extension, (OID = 2.5.29.19).
507 * <p>
508 * The basic constraints extension identifies whether the subject
509 * of the certificate is a Certificate Authority (CA) and
510 * how deep a certification path may exist through that CA. The
511 * {@code pathLenConstraint} field (see below) is meaningful
512 * only if {@code cA} is set to TRUE. In this case, it gives the
513 * maximum number of CA certificates that may follow this certificate in a
514 * certification path. A value of zero indicates that only an end-entity
515 * certificate may follow in the path.
516 * <p>
517 * The ASN.1 definition for this is:
518 * <pre>
519 * BasicConstraints ::= SEQUENCE {
520 * cA BOOLEAN DEFAULT FALSE,
521 * pathLenConstraint INTEGER (0..MAX) OPTIONAL }
522 * </pre>
523 *
524 * @return the value of {@code pathLenConstraint} if the
525 * BasicConstraints extension is present in the certificate and the
526 * subject of the certificate is a CA, otherwise -1.
527 * If the subject of the certificate is a CA and
528 * {@code pathLenConstraint} does not appear,
529 * {@code Integer.MAX_VALUE} is returned to indicate that there is no
530 * limit to the allowed length of the certification path.
531 */
532 public abstract int getBasicConstraints();
533
534 /**
535 * Gets an immutable collection of subject alternative names from the
536 * {@code SubjectAltName} extension, (OID = 2.5.29.17).
537 * <p>
538 * The ASN.1 definition of the {@code SubjectAltName} extension is:
539 * <pre>
540 * SubjectAltName ::= GeneralNames
541 *
542 * GeneralNames :: = SEQUENCE SIZE (1..MAX) OF GeneralName
543 *
544 * GeneralName ::= CHOICE {
545 * otherName [0] OtherName,
546 * rfc822Name [1] IA5String,
547 * dNSName [2] IA5String,
548 * x400Address [3] ORAddress,
549 * directoryName [4] Name,
550 * ediPartyName [5] EDIPartyName,
551 * uniformResourceIdentifier [6] IA5String,
552 * iPAddress [7] OCTET STRING,
553 * registeredID [8] OBJECT IDENTIFIER}
554 * </pre>
555 * <p>
556 * If this certificate does not contain a {@code SubjectAltName}
557 * extension, {@code null} is returned. Otherwise, a
558 * {@code Collection} is returned with an entry representing each
559 * {@code GeneralName} included in the extension. Each entry is a
560 * {@code List} whose first entry is an {@code Integer}
561 * (the name type, 0-8) and whose second entry is a {@code String}
562 * or a byte array (the name, in string or ASN.1 DER encoded form,
563 * respectively).
564 * <p>
565 * <a href="http://www.ietf.org/rfc/rfc822.txt">RFC 822</a>, DNS, and URI
566 * names are returned as {@code String}s,
567 * using the well-established string formats for those types (subject to
568 * the restrictions included in RFC 3280). IPv4 address names are
569 * returned using dotted quad notation. IPv6 address names are returned
570 * in the form "a1:a2:...:a8", where a1-a8 are hexadecimal values
571 * representing the eight 16-bit pieces of the address. OID names are
572 * returned as {@code String}s represented as a series of nonnegative
573 * integers separated by periods. And directory names (distinguished names)
574 * are returned in <a href="http://www.ietf.org/rfc/rfc2253.txt">
575 * RFC 2253</a> string format. No standard string format is
576 * defined for otherNames, X.400 names, EDI party names, or any
577 * other type of names. They are returned as byte arrays
578 * containing the ASN.1 DER encoded form of the name.
579 * <p>
580 * Note that the {@code Collection} returned may contain more
581 * than one name of the same type. Also, note that the returned
582 * {@code Collection} is immutable and any entries containing byte
583 * arrays are cloned to protect against subsequent modifications.
584 * <p>
585 * This method was added to version 1.4 of the Java 2 Platform Standard
586 * Edition. In order to maintain backwards compatibility with existing
587 * service providers, this method is not {@code abstract}
588 * and it provides a default implementation. Subclasses
589 * should override this method with a correct implementation.
590 *
591 * @return an immutable {@code Collection} of subject alternative
592 * names (or {@code null})
593 * @throws CertificateParsingException if the extension cannot be decoded
594 * @since 1.4
595 */
596 public Collection<List<?>> getSubjectAlternativeNames()
597 throws CertificateParsingException {
598 return X509CertImpl.getSubjectAlternativeNames(this);
599 }
600
601 /**
602 * Gets an immutable collection of issuer alternative names from the
603 * {@code IssuerAltName} extension, (OID = 2.5.29.18).
604 * <p>
605 * The ASN.1 definition of the {@code IssuerAltName} extension is:
606 * <pre>
607 * IssuerAltName ::= GeneralNames
608 * </pre>
609 * The ASN.1 definition of {@code GeneralNames} is defined
610 * in {@link #getSubjectAlternativeNames getSubjectAlternativeNames}.
611 * <p>
612 * If this certificate does not contain an {@code IssuerAltName}
613 * extension, {@code null} is returned. Otherwise, a
614 * {@code Collection} is returned with an entry representing each
615 * {@code GeneralName} included in the extension. Each entry is a
616 * {@code List} whose first entry is an {@code Integer}
617 * (the name type, 0-8) and whose second entry is a {@code String}
618 * or a byte array (the name, in string or ASN.1 DER encoded form,
619 * respectively). For more details about the formats used for each
620 * name type, see the {@code getSubjectAlternativeNames} method.
621 * <p>
622 * Note that the {@code Collection} returned may contain more
623 * than one name of the same type. Also, note that the returned
624 * {@code Collection} is immutable and any entries containing byte
625 * arrays are cloned to protect against subsequent modifications.
626 * <p>
627 * This method was added to version 1.4 of the Java 2 Platform Standard
628 * Edition. In order to maintain backwards compatibility with existing
629 * service providers, this method is not {@code abstract}
630 * and it provides a default implementation. Subclasses
631 * should override this method with a correct implementation.
632 *
633 * @return an immutable {@code Collection} of issuer alternative
634 * names (or {@code null})
635 * @throws CertificateParsingException if the extension cannot be decoded
636 * @since 1.4
637 */
638 public Collection<List<?>> getIssuerAlternativeNames()
639 throws CertificateParsingException {
640 return X509CertImpl.getIssuerAlternativeNames(this);
641 }
642
643 /**
644 * Verifies that this certificate was signed using the
645 * private key that corresponds to the specified public key.
646 * This method uses the signature verification engine
647 * supplied by the specified provider. Note that the specified
648 * Provider object does not have to be registered in the provider list.
649 *
650 * This method was added to version 1.8 of the Java Platform Standard
651 * Edition. In order to maintain backwards compatibility with existing
652 * service providers, this method is not {@code abstract}
653 * and it provides a default implementation.
654 *
655 * @param key the PublicKey used to carry out the verification.
656 * @param sigProvider the signature provider.
657 *
658 * @exception NoSuchAlgorithmException on unsupported signature
659 * algorithms.
660 * @exception InvalidKeyException on incorrect key.
661 * @exception SignatureException on signature errors.
662 * @exception CertificateException on encoding errors.
663 * @exception UnsupportedOperationException if the method is not supported
664 * @since 1.8
665 */
666 public void verify(PublicKey key, Provider sigProvider)
667 throws CertificateException, NoSuchAlgorithmException,
668 InvalidKeyException, SignatureException {
669 X509CertImpl.verify(this, key, sigProvider);
670 }
671 }
|