Package org.pgpainless.util

# Class ArmorUtils

java.lang.Object
org.pgpainless.util.ArmorUtils

public final class ArmorUtils extends Object
Utility class for dealing with ASCII armored OpenPGP data.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`HEADER_CHARSET`
Constant armor key for message character sets.
`static final String`
`HEADER_COMMENT`
Constant armor key for comments.
`static final String`
`HEADER_HASH`
Constant armor key for used hash algorithms in clearsigned messages.
`static final String`
`HEADER_MESSAGEID`
Constant armor key for message IDs.
`static final String`
`HEADER_VERSION`
Constant armor key for program versions.

## Method Summary

Modifier and Type
Method
Description
`static void`
`addCommentHeader(org.bouncycastle.bcpg.ArmoredOutputStream armor, String comment)`
Add an ASCII armor comment header entry into the `ArmoredOutputStream`.
`static void`
`addHashAlgorithmHeader(org.bouncycastle.bcpg.ArmoredOutputStream armor, HashAlgorithm hashAlgorithm)`
Add an ASCII armor header entry about the used hash algorithm into the `ArmoredOutputStream`.
`static void`
`addMessageIdHeader(org.bouncycastle.bcpg.ArmoredOutputStream armor, String messageId)`
Add an ASCII armor message-id header entry into the `ArmoredOutputStream`.
`static List<String>`
`getArmorHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor, String headerKey)`
Return all ASCII armor header values of the given headerKey from the given `ArmoredInputStream`.
`static List<String>`
`getCharsetHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Return all ASCII armor header values of type charset from the given `ArmoredInputStream`.
`static List<String>`
`getCommentHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Extract all ASCII armor header values of type comment from the given `ArmoredInputStream`.
`static InputStream`
`getDecoderStream(InputStream inputStream)`
Hacky workaround for #96.
`static List<HashAlgorithm>`
`getHashAlgorithms(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Return a list of `HashAlgorithm` enums extracted from the hash header entries of the given `ArmoredInputStream`.
`static List<String>`
`getHashHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Return all ASCII armor header values of type hash-algorithm from the given `ArmoredInputStream`.
`static List<String>`
`getMessageIdHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Extract all ASCII armor header values of type message id from the given `ArmoredInputStream`.
`static List<String>`
`getVersionHeaderValues(org.bouncycastle.bcpg.ArmoredInputStream armor)`
Return all ASCII armor header values of type version from the given `ArmoredInputStream`.
`static void`
`setVersionHeader(org.bouncycastle.bcpg.ArmoredOutputStream armor, String version)`
Set the version header entry in the ASCII armor.
`static org.bouncycastle.bcpg.ArmoredOutputStream`
`toAsciiArmoredStream(OutputStream outputStream, MultiMap<String,String> header)`
Create an `ArmoredOutputStream` wrapping the given `OutputStream`.
`static org.bouncycastle.bcpg.ArmoredOutputStream`
`toAsciiArmoredStream(org.bouncycastle.openpgp.PGPKeyRing keyRing, OutputStream outputStream)`
Return an `ArmoredOutputStream` prepared with headers for the given key ring, which wraps the given `OutputStream`.
`static String`
`toAsciiArmoredString(byte[] bytes)`
Return the ASCII armored encoding of the given OpenPGP data bytes.
`static String`
`toAsciiArmoredString(byte[] bytes, MultiMap<String,String> additionalHeaderValues)`
Return the ASCII armored encoding of the given OpenPGP data bytes.
`static String`
`toAsciiArmoredString(InputStream inputStream)`
Return the ASCII armored encoding of the `InputStream` containing OpenPGP data.
`static String`
`toAsciiArmoredString(InputStream inputStream, MultiMap<String,String> additionalHeaderValues)`
Return the ASCII armored encoding of the OpenPGP data from the given `InputStream`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPPublicKey publicKey)`
Return the ASCII armored encoding of the given `PGPPublicKey`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPPublicKeyRing publicKeys)`
Return the ASCII armored encoding of the given `PGPPublicKeyRing`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPPublicKeyRingCollection publicKeyRings)`
Return the ASCII armored encoding of the given `PGPPublicKeyRingCollection`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPSecretKey secretKey)`
Return the ASCII armored encoding of the given `PGPSecretKey`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)`
Return the ASCII armored encoding of the given `PGPSecretKeyRing`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPSecretKeyRingCollection secretKeyRings)`
Return the ASCII armored encoding of the given `PGPSecretKeyRingCollection`.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPSignature signature)`
Return the ASCII armored representation of the given detached signature.
`static String`
`toAsciiArmoredString(org.bouncycastle.openpgp.PGPSignature signature, boolean export)`
Return the ASCII armored representation of the given detached signature.

