Top Description Inners Fields Constructors Methods
org.bouncycastle.bcpg

public Class S2K

extends BCPGObject
Class Inheritance
Imports
java.io.DataInputStream, .IOException, .InputStream, java.security.SecureRandom, org.bouncycastle.crypto.CryptoServicesRegistrar

Parameter specifier for the PGP string-to-key password based key derivation function. There are different S2K modes:
See Also
RFC4880 - String-to-Key (S2K) Specifiers, RFC9580 - String-to-Key (S2K) Specifier, LibrePGP - String-to-Key (S2K) Specifiers

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
S2K.Argon2Params

Parameters for Argon2 S2K.

public static class
S2K.GNUDummyParams

Parameters for the GNU_DUMMY_S2K method.

Field Summary

Modifier and TypeField and Description
pack-priv int
public static final int
ARGON_2

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

private static final int
public static final int
GNU_DUMMY_S2K

GNU S2K extension.

public static final int
GNU_PROTECTION_MODE_DIVERT_TO_CARD

A stub to access smartcards.

public static final int
GNU_PROTECTION_MODE_INTERNAL

The (GnuPG) internal representation of a private key.

public static final int
GNU_PROTECTION_MODE_NO_PRIVATE_KEY

Do not store the secret part at all.

pack-priv int
pack-priv byte[]
pack-priv int
pack-priv int
pack-priv int
pack-priv int
public static final int
SALTED

Deprecated use SALTED_AND_ITERATED or ARGON_2 instead.
Salted key generation.
public static final int
SALTED_AND_ITERATED

Salted and iterated key generation.

public static final int
SIMPLE

Deprecated use SALTED_AND_ITERATED or ARGON_2 instead.
Simple key generation.
pack-priv int

Constructor Summary

AccessConstructor and Description
pack-priv
S2K(InputStream
packet input stream
in
)

Parse an S2K specifier from an OpenPGP packet input stream.

public
S2K(int
the digest algorithm to use.
algorithm
)

Constructs a specifier for a simple S2K generation.

public
S2K(int
the digest algorithm to use.
algorithm
,
byte[]
the salt to apply to input to the key generation.
iv
)

Constructs a specifier for a salted S2K generation.

public
S2K(int
the digest algorithm to iterate.
algorithm
,
byte[]
the salt to apply to input to the key generation.
iv
,
int
the single byte iteration count specifier.
itCount
)

Constructs a specifier for a salted and iterated S2K generation.

public
S2K(S2K.Argon2Params
argon2 parameters
argon2Params
)

Constructs a specifier for an S2K method using Argon2.

public
S2K(S2K.GNUDummyParams
GNU_DUMMY_S2K parameters
gnuDummyParams
)

Construct a specifier for an S2K using the GNU_DUMMY_S2K method.

Method Summary

Modifier and TypeMethod and Description
public static S2K

Returns:

S2K
argon2S2K
(S2K.Argon2Params
argon2 parameters
parameters
)

Return a new S2K instance using the ARGON_2 method, using the given argon2

parameters
public void
encode(BCPGOutputStream
packet output stream
out
)

Implements abstract org.bouncycastle.bcpg.BCPGObject.encode.

Encode the packet into the given BCPGOutputStream.

public int

Returns:

hash algorithm
getHashAlgorithm
()

Gets the hash algorithm for this S2K.

public long

Returns:

iteration count
getIterationCount
()

Gets the actual (expanded) iteration count.

public byte[]

Returns:

IV
getIV
()

Gets the iv/salt to use for the key generation.

public int

Returns:

memory size exponent
getMemorySizeExponent
()

Gets the memory size exponent - only if ARGON_2.

public int

Returns:

parallelism
getParallelism
()

Gets the degree of parallelism - only if ARGON_2.

public int

Returns:

number of passes
getPasses
()

Return the number of passes - only Argon2.

public int

Returns:

GNU dummy-s2k protection mode
getProtectionMode
()

Gets the protection mode - only if GNU_DUMMY_S2K.

public int

Returns:

type
getType
()

Gets the S2K specifier type.

public static S2K

Returns:

S2K
gnuDummyS2K
(S2K.GNUDummyParams
GNU Dummy S2K parameters
parameters
)

Return a new S2K instance using the GNU_DUMMY_S2K method, using the given GNU Dummy S2K

parameters
public static S2K

Returns:

S2K
saltedAndIteratedS2K
(int
hash algorithm tag
algorithm
,
byte[]
salt
salt
,
int
number of iterations
iterationCount
)

Return a new S2K instance using the SALTED_AND_ITERATED method, using the given hash

