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:

RFC4880 - String-to-Key (S2K) Specifiers, RFC9580 - String-to-Key (S2K) Specifier, LibrePGP - String-to-Key (S2K) Specifiers

Inner Class Summary

static class	S2K.Argon2Params Parameters for Argon2 S2K.
static class	S2K.GNUDummyParams Parameters for the GNU_DUMMY_S2K method.

Field Summary

static int	ARGON_2 Memory-hard, salted key generation using Argon2 hash algorithm.
static int	GNU_DUMMY_S2K GNU S2K extension.
static int	GNU_PROTECTION_MODE_DIVERT_TO_CARD A stub to access smartcards.
static int	GNU_PROTECTION_MODE_INTERNAL The (GnuPG) internal representation of a private key.
static int	GNU_PROTECTION_MODE_NO_PRIVATE_KEY Do not store the secret part at all.
static int	SALTED Deprecated. use SALTED_AND_ITERATED or ARGON_2 instead.
static int	SALTED_AND_ITERATED Salted and iterated key generation.
static int	SIMPLE Deprecated. use SALTED_AND_ITERATED or ARGON_2 instead.

Constructor Summary

S2K(int algorithm)
Constructs a specifier for a simple S2K generation.

S2K(int algorithm, byte[] iv)
Constructs a specifier for a salted S2K generation.

S2K(int algorithm, byte[] iv, int itCount)
Constructs a specifier for a salted and iterated S2K generation.

S2K(S2K.Argon2Params argon2Params)
Constructs a specifier for an S2K method using Argon2.

S2K(S2K.GNUDummyParams gnuDummyParams)
Construct a specifier for an S2K using the GNU_DUMMY_S2K method.

Method Summary

static S2K	argon2S2K(S2K.Argon2Params parameters) Return a new S2K instance using the ARGON_2 method, using the given argon2 parameters
void	encode(BCPGOutputStream out) Encode the packet into the given BCPGOutputStream.
int	getHashAlgorithm() Gets the hash algorithm for this S2K.
long	getIterationCount() Gets the actual (expanded) iteration count.
byte[]	getIV() Gets the iv/salt to use for the key generation.
int	getMemorySizeExponent() Gets the memory size exponent - only if ARGON_2.
int	getParallelism() Gets the degree of parallelism - only if ARGON_2.
int	getPasses() Return the number of passes - only Argon2.
int	getProtectionMode() Gets the protection mode - only if GNU_DUMMY_S2K.
int	getType() Gets the S2K specifier type.
static S2K	gnuDummyS2K(S2K.GNUDummyParams parameters) Return a new S2K instance using the GNU_DUMMY_S2K method, using the given GNU Dummy S2K parameters
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
static S2K	saltedS2K(int algorithm, byte[] salt) Return a new S2K instance using the SALTED method, using the given hash algorithm
static S2K	simpleS2K(int algorithm) Return a new S2K instance using the SIMPLE method, using the given hash algorithm

Methods inherited from class org.bouncycastle.bcpg.BCPGObject

getEncoded

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

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.

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.

ARGON_2

public static final int ARGON_2

Memory-hard, salted key generation using Argon2 hash algorithm.

See Also:

S2K.Argon2Params

GNU_DUMMY_S2K

public static final int GNU_DUMMY_S2K

GNU S2K extension.

See Also:

S2K.GNUDummyParams

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:

S2K.GNUDummyParams

GNU_PROTECTION_MODE_DIVERT_TO_CARD

public static final int GNU_PROTECTION_MODE_DIVERT_TO_CARD

A stub to access smartcards.

See Also:

S2K.GNUDummyParams

GNU_PROTECTION_MODE_INTERNAL

public static final int GNU_PROTECTION_MODE_INTERNAL

The (GnuPG) internal representation of a private key.

See Also:

S2K.GNUDummyParams

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.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 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

getType

public int getType()

Gets the S2K specifier type.

Returns:

type

See Also:

SIMPLE, SALTED, SALTED_AND_ITERATED, ARGON_2

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: SIMPLE: null SALTED: 8 octets SALTED_AND_ITERATED: 8 octets ARGON_2: 16 octets

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:

GNU_PROTECTION_MODE_NO_PRIVATE_KEY, GNU_PROTECTION_MODE_DIVERT_TO_CARD

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 java.io.IOException

Encode the packet into the given BCPGOutputStream.

Overrides:

encode in class BCPGObject

Parameters:

out - packet output stream

Throws:

java.io.IOException -