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      */
getId()73     String getId();
74 
75     /**
76      * Gets the extension's criticality setting.
77      *
78      * @return true if this is a critical extension.
79      */
isCritical()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      */
getValue()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      */
encode(OutputStream out)100     void encode(OutputStream out) throws IOException;
101 }
102