algorithm
public static S2K

Returns:

S2K
saltedS2K
(int
hash algorithm tag
algorithm
,
byte[]
salt
salt
)

Return a new S2K instance using the SALTED method, using the given hash

algorithm
public static S2K

Returns:

S2K
simpleS2K
(int
hash algorithm tag
algorithm
)

Return a new S2K instance using the SIMPLE method, using the given hash

algorithm
private void
writeOneOctetOrThrow(BCPGOutputStream
output stream
out
,
int
value
val
,
String
name of the value for the error message
valName
)

Throw an IllegalArgumentException if the value cannot be encoded, otherwise write the value to the output stream.

Inherited from org.bouncycastle.bcpg.BCPGObject:
getEncoded

Field Detail

algorithmback to summary
pack-priv int algorithm
ARGON_2back to summary
public static final int ARGON_2

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

See Also
Argon2Params
EXPBIASback to summary
private static final int EXPBIAS
GNU_DUMMY_S2Kback to summary
public static final int GNU_DUMMY_S2K

GNU S2K extension.

See Also
GNUDummyParams
GNU_PROTECTION_MODE_DIVERT_TO_CARDback to summary
public static final int GNU_PROTECTION_MODE_DIVERT_TO_CARD

A stub to access smartcards.

See Also
GNUDummyParams
GNU_PROTECTION_MODE_INTERNALback to summary
public static final int GNU_PROTECTION_MODE_INTERNAL

The (GnuPG) internal representation of a private key.

See Also
GNUDummyParams
GNU_PROTECTION_MODE_NO_PRIVATE_KEYback to summary
public static final int GNU_PROTECTION_MODE_NO_PRIVATE_KEY

Do not store the secret part at all.

See Also
GNUDummyParams
itCountback to summary
pack-priv int itCount
ivback to summary
pack-priv byte[] iv
memorySizeExponentback to summary
pack-priv int memorySizeExponent
parallelismback to summary
pack-priv int parallelism
passesback to summary
pack-priv int passes
protectionModeback to summary
pack-priv int protectionMode
SALTEDback to summary
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_ITERATEDback to summary
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.

SIMPLEback to summary
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.

typeback to summary
pack-priv int type

Constructor Detail

S2Kback to summary
pack-priv S2K(InputStream in) throws IOException

Parse an S2K specifier from an OpenPGP packet input stream.

Parameters
in:InputStream

packet input stream

Exceptions
UnsupportedPacketVersionException:
if an unsupported S2K type is encountered
S2Kback to summary
public S2K(int algorithm)

Constructs a specifier for a simple S2K generation.

Parameters
algorithm:int

the digest algorithm to use.

S2Kback to summary
public S2K(int algorithm, byte[] iv)

Constructs a specifier for a salted S2K generation.

Parameters
algorithm:int

the digest algorithm to use.

iv:byte[]

the salt to apply to input to the key generation.

S2Kback to summary
public S2K(int algorithm, byte[] iv, int itCount)

Constructs a specifier for a salted and iterated S2K generation.

Parameters
algorithm:int

the digest algorithm to iterate.

iv:byte[]

the salt to apply to input to the key generation.

itCount:int

the single byte iteration count specifier.

S2Kback to summary
public S2K(S2K.Argon2Params argon2Params)

Constructs a specifier for an S2K method using Argon2.

Parameters
argon2Params:S2K.Argon2Params

argon2 parameters

S2Kback to summary
public S2K(S2K.GNUDummyParams gnuDummyParams)

Construct a specifier for an S2K using the GNU_DUMMY_S2K method.

Parameters
gnuDummyParams:S2K.GNUDummyParams

GNU_DUMMY_S2K parameters

Method Detail

argon2S2Kback to summary
public static S2K argon2S2K(S2K.Argon2Params parameters)

Return a new S2K instance using the ARGON_2 method, using the given argon2

parameters
.
Parameters
parameters:S2K.Argon2Params

argon2 parameters

Returns:S2K

S2K

encodeback to summary
public void encode(BCPGOutputStream out) throws IOException

Implements abstract org.bouncycastle.bcpg.BCPGObject.encode.

Encode the packet into the given BCPGOutputStream.

Parameters
out:BCPGOutputStream

packet output stream

getHashAlgorithmback to summary
public int getHashAlgorithm()

Gets the hash algorithm for this S2K. Only used for SIMPLE, SALTED, SALTED_AND_ITERATED

Returns:int

hash algorithm

getIterationCountback to summary
public long getIterationCount()

Gets the actual (expanded) iteration count. Only used for SALTED_AND_ITERATED.

