org.forgerock.secrets.keys

Class KeyFormatPem

java.lang.Object

org.forgerock.secrets.keys.KeyFormatPem

All Implemented Interfaces:

KeyFormat<String>

public final class KeyFormatPem
extends Object
implements KeyFormat<String>

Exports a key in the PEM (Privacy Enhanced Mail) format. This is the base64-encoded ASN.1 DER binary encoding of the key surrounded by markers identifying the beginning and end of the key. Currently this produces private keys in the more general PKCS#8 format, rather than the older PKCS#1 format produced by OpenSSL by default. The correct headers are produced to allow software to parse these keys directly. To convert to PKCS#1 you can use OpenSSL:

      openssl pkcs8 -nocrypt -in pkcs8key.pem -out pkcs1key.pem
 

Private keys can be encrypted during export. This will produce a PKCS#8 EncryptedPrivateKeyInfo format PEM, using strong encryption parameters:

• The encryption key is derived from a password using 200,000 iterations of salted PBKDF2-HMAC-SHA256.
• The private key is then encrypted using AES-128-CBC.

The resulting encrypted keys can be processed with OpenSSL using the following command:

      openssl pkcs8 -v2 aes-128-cbc -inform PEM -in in.pem -out out.pem
 

See Also:

RFC 1421 for the PEM format specification., This article by ARM on how PEM keys are encoded in practice.

Field Summary

Fields

Modifier and Type	Field and Description
static KeyFormatPem	WITH_CERTIFICATE Exports the key material with the certificate as well.
static KeyFormatPem	WITHOUT_CERTIFICATE Exports the key material without any associated certificate.

Constructor Summary

Constructors

Constructor and Description
KeyFormatPem(boolean includeCertificate) Constructs a new PEM key format that does not encrypt private keys.
KeyFormatPem(boolean includeCertificate, SecretReference<GenericSecret> encryptionPassword) Constructs a new PEM key format that encrypts private keys using the given password.

Method Summary

Modifier and Type	Method and Description
String	export(CryptoKey key, Key rawKey) Exports the given crypto key and raw key material.
KeyFormatPem	withEncryptionPassword(SecretReference<GenericSecret> encryptionPassword) Returns a new PEM key format that will encrypt private keys with the given password.

Methods inherited from class java.lang.Object

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

Field Detail

WITHOUT_CERTIFICATE

public static final KeyFormatPem WITHOUT_CERTIFICATE

Exports the key material without any associated certificate.

WITH_CERTIFICATE

public static final KeyFormatPem WITH_CERTIFICATE

Exports the key material with the certificate as well. The certificate will be exported before the key.

Constructor Detail

KeyFormatPem

public KeyFormatPem(boolean includeCertificate,
                    SecretReference<GenericSecret> encryptionPassword)

Constructs a new PEM key format that encrypts private keys using the given password.

Parameters:

includeCertificate - whether to include any certificate associated with the key in the PEM.

encryptionPassword - the password to use for encrypting the private key.

KeyFormatPem

public KeyFormatPem(boolean includeCertificate)

Constructs a new PEM key format that does not encrypt private keys. This should only be used if either no private key material is being exported or it will never be exposed to untrusted sources.

Parameters:

includeCertificate - whether to include any certificate associated with the key in the PEM.

Method Detail

withEncryptionPassword

public KeyFormatPem withEncryptionPassword(SecretReference<GenericSecret> encryptionPassword)

Returns a new PEM key format that will encrypt private keys with the given password.

Parameters:

encryptionPassword - the encryption password.

Returns:

the new PEM encryption format.

export

public String export(CryptoKey key,
                     Key rawKey)
              throws NoSuchSecretException

Description copied from interface: KeyFormat

Exports the given crypto key and raw key material.

Specified by:

export in interface KeyFormat<String>

Parameters:

key - the crypto key.

rawKey - the raw key material.

Returns:

the exported key material in the given format.

Throws:

NoSuchSecretException - if the secret could not be exported.