### Methods inherited from class java.lang.Object

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

## Field Details

### HEADER_COMMENT

public static final String HEADER_COMMENT
Constant armor key for comments.

See Also:
  - Constant Field Values

### HEADER_VERSION

public static final String HEADER_VERSION
Constant armor key for program versions.

See Also:
  - Constant Field Values

### HEADER_MESSAGEID

public static final String HEADER_MESSAGEID
Constant armor key for message IDs. Useful for split messages.

See Also:
  - Constant Field Values

### HEADER_HASH

public static final String HEADER_HASH
Constant armor key for used hash algorithms in clearsigned messages.

See Also:
  - Constant Field Values

### HEADER_CHARSET

public static final String HEADER_CHARSET
Constant armor key for message character sets.

See Also:
  - Constant Field Values

## Method Details

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPSecretKey secretKey) throws IOException
Return the ASCII armored encoding of the given `PGPSecretKey`.

Parameters:
  `secretKey` - secret key
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPPublicKey publicKey) throws IOException
Return the ASCII armored encoding of the given `PGPPublicKey`.

Parameters:
  `publicKey` - public key
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys) throws IOException
Return the ASCII armored encoding of the given `PGPSecretKeyRing`.

Parameters:
  `secretKeys` - secret key ring
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPPublicKeyRing publicKeys) throws IOException
Return the ASCII armored encoding of the given `PGPPublicKeyRing`.

Parameters:
  `publicKeys` - public key ring
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRingCollection secretKeyRings) throws IOException
Return the ASCII armored encoding of the given `PGPSecretKeyRingCollection`. The encoding will use per-key ASCII armors protecting each `PGPSecretKeyRing` individually. Those armors are then concatenated with newlines in between.

Parameters:
  `secretKeyRings` - secret key ring collection
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPPublicKeyRingCollection publicKeyRings) throws IOException
Return the ASCII armored encoding of the given `PGPPublicKeyRingCollection`. The encoding will use per-key ASCII armors protecting each `PGPPublicKeyRing` individually. Those armors are then concatenated with newlines in between.

Parameters:
  `publicKeyRings` - public key ring collection
Returns:
  ascii armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPSignature signature) throws IOException
Return the ASCII armored representation of the given detached signature. The signature will not be stripped of non-exportable subpackets or trust-packets. If you need to strip those (e.g. because the signature is intended to be sent to a third party), use `toAsciiArmoredString(PGPSignature, boolean)` and provide

    true

as boolean value.

Parameters:
  `signature` - signature
Returns:
  ascii armored string
Throws:
  `IOException` - in case of an error in the `ArmoredOutputStream`

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull org.bouncycastle.openpgp.PGPSignature signature, boolean export) throws IOException
Return the ASCII armored representation of the given detached signature. If

    export

is true, the signature will be stripped of non-exportable subpackets or trust-packets. If it is

    false

, the signature will be encoded as-is.

Parameters:
  `signature` - signature
  `export` - whether to exclude non-exportable subpackets or trust-packets.
Returns:
  ascii armored string
Throws:
  `IOException` - in case of an error in the `ArmoredOutputStream`

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull byte[] bytes) throws IOException
Return the ASCII armored encoding of the given OpenPGP data bytes.

Parameters:
  `bytes` - openpgp data
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull byte[] bytes, @Nullable MultiMap<String,String> additionalHeaderValues) throws IOException
Return the ASCII armored encoding of the given OpenPGP data bytes. The ASCII armor will include headers from the header map.

Parameters:
  `bytes` - OpenPGP data
  `additionalHeaderValues` - header map
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull InputStream inputStream) throws IOException
Return the ASCII armored encoding of the `InputStream` containing OpenPGP data.

Parameters:
  `inputStream` - input stream of OpenPGP data
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredString

@Nonnull public static String toAsciiArmoredString(@Nonnull InputStream inputStream, @Nullable MultiMap<String,String> additionalHeaderValues) throws IOException
Return the ASCII armored encoding of the OpenPGP data from the given `InputStream`. The ASCII armor will include armor headers from the given header map.

Parameters:
  `inputStream` - input stream of OpenPGP data
  `additionalHeaderValues` - ASCII armor header map
Returns:
  ASCII armored encoding
Throws:
  `IOException` - in case of an io error

### toAsciiArmoredStream

@Nonnull public static org.bouncycastle.bcpg.ArmoredOutputStream toAsciiArmoredStream(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing, @Nonnull OutputStream outputStream)
Return an `ArmoredOutputStream` prepared with headers for the given key ring, which wraps the given `OutputStream`. The armored output stream can be used to encode the key ring by calling `PGPKeyRing.encode(OutputStream)` with the armored output stream as an argument.