Returns:long

iteration count

getIVback to summary
public byte[] getIV()

Gets the iv/salt to use for the key generation. The value of this field depends on the S2K type:

Returns:byte[]

IV

getMemorySizeExponentback to summary
public int getMemorySizeExponent()

Gets the memory size exponent - only if ARGON_2.

Returns:int

memory size exponent

getParallelismback to summary
public int getParallelism()

Gets the degree of parallelism - only if ARGON_2.

Returns:int

parallelism

getPassesback to summary
public int getPasses()

Return the number of passes - only Argon2.

Returns:int

number of passes

getProtectionModeback to summary
public int getProtectionMode()

Gets the protection mode - only if GNU_DUMMY_S2K.

Returns:int

GNU dummy-s2k protection mode

See Also
GNU_PROTECTION_MODE_NO_PRIVATE_KEY, GNU_PROTECTION_MODE_DIVERT_TO_CARD
getTypeback to summary
public int getType()

Gets the S2K specifier type.

Returns:int

type

See Also
SIMPLE, SALTED, SALTED_AND_ITERATED, ARGON_2
gnuDummyS2Kback to summary
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:S2K.GNUDummyParams

GNU Dummy S2K parameters

Returns:S2K

S2K

saltedAndIteratedS2Kback to summary
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:int

hash algorithm tag

salt:byte[]

salt

iterationCount:int

number of iterations

Returns:S2K

S2K

saltedS2Kback to summary
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:int

hash algorithm tag

salt:byte[]

salt

Returns:S2K

S2K

simpleS2Kback to summary
public static S2K simpleS2K(int algorithm)

Return a new S2K instance using the SIMPLE method, using the given hash

algorithm
.
Parameters
algorithm:int

hash algorithm tag

Returns:S2K

S2K

writeOneOctetOrThrowback to summary
private void writeOneOctetOrThrow(BCPGOutputStream out, int val, String valName) throws IOException

Throw an IllegalArgumentException if the value cannot be encoded, otherwise write the value to the output stream.

Parameters
out:BCPGOutputStream

output stream

val:int

value

valName:String

name of the value for the error message

Exceptions
IOException:
potentially thrown by BCPGOutputStream#write(int)
IllegalArgumentException:
if the value cannot be encoded
org.bouncycastle.bcpg back to summary

public Class S2K.Argon2Params

extends Object
Class Inheritance

Parameters for Argon2 S2K.
See Also
OpenPGP - Argon2

Field Summary

Modifier and TypeField and Description
private final int
private final int
private final int
private final byte[]

Constructor Summary

AccessConstructor and Description
public
Argon2Params()

Uniformly safe and recommended parameters not tailored to any hardware.

public
Argon2Params(SecureRandom secureRandom)

Uniformly safe and recommended parameters not tailored to any hardware.

public
Argon2Params(int
number of iterations, must be greater than 0
passes
,
int
number of lanes, must be greater 0
parallelism
,
int
exponent for memory consumption, must be between
3 + ⌈log₂p⌉
and
31
memSizeExp
,
SecureRandom
secure random generator to initialize the salt vector
secureRandom
)

Create customized Argon2 S2K parameters.

public
Argon2Params(byte[]
16 bytes of random salt
salt
,
int
number of iterations, must be greater than 0
passes
,
int
number of lanes, must be greater 0
parallelism
,
int
exponent for memory consumption, must be between
3 + ⌈log₂p⌉
and
31
memSizeExp
)

Create customized Argon2 S2K parameters.

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

memory size exponent
getMemSizeExp
()

Return the exponent indicating the memory size

m
public int

Returns:

parallelism
getParallelism
()

Return the factor of parallelism

p
public int

Returns:

number of passes
getPasses
()

Return the number of passes

t
public byte[]

Returns:

salt
getSalt
()

Return a 16-byte byte array containing the salt

S
public static S2K.Argon2Params

Returns:

safe parameters for memory constrained environments
memoryConstrainedParameters
()

Recommended parameters for memory constrained environments (64MiB RAM).

private static byte[]

Returns:

salt
mineSalt
(SecureRandom
random number generator instance
secureRandom
)

Generate 16 bytes of random salt.

public static S2K.Argon2Params
universallyRecommendedParameters()

Uniformly safe and recommended parameters not tailored to any hardware.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

memSizeExpback to summary
private final int memSizeExp
parallelismback to summary
private final int parallelism
passesback to summary
private final int passes
saltback to summary
private final byte[] salt

Constructor Detail

Argon2Paramsback to summary
public Argon2Params()

Uniformly safe and recommended parameters not tailored to any hardware. Uses Argon2id, 1 pass, 4 parallelism, 2 GiB RAM.

See Also
RFC 9106: §4. Parameter Choice
Argon2Paramsback to summary
public Argon2Params(SecureRandom secureRandom)

Uniformly safe and recommended parameters not tailored to any hardware. Uses Argon2id, 1 pass, 4 parallelism, 2 GiB RAM.

See Also
RFC 9106: §4. Parameter Choice
Argon2Paramsback to summary
public Argon2Params(int passes, int parallelism, int memSizeExp, SecureRandom secureRandom)

Create customized Argon2 S2K parameters.

Parameters
passes:int

number of iterations, must be greater than 0

parallelism:int

number of lanes, must be greater 0

memSizeExp:int

exponent for memory consumption, must be between

3 + ⌈log₂p⌉
and
31
secureRandom:SecureRandom

secure random generator to initialize the salt vector

Argon2Paramsback to summary
public Argon2Params(byte[] salt, int passes, int parallelism, int memSizeExp)

Create customized Argon2 S2K parameters.

Parameters
salt:byte[]

16 bytes of random salt

passes:int

number of iterations, must be greater than 0

parallelism:int

number of lanes, must be greater 0

memSizeExp:int

exponent for memory consumption, must be between

3 + ⌈log₂p⌉
and
31

Method Detail

getMemSizeExpback to summary
public int getMemSizeExp()

Return the exponent indicating the memory size

m
.
Returns:int

memory size exponent

getParallelismback to summary
public int getParallelism()

Return the factor of parallelism

p
.
Returns:int

parallelism

getPassesback to summary
public int getPasses()

Return the number of passes

t
.
Returns:int

number of passes

getSaltback to summary
public byte[] getSalt()

Return a 16-byte byte array containing the salt

S
.
Returns:byte[]

salt

memoryConstrainedParametersback to summary
public static S2K.Argon2Params memoryConstrainedParameters()

Recommended parameters for memory constrained environments (64MiB RAM). Uses Argon2id with 3 passes, 4 lanes and 64 MiB RAM.

Returns:S2K.Argon2Params

safe parameters for memory constrained environments

See Also
RFC9106: §4. Parameter Choice
mineSaltback to summary
private static byte[] mineSalt(SecureRandom secureRandom)

Generate 16 bytes of random salt.

Parameters
secureRandom:SecureRandom

random number generator instance

Returns:byte[]

salt

universallyRecommendedParametersback to summary
public static S2K.Argon2Params universallyRecommendedParameters()

Uniformly safe and recommended parameters not tailored to any hardware. Uses Argon2id, 1 pass, 4 parallelism, 2 GiB RAM.

See Also
RFC 9106: §4. Parameter Choice
org.bouncycastle.bcpg back to summary

public Class S2K.GNUDummyParams

extends Object
Class Inheritance

Parameters for the GNU_DUMMY_S2K method.
See Also
GNU extensions to the S2K algorithm

Field Summary

Modifier and TypeField and Description
private final int

Constructor Summary

AccessConstructor and Description
private
GNUDummyParams(int protectionMode)

Method Summary

Modifier and TypeMethod and Description
public static S2K.GNUDummyParams

Returns:

params
divertToCard
()

Factory method for a GNU Dummy S2K indicating a private key located on a smart card.

public int

Returns:

protection method
getProtectionMode
()

Return the GNU Dummy S2K protection method.

public static S2K.GNUDummyParams

Returns:

params
internal
()

Factory method for a GNU Dummy S2K indicating an internal private key.

public static S2K.GNUDummyParams

Returns:

params
noPrivateKey
()

Factory method for a GNU Dummy S2K indicating a missing private key.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

protectionModeback to summary
private final int protectionMode

Constructor Detail

GNUDummyParamsback to summary
private GNUDummyParams(int protectionMode)

Method Detail

divertToCardback to summary
public static S2K.GNUDummyParams divertToCard()

Factory method for a GNU Dummy S2K indicating a private key located on a smart card.

Returns:S2K.GNUDummyParams

params

getProtectionModeback to summary
public int getProtectionMode()

Return the GNU Dummy S2K protection method.

Returns:int

protection method

internalback to summary
public static S2K.GNUDummyParams internal()

Factory method for a GNU Dummy S2K indicating an internal private key.

Returns:S2K.GNUDummyParams

params

noPrivateKeyback to summary
public static S2K.GNUDummyParams noPrivateKey()

Factory method for a GNU Dummy S2K indicating a missing private key.

Returns:S2K.GNUDummyParams

params