Package org.bouncycastle.bcpg

Class S2K

  • All Implemented Interfaces:
    org.bouncycastle.util.Encodable
    public class S2K
extends BCPGObject
    Parameter specifier for the PGP string-to-key password based key derivation function.

    In iterated mode, S2K takes a single byte iteration count specifier, which is converted to an actual iteration count using a formula that grows the iteration count exponentially as the byte value increases.

    e.g. 0x01 == 1088 iterations, and 0xFF == 65,011,712 iterations.

    • Field Detail

      • SIMPLE

        public static final int SIMPLE
        Deprecated.
        use SALTED_AND_ITERATED or ARGON_2 instead.
        Simple key generation. A single non-salted iteration of a hash function. This method is deprecated to use, since it can be brute-forced when used with a low-entropy string, such as those typically provided by users. Additionally, the usage of Simple S2K can lead to key and IV reuse. Therefore, in OpenPGP v6, Therefore, when generating an S2K specifier, an implementation MUST NOT use Simple S2K.
        See Also:
        Constant Field Values

      • SALTED

        public static final int SALTED
        Deprecated.
        use SALTED_AND_ITERATED or ARGON_2 instead.
        Salted key generation. A single iteration of a hash function with a (unique) salt. This method is deprecated to use, since it can be brute-forced when used with a low-entropy string, such as those typically provided by users. Therefore, in OpenPGP v6, an implementation SHOULD NOT generate a Salted S2K, unless the implementation knows that the input string is high-entropy.
        See Also:
        Constant Field Values

      • SALTED_AND_ITERATED

        public static final int SALTED_AND_ITERATED
        Salted and iterated key generation. Multiple iterations of a hash function, with a salt. This method MAY be used if ARGON_2 is not available.
        See Also:
        Constant Field Values

      • ARGON_2

        public static final int ARGON_2
        Memory-hard, salted key generation using Argon2 hash algorithm.
        See Also:
        Constant Field Values

      • GNU_PROTECTION_MODE_NO_PRIVATE_KEY

        public static final int GNU_PROTECTION_MODE_NO_PRIVATE_KEY
        See Also:
        Constant Field Values

      • GNU_PROTECTION_MODE_DIVERT_TO_CARD

        public static final int GNU_PROTECTION_MODE_DIVERT_TO_CARD
        See Also:
        Constant Field Values

    • Constructor Detail

      • S2K

        public S2K​(int algorithm)
        Constructs a specifier for a simple S2K generation.
        Parameters:
        algorithm - the digest algorithm to use.

      • S2K

        public S2K​(int algorithm,
           byte[] iv)
        Constructs a specifier for a salted S2K generation.
        Parameters:
        algorithm - the digest algorithm to use.
        iv - the salt to apply to input to the key generation.

      • S2K

        public S2K​(int algorithm,
           byte[] iv,
           int itCount)
        Constructs a specifier for a salted and iterated S2K generation.
        Parameters:
        algorithm - the digest algorithm to iterate.
        iv - the salt to apply to input to the key generation.
        itCount - the single byte iteration count specifier.

      • S2K

        public S2K​(S2K.GNUDummyParams gnuDummyParams)
        Construct a specifier for an S2K using the GNU_DUMMY_S2K method.
        Parameters:
        gnuDummyParams - GNU_DUMMY_S2K parameters

    • Method Detail

      • simpleS2K

        public static S2K simpleS2K​(int algorithm)
        Return a new S2K instance using the SIMPLE method, using the given hash 
        algorithm
        .
        Parameters:
        algorithm - hash algorithm tag
        Returns:
        S2K

      • saltedS2K

        public static S2K saltedS2K​(int algorithm,
                            byte[] salt)
        Return a new S2K instance using the SALTED method, using the given hash 
        algorithm
        and 
        salt
        .
        Parameters:
        algorithm - hash algorithm tag
        salt - salt
        Returns:
        S2K

      • saltedAndIteratedS2K

        public static S2K saltedAndIteratedS2K​(int algorithm,
                                       byte[] salt,
                                       int iterationCount)
        Return a new S2K instance using the SALTED_AND_ITERATED method, using the given hash 
        algorithm
        , 
        salt
        and 
        iterationCount
        .
        Parameters:
        algorithm - hash algorithm tag
        salt - salt
        iterationCount - number of iterations
        Returns:
        S2K

      • argon2S2K

        public static S2K argon2S2K​(S2K.Argon2Params parameters)
        Return a new S2K instance using the ARGON_2 method, using the given argon2 
        parameters
        .
        Parameters:
        parameters - argon2 parameters
        Returns:
        S2K

      • gnuDummyS2K

        public static S2K gnuDummyS2K​(S2K.GNUDummyParams parameters)
        Return a new S2K instance using the GNU_DUMMY_S2K method, using the given GNU Dummy S2K 
        parameters
        .
        Parameters:
        parameters - GNU Dummy S2K parameters
        Returns:
        S2K

      • getHashAlgorithm

        public int getHashAlgorithm()
        Gets the hash algorithm for this S2K.

      • getIV

        public byte[] getIV()
        Gets the iv/salt to use for the key generation.

      • getIterationCount

        public long getIterationCount()
        Gets the actual (expanded) iteration count.

      • getPasses

        public int getPasses()
        Return the number of passes - only Argon2
        Returns:
        number of passes

      • getProtectionMode

        public int getProtectionMode()
        Gets the protection mode - only if GNU_DUMMY_S2K

      • getParallelism

        public int getParallelism()
        Gets the degree of parallelism - only if ARGON_2
        Returns:
        parallelism

      • getMemorySizeExponent

        public int getMemorySizeExponent()
        Gets the memory size exponent - only if ARGON_2
        Returns:
        memory size exponent