S2K (Bouncy Castle Library 1.84 API Specification)

java.lang.Object
- org.bouncycastle.bcpg.BCPGObject
- - org.bouncycastle.bcpg.S2K

All Implemented Interfaces:

org.bouncycastle.util.Encodable

Direct Known Subclasses:

GnuExtendedS2K
```
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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class S2K.Argon2Params
Parameters for Argon2 S2K.

static class S2K.GNUDummyParams
Parameters for the GNU_DUMMY_S2K method.

Nested Classes
Modifier and Type	Class and Description
`static class`	`S2K.Argon2Params` Parameters for Argon2 S2K.
`static class`	`S2K.GNUDummyParams` Parameters for the `GNU_DUMMY_S2K` method.

Field Summary

Fields
Modifier and Type	Field and 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. 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

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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, salt and iterationCount.
`static S2K`	`saltedS2K(int algorithm, byte[] salt)` Return a new S2K instance using the `SALTED` method, using the given hash algorithm and salt.
`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, 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:
    
    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 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.
    
    Specified by:
    
    encode in class BCPGObject
    
    Parameters:
    
    out - packet output stream
    
    Throws:
    
    java.io.IOException

Class S2K

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.bouncycastle.bcpg.BCPGObject

Methods inherited from class java.lang.Object

Field Detail

SIMPLE

SALTED

SALTED_AND_ITERATED

ARGON_2

GNU_DUMMY_S2K

GNU_PROTECTION_MODE_NO_PRIVATE_KEY

GNU_PROTECTION_MODE_DIVERT_TO_CARD

GNU_PROTECTION_MODE_INTERNAL

Constructor Detail

S2K

S2K

S2K

S2K

S2K

Method Detail

simpleS2K

saltedS2K

saltedAndIteratedS2K

argon2S2K

gnuDummyS2K

getType

getHashAlgorithm

getIV

getIterationCount

getPasses

getProtectionMode

getParallelism

getMemorySizeExponent

encode