TrustAnchor


1   /*
2    * @(#)TrustAnchor.java 1.10 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.security.cert;
9   
10  import java.io.IOException  ;
11  import java.security.PublicKey  ;
12  
13  import javax.security.auth.x500.X500Principal  ;
14  
15  import sun.security.x509.NameConstraintsExtension;
16  import sun.security.x509.X500Name;
17  
18  /**
19   * A trust anchor or most-trusted Certification Authority (CA).
20   * <p>
21   * This class represents a "most-trusted CA", which is used as a trust anchor
22   * for validating X.509 certification paths. A most-trusted CA includes the 
23   * public key of the CA, the CA's name, and any constraints upon the set of 
24   * paths which may be validated using this key. These parameters can be
25   * specified in the form of a trusted <code>X509Certificate</code> or as
26   * individual parameters.
27   * <p>
28   * <b>Concurrent Access</b>
29   * <p>
30   * <p>All <code>TrustAnchor</code> objects must be immutable and
31   * thread-safe. That is, multiple threads may concurrently invoke the
32   * methods defined in this class on a single <code>TrustAnchor</code>
33   * object (or more than one) with no ill effects. Requiring
34   * <code>TrustAnchor</code> objects to be immutable and thread-safe
35   * allows them to be passed around to various pieces of code without
36   * worrying about coordinating access. This stipulation applies to all 
37   * public fields and methods of this class and any added or overridden
38   * by subclasses. 
39   *
40   * @see PKIXParameters#PKIXParameters(Set)
41   * @see PKIXBuilderParameters#PKIXBuilderParameters(Set, CertSelector)
42   *
43   * @version     1.10 12/19/03
44   * @since       1.4
45   * @author      Sean Mullan
46   */
47  public class TrustAnchor {
48      
49      static {
50      CertPathHelperImpl.initialize();
51      }
52  
53      private final PublicKey   pubKey;
54      private final String   caName;
55      private final X500Principal   caPrincipal;
56      private final X509Certificate   trustedCert;
57      private byte[] ncBytes;
58      private NameConstraintsExtension nc;
59  
60      /**
61       * Creates an instance of <code>TrustAnchor</code> with the specified
62       * <code>X509Certificate</code> and optional name constraints, which
63       * are intended to be used as additional constraints when validating 
64       * an X.509 certification path.
65       * <p>
66       * The name constraints are specified as a byte array. This byte array
67       * should contain the DER encoded form of the name constraints, as they
68       * would appear in the NameConstraints structure defined in RFC 2459
69       * and X.509. The ASN.1 definition of this structure appears below.
70       *
71       * <pre><code>
72       *  NameConstraints ::= SEQUENCE {
73       *       permittedSubtrees       [0]     GeneralSubtrees OPTIONAL,
74       *       excludedSubtrees        [1]     GeneralSubtrees OPTIONAL }
75       *
76       *  GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree
77       *
78       *  GeneralSubtree ::= SEQUENCE {
79       *       base                    GeneralName,
80       *       minimum         [0]     BaseDistance DEFAULT 0,
81       *       maximum         [1]     BaseDistance OPTIONAL }
82       *
83       *  BaseDistance ::= INTEGER (0..MAX)
84       *
85       *  GeneralName ::= CHOICE {
86       *       otherName                       [0]     OtherName,
87       *       rfc822Name                      [1]     IA5String,
88       *       dNSName                         [2]     IA5String,
89       *       x400Address                     [3]     ORAddress,
90       *       directoryName                   [4]     Name,
91       *       ediPartyName                    [5]     EDIPartyName,
92       *       uniformResourceIdentifier       [6]     IA5String,
93       *       iPAddress                       [7]     OCTET STRING,
94       *       registeredID                    [8]     OBJECT IDENTIFIER}
95       * </code></pre>
96       * <p>
97       * Note that the name constraints byte array supplied is cloned to protect 
98       * against subsequent modifications.
99       *
100      * @param trustedCert a trusted <code>X509Certificate</code>
101      * @param nameConstraints a byte array containing the ASN.1 DER encoding of
102      * a NameConstraints extension to be used for checking name constraints. 
103      * Only the value of the extension is included, not the OID or criticality 
104      * flag. Specify <code>null</code> to omit the parameter.
105      * @throws IllegalArgumentException if the name constraints cannot be 
106      * decoded
107      * @throws NullPointerException if the specified 
108      * <code>X509Certificate</code> is <code>null</code>
109      */
110     public TrustAnchor(X509Certificate   trustedCert, byte[] nameConstraints) 
111     {
112     if (trustedCert == null)
113         throw new NullPointerException  ("the trustedCert parameter must " +
114         "be non-null");
115     this.trustedCert = trustedCert;
116         this.pubKey = null;
117         this.caName = null;
118     this.caPrincipal = null;
119     setNameConstraints(nameConstraints);
120     }
121 
122     /**
123      * Creates an instance of <code>TrustAnchor</code> where the
124      * most-trusted CA is specified as an X500Principal and public key.
125      * Name constraints are an optional parameter, and are intended to be used
126      * as additional constraints when validating an X.509 certification path.
127      * <p>
128      * The name constraints are specified as a byte array. This byte array
129      * contains the DER encoded form of the name constraints, as they
130      * would appear in the NameConstraints structure defined in RFC 2459
131      * and X.509. The ASN.1 notation for this structure is supplied in the
132      * documentation for
133      * {@link #TrustAnchor(X509Certificate, byte[])
134      * TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) }.
135      * <p>
136      * Note that the name constraints byte array supplied here is cloned to
137      * protect against subsequent modifications.
138      *
139      * @param caPrincipal the name of the most-trusted CA as X500Principal
140      * @param pubKey the public key of the most-trusted CA
141      * @param nameConstraints a byte array containing the ASN.1 DER encoding of
142      * a NameConstraints extension to be used for checking name constraints.
143      * Only the value of the extension is included, not the OID or criticality
144      * flag. Specify <code>null</code> to omit the parameter.
145      * @throws NullPointerException if the specified <code>caPrincipal</code> or
146      * <code>pubKey</code> parameter is <code>null</code>
147      * @since 1.5
148      */
149     public TrustAnchor(X500Principal   caPrincipal, PublicKey   pubKey,
150             byte[] nameConstraints) {
151     if ((caPrincipal == null) || (pubKey == null)) {
152         throw new NullPointerException  ();
153     }
154     this.trustedCert = null;
155     this.caPrincipal = caPrincipal;
156     this.caName = caPrincipal.getName();
157     this.pubKey = pubKey;
158     setNameConstraints(nameConstraints);
159     }
160  
161     /**
162      * Creates an instance of <code>TrustAnchor</code> where the
163      * most-trusted CA is specified as a distinguished name and public key.
164      * Name constraints are an optional parameter, and are intended to be used 
165      * as additional constraints when validating an X.509 certification path.
166      * <p>
167      * The name constraints are specified as a byte array. This byte array
168      * contains the DER encoded form of the name constraints, as they
169      * would appear in the NameConstraints structure defined in RFC 2459
170      * and X.509. The ASN.1 notation for this structure is supplied in the
171      * documentation for
172      * {@link #TrustAnchor(X509Certificate, byte[]) 
173      * TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) }.
174      * <p>
175      * Note that the name constraints byte array supplied here is cloned to 
176      * protect against subsequent modifications.
177      *
178      * @param caName the X.500 distinguished name of the most-trusted CA in
179      * RFC 2253 <code>String</code> format
180      * @param pubKey the public key of the most-trusted CA
181      * @param nameConstraints a byte array containing the ASN.1 DER encoding of
182      * a NameConstraints extension to be used for checking name constraints. 
183      * Only the value of the extension is included, not the OID or criticality 
184      * flag. Specify <code>null</code> to omit the parameter.
185      * @throws IllegalArgumentException if the specified <code>
186      * caName</code> parameter is empty <code>(caName.length() == 0)</code>
187      * or incorrectly formatted or the name constraints cannot be decoded
188      * @throws NullPointerException if the specified <code>caName</code> or
189      * <code>pubKey</code> parameter is <code>null</code>
190      */
191     public TrustAnchor(String   caName, PublicKey   pubKey, byte[] nameConstraints)
192     {
193         if (pubKey == null)
194             throw new NullPointerException  ("the pubKey parameter must be " +
195                 "non-null");
196         if (caName == null)
197             throw new NullPointerException  ("the caName parameter must be " +
198                 "non-null");
199         if (caName.length() == 0)
200             throw new IllegalArgumentException  ("the caName " +
201                 "parameter must be a non-empty String");
202     // check if caName is formatted correctly
203     this.caPrincipal = new X500Principal  (caName);
204         this.pubKey = pubKey;
205         this.caName = caName;
206     this.trustedCert = null;
207     setNameConstraints(nameConstraints);
208     }
209 
210     /**
211      * Returns the most-trusted CA certificate.
212      *
213      * @return a trusted <code>X509Certificate</code> or <code>null</code> 
214      * if the trust anchor was not specified as a trusted certificate
215      */
216     public final X509Certificate   getTrustedCert() {
217         return this.trustedCert;
218     }
219 
220     /**
221      * Returns the name of the most-trusted CA as an X500Principal.
222      *
223      * @return the X.500 distinguished name of the most-trusted CA, or
224      * <code>null</code> if the trust anchor was not specified as a trusted
225      * public key and name or X500Principal pair
226      * @since 1.5
227      */
228     public final X500Principal   getCA() {
229     return this.caPrincipal;
230     }
231 
232     /**
233      * Returns the name of the most-trusted CA in RFC 2253 <code>String</code>
234      * format.
235      *
236      * @return the X.500 distinguished name of the most-trusted CA, or
237      * <code>null</code> if the trust anchor was not specified as a trusted
238      * public key and name or X500Principal pair
239      */
240     public final String   getCAName() {
241         return this.caName;
242     }
243     
244     /**
245      * Returns the public key of the most-trusted CA.
246      *
247      * @return the public key of the most-trusted CA, or <code>null</code>
248      * if the trust anchor was not specified as a trusted public key and name
249      * or X500Principal pair
250      */
251     public final PublicKey   getCAPublicKey() {
252         return this.pubKey;
253     }
254 
255     /**
256      * Decode the name constraints and clone them if not null.
257      */
258     private void setNameConstraints(byte[] bytes) {
259         if (bytes == null) {
260             ncBytes = null;
261         nc = null;
262         } else {
263             ncBytes = (byte []) bytes.clone();
264             // validate DER encoding
265         try {
266                 nc = new NameConstraintsExtension(Boolean.FALSE, bytes);
267         } catch (IOException   ioe) {
268         IllegalArgumentException   iae = 
269             new IllegalArgumentException  (ioe.getMessage());
270         iae.initCause(ioe);
271         throw iae;
272         }
273         }
274     }
275     
276     /**
277      * Returns the name constraints parameter. The specified name constraints
278      * are associated with this trust anchor and are intended to be used 
279      * as additional constraints when validating an X.509 certification path. 
280      * <p>
281      * The name constraints are returned as a byte array. This byte array
282      * contains the DER encoded form of the name constraints, as they
283      * would appear in the NameConstraints structure defined in RFC 2459
284      * and X.509. The ASN.1 notation for this structure is supplied in the
285      * documentation for
286      * {@link #TrustAnchor(X509Certificate, byte[]) 
287      * TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) }.
288      * <p>
289      * Note that the byte array returned is cloned to protect against
290      * subsequent modifications.
291      *
292      * @return a byte array containing the ASN.1 DER encoding of
293      *         a NameConstraints extension used for checking name constraints, 
294      *         or <code>null</code> if not set. 
295      */
296     public final byte [] getNameConstraints() {
297     return (ncBytes == null ? null : (byte []) ncBytes.clone());
298     }
299 
300     /**
301      * Returns a formatted string describing the <code>TrustAnchor</code>.
302      *
303      * @return a formatted string describing the <code>TrustAnchor</code>
304      */
305     public String   toString() {
306         StringBuffer   sb = new StringBuffer  ();
307         sb.append("[\n");
308         if (pubKey != null) {
309             sb.append("  Trusted CA Public Key: " + pubKey.toString() + "\n");
310             sb.append("  Trusted CA Issuer Name: " 
311         + String.valueOf(caName) + "\n");
312     } else {
313         sb.append("  Trusted CA cert: " + trustedCert.toString() + "\n");
314     }
315     if (nc != null)
316         sb.append("  Name Constraints: " + nc.toString() + "\n");
317     return sb.toString();
318     }
319 }
320
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags