View Javadoc
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
23   * questions.
24   */
25  
26  package java.security;
27  
28  import java.io.*;
29  import java.security.spec.AlgorithmParameterSpec;
30  import java.security.spec.InvalidParameterSpecException;
31  
32  /**
33   * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
34   * for the {@code AlgorithmParameters} class, which is used to manage
35   * algorithm parameters.
36   *
37   * <p> All the abstract methods in this class must be implemented by each
38   * cryptographic service provider who wishes to supply parameter management
39   * for a particular algorithm.
40   *
41   * @author Jan Luehe
42   *
43   *
44   * @see AlgorithmParameters
45   * @see java.security.spec.AlgorithmParameterSpec
46   * @see java.security.spec.DSAParameterSpec
47   *
48   * @since 1.2
49   */
50  
51  public abstract class AlgorithmParametersSpi {
52  
53      /**
54       * Initializes this parameters object using the parameters
55       * specified in {@code paramSpec}.
56       *
57       * @param paramSpec the parameter specification.
58       *
59       * @exception InvalidParameterSpecException if the given parameter
60       * specification is inappropriate for the initialization of this parameter
61       * object.
62       */
63      protected abstract void engineInit(AlgorithmParameterSpec paramSpec)
64          throws InvalidParameterSpecException;
65  
66      /**
67       * Imports the specified parameters and decodes them
68       * according to the primary decoding format for parameters.
69       * The primary decoding format for parameters is ASN.1, if an ASN.1
70       * specification for this type of parameters exists.
71       *
72       * @param params the encoded parameters.
73       *
74       * @exception IOException on decoding errors
75       */
76      protected abstract void engineInit(byte[] params)
77          throws IOException;
78  
79      /**
80       * Imports the parameters from {@code params} and
81       * decodes them according to the specified decoding format.
82       * If {@code format} is null, the
83       * primary decoding format for parameters is used. The primary decoding
84       * format is ASN.1, if an ASN.1 specification for these parameters
85       * exists.
86       *
87       * @param params the encoded parameters.
88       *
89       * @param format the name of the decoding format.
90       *
91       * @exception IOException on decoding errors
92       */
93      protected abstract void engineInit(byte[] params, String format)
94          throws IOException;
95  
96      /**
97       * Returns a (transparent) specification of this parameters
98       * object.
99       * {@code paramSpec} identifies the specification class in which
100      * the parameters should be returned. It could, for example, be
101      * {@code DSAParameterSpec.class}, to indicate that the
102      * parameters should be returned in an instance of the
103      * {@code DSAParameterSpec} class.
104      *
105      * @param <T> the type of the parameter specification to be returned
106      *
107      * @param paramSpec the specification class in which
108      * the parameters should be returned.
109      *
110      * @return the parameter specification.
111      *
112      * @exception InvalidParameterSpecException if the requested parameter
113      * specification is inappropriate for this parameter object.
114      */
115     protected abstract
116         <T extends AlgorithmParameterSpec>
117         T engineGetParameterSpec(Class<T> paramSpec)
118         throws InvalidParameterSpecException;
119 
120     /**
121      * Returns the parameters in their primary encoding format.
122      * The primary encoding format for parameters is ASN.1, if an ASN.1
123      * specification for this type of parameters exists.
124      *
125      * @return the parameters encoded using their primary encoding format.
126      *
127      * @exception IOException on encoding errors.
128      */
129     protected abstract byte[] engineGetEncoded() throws IOException;
130 
131     /**
132      * Returns the parameters encoded in the specified format.
133      * If {@code format} is null, the
134      * primary encoding format for parameters is used. The primary encoding
135      * format is ASN.1, if an ASN.1 specification for these parameters
136      * exists.
137      *
138      * @param format the name of the encoding format.
139      *
140      * @return the parameters encoded using the specified encoding scheme.
141      *
142      * @exception IOException on encoding errors.
143      */
144     protected abstract byte[] engineGetEncoded(String format)
145         throws IOException;
146 
147     /**
148      * Returns a formatted string describing the parameters.
149      *
150      * @return a formatted string describing the parameters.
151      */
152     protected abstract String engineToString();
153 }