Package org.bouncycastle.bcpg

Class S2K

java.lang.Object
org.bouncycastle.bcpg.BCPGObject
org.bouncycastle.bcpg.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. There are different S2K modes:
  • In SIMPLE mode, a single iteration of the hash algorithm is performed to derived a key from the given passphrase. This mode is deprecated and MUST NOT be generated.
  • The SALTED mode is like SIMPLE, but uses an additional salt value. This mode is deprecated and MUST NOT be generated.
  • In SALTED_AND_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.
  • The SALTED_AND_ITERATED mode uses both iteration and a salt value. This mode is recommended for applications that want to stay backwards compatible.
  • The new ARGON_2 mode does key derivation using salted Argon2, which is a memory-hard hash algorithm. This mode is generally recommended over SALTED_AND_ITERATED.
See Also:

  • Field Details

    • 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:

    • 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:

    • 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:

    • ARGON_2

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

    • GNU_DUMMY_S2K

      public static final int GNU_DUMMY_S2K
      GNU S2K extension.
      See Also:

    • GNU_PROTECTION_MODE_NO_PRIVATE_KEY

      public static final int GNU_PROTECTION_MODE_NO_PRIVATE_KEY
      Do not store the secret part at all.
      See Also:

    • GNU_PROTECTION_MODE_DIVERT_TO_CARD

      public static final int GNU_PROTECTION_MODE_DIVERT_TO_CARD
      A stub to access smartcards.
      See Also:

    • GNU_PROTECTION_MODE_INTERNAL

      public static final int GNU_PROTECTION_MODE_INTERNAL
      The (GnuPG) internal representation of a private key.
      See Also:

  • Constructor Details

    • 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.Argon2Params argon2Params)
      Constructs a specifier for an S2K method using Argon2.
      Parameters:
      argon2Params - argon2 parameters

    • 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 Details

    • 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

    • getType

      public int getType()
      Gets the S2K specifier type.
      Returns:
      type
      See Also:

    • getHashAlgorithm

      public int getHashAlgorithm()
      Gets the hash algorithm for this S2K. Only used for SIMPLE, SALTED, SALTED_AND_ITERATED
      Returns:
      hash algorithm

    • getIV

      public byte[] getIV()
      Gets the iv/salt to use for the key generation. The value of this field depends on the S2K type:
      Returns:
      IV

    • getIterationCount

      public long getIterationCount()
      Gets the actual (expanded) iteration count. Only used for SALTED_AND_ITERATED.
      Returns:
      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.
      Returns:
      GNU dummy-s2k protection mode
      See Also:

    • 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

    • encode

      public void encode(BCPGOutputStream out) throws IOException
      Encode the packet into the given BCPGOutputStream.
      Specified by:
      encode in class BCPGObject
      Parameters:
      out - packet output stream
      Throws:
      IOException