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: InSIMPLE
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. TheSALTED
mode is likeSIMPLE
, but uses an additional salt value. This mode is deprecated and MUST NOT be generated. InSALTED_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. TheSALTED_AND_ITERATED
mode uses both iteration and a salt value. This mode is recommended for applications that want to stay backwards compatible. The newARGON_2
mode does key derivation using salted Argon2, which is a memory-hard hash algorithm. This mode is generally recommended overSALTED_AND_ITERATED
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
S2K.Argon2Params
Parameters for Argon2 S2K.static class
S2K.GNUDummyParams
Parameters for theGNU_DUMMY_S2K
method.
-
Field Summary
Fields Modifier and Type Field Description 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.useSALTED_AND_ITERATED
orARGON_2
instead.static int
SALTED_AND_ITERATED
Salted and iterated key generation.static int
SIMPLE
Deprecated.useSALTED_AND_ITERATED
orARGON_2
instead.
-
Constructor Summary
Constructors Constructor Description S2K(int algorithm)
Constructs a specifier for asimple
S2K generation.S2K(int algorithm, byte[] iv)
Constructs a specifier for asalted
S2K generation.S2K(int algorithm, byte[] iv, int itCount)
Constructs a specifier for asalted and iterated
S2K generation.S2K(S2K.Argon2Params argon2Params)
Constructs a specifier for anS2K method using Argon2
.S2K(S2K.GNUDummyParams gnuDummyParams)
Construct a specifier for an S2K using theGNU_DUMMY_S2K
method.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static S2K
argon2S2K(S2K.Argon2Params parameters)
Return a new S2K instance using theARGON_2
method, using the given argon2 parametersvoid
encode(BCPGOutputStream out)
Encode the packet into the givenBCPGOutputStream
.int
getHashAlgorithm()
Gets thehash 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 theGNU_DUMMY_S2K
method, using the given GNU Dummy S2K parametersstatic S2K
saltedAndIteratedS2K(int algorithm, byte[] salt, int iterationCount)
Return a new S2K instance using theSALTED_AND_ITERATED
method, using the given hash algorithmstatic S2K
saltedS2K(int algorithm, byte[] salt)
Return a new S2K instance using theSALTED
method, using the given hash algorithmstatic S2K
simpleS2K(int algorithm)
Return a new S2K instance using theSIMPLE
method, using the given hash algorithm-
Methods inherited from class org.bouncycastle.bcpg.BCPGObject
getEncoded
-
-
-
-
Field Detail
-
SIMPLE
public static final int SIMPLE
Deprecated.useSALTED_AND_ITERATED
orARGON_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.useSALTED_AND_ITERATED
orARGON_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 ifARGON_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:
S2K.Argon2Params
, Constant Field Values
-
GNU_DUMMY_S2K
public static final int GNU_DUMMY_S2K
GNU S2K extension.- See Also:
S2K.GNUDummyParams
, Constant Field Values
-
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
, Constant Field Values
-
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
, Constant Field Values
-
GNU_PROTECTION_MODE_INTERNAL
public static final int GNU_PROTECTION_MODE_INTERNAL
The (GnuPG) internal representation of a private key.- See Also:
S2K.GNUDummyParams
, Constant Field Values
-
-
Constructor Detail
-
S2K
public S2K(int algorithm)
Constructs a specifier for asimple
S2K generation.- Parameters:
algorithm
- thedigest algorithm
to use.
-
S2K
public S2K(int algorithm, byte[] iv)
Constructs a specifier for asalted
S2K generation.- Parameters:
algorithm
- thedigest 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 asalted and iterated
S2K generation.- Parameters:
algorithm
- thedigest 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 anS2K method using Argon2
.- Parameters:
argon2Params
- argon2 parameters
-
S2K
public S2K(S2K.GNUDummyParams gnuDummyParams)
Construct a specifier for an S2K using theGNU_DUMMY_S2K
method.- Parameters:
gnuDummyParams
- GNU_DUMMY_S2K parameters
-
-
Method Detail
-
simpleS2K
public static S2K simpleS2K(int algorithm)
Return a new S2K instance using theSIMPLE
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 theSALTED
method, using the given hash algorithm and salt.- Parameters:
algorithm
- hash algorithm tagsalt
- salt- Returns:
- S2K
-
saltedAndIteratedS2K
public static S2K saltedAndIteratedS2K(int algorithm, byte[] salt, int iterationCount)
Return a new S2K instance using theSALTED_AND_ITERATED
method, using the given hash algorithm, salt and iterationCount.- Parameters:
algorithm
- hash algorithm tagsalt
- saltiterationCount
- number of iterations- Returns:
- S2K
-
argon2S2K
public static S2K argon2S2K(S2K.Argon2Params parameters)
Return a new S2K instance using theARGON_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 theGNU_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()
- 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 S2Ktype
:SIMPLE
: nullSALTED
: 8 octetsSALTED_AND_ITERATED
: 8 octetsARGON_2
: 16 octets- Returns:
- IV
-
getIterationCount
public long getIterationCount()
Gets the actual (expanded) iteration count. Only used forSALTED_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 givenBCPGOutputStream
.- Specified by:
encode
in classBCPGObject
- Parameters:
out
- packet output stream- Throws:
java.io.IOException
-
-