View Javadoc
1   /*
2    * Copyright (c) 2007, 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
23   * questions.
24   */
25  
26  package java.security.cert;
27  
28  import java.io.IOException;
29  import java.io.OutputStream;
30  import java.io.Serializable;
31  
32  /**
33   * This interface represents an X.509 extension.
34   *
35   * <p>
36   * Extensions provide a means of associating additional attributes with users
37   * or public keys and for managing a certification hierarchy.  The extension
38   * format also allows communities to define private extensions to carry
39   * information unique to those communities.
40   *
41   * <p>
42   * Each extension contains an object identifier, a criticality setting
43   * indicating whether it is a critical or a non-critical extension, and
44   * and an ASN.1 DER-encoded value. Its ASN.1 definition is:
45   *
46   * <pre>
47   *
48   *     Extension ::= SEQUENCE {
49   *         extnId        OBJECT IDENTIFIER,
50   *         critical      BOOLEAN DEFAULT FALSE,
51   *         extnValue     OCTET STRING
52   *                 -- contains a DER encoding of a value
53   *                 -- of the type registered for use with
54   *                 -- the extnId object identifier value
55   *     }
56   *
57   * </pre>
58   *
59   * <p>
60   * This interface is designed to provide access to a single extension,
61   * unlike {@link java.security.cert.X509Extension} which is more suitable
62   * for accessing a set of extensions.
63   *
64   * @since 1.7
65   */
66  public interface Extension {
67  
68      /**
69       * Gets the extensions's object identifier.
70       *
71       * @return the object identifier as a String
72       */
73      String getId();
74  
75      /**
76       * Gets the extension's criticality setting.
77       *
78       * @return true if this is a critical extension.
79       */
80      boolean isCritical();
81  
82      /**
83       * Gets the extensions's DER-encoded value. Note, this is the bytes
84       * that are encoded as an OCTET STRING. It does not include the OCTET
85       * STRING tag and length.
86       *
87       * @return a copy of the extension's value, or {@code null} if no
88       *    extension value is present.
89       */
90      byte[] getValue();
91  
92      /**
93       * Generates the extension's DER encoding and writes it to the output
94       * stream.
95       *
96       * @param out the output stream
97       * @exception IOException on encoding or output error.
98       * @exception NullPointerException if {@code out} is {@code null}.
99       */
100     void encode(OutputStream out) throws IOException;
101 }