Home | History | Annotate | Download | only in spec 
      1 /*
      2  * Copyright (c) 2001, 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.spec;
     27 
     28 import java.math.BigInteger;
     29 import java.security.spec.MGF1ParameterSpec;
     30 
     31 /**
     32  * This class specifies a parameter spec for RSA-PSS signature scheme,
     33  * as defined in the
     34  * <a href="http://www.ietf.org/rfc/rfc3447.txt">PKCS#1 v2.1</a>
     35  * standard.
     36  *
     37  * <p>Its ASN.1 definition in PKCS#1 standard is described below:
     38  * <pre>
     39  * RSASSA-PSS-params ::= SEQUENCE {
     40  *   hashAlgorithm      [0] OAEP-PSSDigestAlgorithms  DEFAULT sha1,
     41  *   maskGenAlgorithm   [1] PKCS1MGFAlgorithms  DEFAULT mgf1SHA1,
     42  *   saltLength         [2] INTEGER  DEFAULT 20,
     43  *   trailerField       [3] INTEGER  DEFAULT 1
     44  * }
     45  * </pre>
     46  * where
     47  * <pre>
     48  * OAEP-PSSDigestAlgorithms    ALGORITHM-IDENTIFIER ::= {
     49  *   { OID id-sha1 PARAMETERS NULL   }|
     50  *   { OID id-sha224 PARAMETERS NULL   }|
     51  *   { OID id-sha256 PARAMETERS NULL }|
     52  *   { OID id-sha384 PARAMETERS NULL }|
     53  *   { OID id-sha512 PARAMETERS NULL },
     54  *   ...  -- Allows for future expansion --
     55  * }
     56  *
     57  * PKCS1MGFAlgorithms    ALGORITHM-IDENTIFIER ::= {
     58  *   { OID id-mgf1 PARAMETERS OAEP-PSSDigestAlgorithms },
     59  *   ...  -- Allows for future expansion --
     60  * }
     61  * </pre>
     62  * <p>Note: the PSSParameterSpec.DEFAULT uses the following:
     63  *     message digest  -- "SHA-1"
     64  *     mask generation function (mgf) -- "MGF1"
     65  *     parameters for mgf -- MGF1ParameterSpec.SHA1
     66  *     SaltLength   -- 20
     67  *     TrailerField -- 1
     68  *
     69  * @see MGF1ParameterSpec
     70  * @see AlgorithmParameterSpec
     71  * @see java.security.Signature
     72  *
     73  * @author Valerie Peng
     74  *
     75  *
     76  * @since 1.4
     77  */
     78 
     79 public class PSSParameterSpec implements AlgorithmParameterSpec {
     80 
     81     private String mdName = "SHA-1";
     82     private String mgfName = "MGF1";
     83     private AlgorithmParameterSpec mgfSpec = MGF1ParameterSpec.SHA1;
     84     private int saltLen = 20;
     85     private int trailerField = 1;
     86 
     87     /**
     88      * The PSS parameter set with all default values.
     89      * @since 1.5
     90      */
     91     public static final PSSParameterSpec DEFAULT = new PSSParameterSpec();
     92 
     93     /**
     94      * Constructs a new {@code PSSParameterSpec} as defined in
     95      * the PKCS #1 standard using the default values.
     96      */
     97     private PSSParameterSpec() {
     98     }
     99 
    100     /**
    101      * Creates a new {@code PSSParameterSpec} as defined in
    102      * the PKCS #1 standard using the specified message digest,
    103      * mask generation function, parameters for mask generation
    104      * function, salt length, and trailer field values.
    105      *
    106      * @param mdName the algorithm name of the hash function.
    107      * @param mgfName the algorithm name of the mask generation
    108      * function.
    109      * @param mgfSpec the parameters for the mask generation
    110      * function. If null is specified, null will be returned by
    111      * getMGFParameters().
    112      * @param saltLen the length of salt.
    113      * @param trailerField the value of the trailer field.
    114      * @exception NullPointerException if {@code mdName},
    115      * or {@code mgfName} is null.
    116      * @exception IllegalArgumentException if {@code saltLen}
    117      * or {@code trailerField} is less than 0.
    118      * @since 1.5
    119      */
    120     public PSSParameterSpec(String mdName, String mgfName,
    121                             AlgorithmParameterSpec mgfSpec,
    122                             int saltLen, int trailerField) {
    123         if (mdName == null) {
    124             throw new NullPointerException("digest algorithm is null");
    125         }
    126         if (mgfName == null) {
    127             throw new NullPointerException("mask generation function " +
    128                                            "algorithm is null");
    129         }
    130         if (saltLen < 0) {
    131             throw new IllegalArgumentException("negative saltLen value: " +
    132                                                saltLen);
    133         }
    134         if (trailerField < 0) {
    135             throw new IllegalArgumentException("negative trailerField: " +
    136                                                trailerField);
    137         }
    138         this.mdName = mdName;
    139         this.mgfName = mgfName;
    140         this.mgfSpec = mgfSpec;
    141         this.saltLen = saltLen;
    142         this.trailerField = trailerField;
    143     }
    144 
    145     /**
    146      * Creates a new {@code PSSParameterSpec}
    147      * using the specified salt length and other default values as
    148      * defined in PKCS#1.
    149      *
    150      * @param saltLen the length of salt in bits to be used in PKCS#1
    151      * PSS encoding.
    152      * @exception IllegalArgumentException if {@code saltLen} is
    153      * less than 0.
    154      */
    155     public PSSParameterSpec(int saltLen) {
    156         if (saltLen < 0) {
    157             throw new IllegalArgumentException("negative saltLen value: " +
    158                                                saltLen);
    159         }
    160         this.saltLen = saltLen;
    161     }
    162 
    163     /**
    164      * Returns the message digest algorithm name.
    165      *
    166      * @return the message digest algorithm name.
    167      * @since 1.5
    168      */
    169     public String getDigestAlgorithm() {
    170         return mdName;
    171     }
    172 
    173     /**
    174      * Returns the mask generation function algorithm name.
    175      *
    176      * @return the mask generation function algorithm name.
    177      *
    178      * @since 1.5
    179      */
    180     public String getMGFAlgorithm() {
    181         return mgfName;
    182     }
    183 
    184     /**
    185      * Returns the parameters for the mask generation function.
    186      *
    187      * @return the parameters for the mask generation function.
    188      * @since 1.5
    189      */
    190     public AlgorithmParameterSpec getMGFParameters() {
    191         return mgfSpec;
    192     }
    193 
    194     /**
    195      * Returns the salt length in bits.
    196      *
    197      * @return the salt length.
    198      */
    199     public int getSaltLength() {
    200         return saltLen;
    201     }
    202 
    203     /**
    204      * Returns the value for the trailer field, i.e. bc in PKCS#1 v2.1.
    205      *
    206      * @return the value for the trailer field, i.e. bc in PKCS#1 v2.1.
    207      * @since 1.5
    208      */
    209     public int getTrailerField() {
    210         return trailerField;
    211     }
    212 }
    213