Parameters:
  `keyRing` - key ring
  `outputStream` - wrapped output stream
Returns:
  armored output stream

### toAsciiArmoredStream

@Nonnull public static org.bouncycastle.bcpg.ArmoredOutputStream toAsciiArmoredStream(@Nonnull OutputStream outputStream, @Nullable MultiMap<String,String> header)
Create an `ArmoredOutputStream` wrapping the given `OutputStream`. The armored output stream will be prepared with armor headers given by header. Note: Since the armored output stream is retrieved from `ArmoredOutputStreamFactory.get(OutputStream)`, it may already come with custom headers. Hence, the header entries given by header are appended below those already populated headers.

Parameters:
  `outputStream` - output stream to wrap
  `header` - map of header entries
Returns:
  armored output stream

### setVersionHeader

public static void setVersionHeader(@Nonnull org.bouncycastle.bcpg.ArmoredOutputStream armor, @Nullable String version)
Set the version header entry in the ASCII armor. If the version info is null or only contains whitespace characters, then the version header will be removed.

Parameters:
  `armor` - armored output stream
  `version` - version header.

### addHashAlgorithmHeader

public static void addHashAlgorithmHeader(@Nonnull org.bouncycastle.bcpg.ArmoredOutputStream armor, @Nonnull HashAlgorithm hashAlgorithm)
Add an ASCII armor header entry about the used hash algorithm into the `ArmoredOutputStream`.

Parameters:
  `armor` - armored output stream
  `hashAlgorithm` - hash algorithm
See Also:
  - RFC 4880 - OpenPGP Message Format §6.2. Forming ASCII Armor

### addCommentHeader

public static void addCommentHeader(@Nonnull org.bouncycastle.bcpg.ArmoredOutputStream armor, @Nonnull String comment)
Add an ASCII armor comment header entry into the `ArmoredOutputStream`.

Parameters:
  `armor` - armored output stream
  `comment` - free-text comment
See Also:
  - RFC 4880 - OpenPGP Message Format §6.2. Forming ASCII Armor

### addMessageIdHeader

public static void addMessageIdHeader(@Nonnull org.bouncycastle.bcpg.ArmoredOutputStream armor, @Nonnull String messageId)
Add an ASCII armor message-id header entry into the `ArmoredOutputStream`.

Parameters:
  `armor` - armored output stream
  `messageId` - message id
See Also:
  - RFC 4880 - OpenPGP Message Format §6.2. Forming ASCII Armor

### getCommentHeaderValues

@Nonnull public static List<String> getCommentHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Extract all ASCII armor header values of type comment from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of comment headers

### getMessageIdHeaderValues

@Nonnull public static List<String> getMessageIdHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Extract all ASCII armor header values of type message id from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of message-id headers

### getHashHeaderValues

@Nonnull public static List<String> getHashHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Return all ASCII armor header values of type hash-algorithm from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of hash headers

### getHashAlgorithms

@Nonnull public static List<HashAlgorithm> getHashAlgorithms(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Return a list of `HashAlgorithm` enums extracted from the hash header entries of the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of hash algorithms from the ASCII header

### getVersionHeaderValues

@Nonnull public static List<String> getVersionHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Return all ASCII armor header values of type version from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of version headers

### getCharsetHeaderValues

@Nonnull public static List<String> getCharsetHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor)
Return all ASCII armor header values of type charset from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
Returns:
  list of charset headers

### getArmorHeaderValues

@Nonnull public static List<String> getArmorHeaderValues(@Nonnull org.bouncycastle.bcpg.ArmoredInputStream armor, @Nonnull String headerKey)
Return all ASCII armor header values of the given headerKey from the given `ArmoredInputStream`.

Parameters:
  `armor` - armored input stream
  `headerKey` - ASCII armor header key
Returns:
  list of values for the header key

### getDecoderStream

@Nonnull public static InputStream getDecoderStream(@Nonnull InputStream inputStream) throws IOException
Hacky workaround for #96. For `PGPPublicKeyRingCollection(InputStream, KeyFingerPrintCalculator)` or `PGPSecretKeyRingCollection(InputStream, KeyFingerPrintCalculator)` to read all PGPKeyRings properly, we apparently have to make sure that the `InputStream` that is given as constructor argument is a PGPUtil.BufferedInputStreamExt. Since `PGPUtil.getDecoderStream(InputStream)` will return an `ArmoredInputStream` if the underlying input stream contains armored data, we first dearmor the data ourselves to make sure that the end-result is a PGPUtil.BufferedInputStreamExt.

Parameters:
  `inputStream` - input stream
Returns:
  BufferedInputStreamExt
Throws:
  `IOException` - in case of an IO error