View Source X509.PrivateKey (X509 v0.8.5)

Functions for generating, reading and writing RSA and EC private keys.

example-use-with-public_key

Example use with :public_key

Encryption and decryption:

iex> private_key = X509.PrivateKey.new_rsa(2048)
iex> public_key = X509.PublicKey.derive(private_key)
iex> plaintext = "Hello, world!"
iex> ciphertext = :public_key.encrypt_public(plaintext, public_key)
iex> :public_key.decrypt_private(ciphertext, private_key)
"Hello, world!"

Signing and signature verification:

iex> private_key = X509.PrivateKey.new_ec(:secp256r1)
iex> public_key = X509.PublicKey.derive(private_key)
iex> message = "Hello, world!"
iex> signature = :public_key.sign(message, :sha256, private_key)
iex> :public_key.verify(message, :sha256, signature, public_key)
true

Note that in practice it is not a good idea to directly encrypt a message with asymmetrical cryptography. The examples above are deliberate over-simpliciations intended to highlight the :public_key API calls.

Link to this section Summary

Types

t()

RSA or EC private key

Functions

Attempts to parse a private key in DER (binary) format.

Attempts to parse a private key in DER (binary) format. Raises in case of failure.

Attempts to parse a private key in PEM format.

Attempts to parse a private key in PEM format. Raises in case of failure.

Generates a new EC private key. To derive the public key, use X509.PublicKey.derive/1.

Generates a new RSA private key. To derive the public key, use X509.PublicKey.derive/1.

Converts a private key to DER (binary) format.

Converts a private key to PEM format.

Extracts a private key from a PKCS#8 PrivateKeyInfo container.

Wraps a private key in a PKCS#8 PrivateKeyInfo container.

Link to this section Types

Link to this section Functions

Specs

from_der(binary()) :: {:ok, t()} | {:error, :malformed}

Attempts to parse a private key in DER (binary) format.

Unwraps the PKCS#8 PrivateKeyInfo container, if present.

Returns an :ok tuple in case of success, or an :error tuple in case of failure. Possible error reasons are:

  • :malformed - the data could not be decoded as a private key

Specs

from_der!(binary()) :: t() | no_return()

Attempts to parse a private key in DER (binary) format. Raises in case of failure.

Unwraps the PKCS#8 PrivateKeyInfo container, if present.

Link to this function

from_pem(pem, opts \\ [])

View Source

Specs

from_pem(String.t(), Keyword.t()) ::
  {:ok, t()} | {:error, :malformed | :not_found}

Attempts to parse a private key in PEM format.

Processes the first PEM entry of type PRIVATE KEY, RSA PRIVATE KEY or EC PRIVATE KEY found in the input. Unwraps the PKCS#8 PrivateKeyInfo container, if present. Returns an :ok tuple in case of success, or an :error tuple in case of failure. Possible error reasons are:

  • :not_found - no PEM entry of a supported PRIVATE KEY type was found
  • :malformed - the entry could not be decoded as a private key

options

Options:

  • :password - the password used to decrypt an encrypted private key; may be specified as a string or a charlist
Link to this function

from_pem!(pem, opts \\ [])

View Source

Specs

from_pem!(String.t(), Keyword.t()) :: t() | no_return()

Attempts to parse a private key in PEM format. Raises in case of failure.

Processes the first PEM entry of type PRIVATE KEY, RSA PRIVATE KEY or EC PRIVATE KEY found in the input. Unwraps the PKCS#8 PrivateKeyInfo container, if present.

options

Options:

  • :password - the password used to decrypt an encrypted private key; may be specified as a string or a charlist

Specs

Generates a new EC private key. To derive the public key, use X509.PublicKey.derive/1.

The first parameter must specify a named curve. The curve can be specified as an atom or an OID tuple.

Note that this function uses Erlang/OTP's :public_key application, which does not support all curve names returned by the :crypto.ec_curves/0 function. In particular, the NIST Prime curves must be selected by their SECG id, e.g. NIST P-256 is :secp256r1 rather than :prime256v1. Please refer to RFC4492 appendix A for a mapping table.

Link to this function

new_rsa(keysize, opts \\ [])

View Source

Specs

Generates a new RSA private key. To derive the public key, use X509.PublicKey.derive/1.

The key length in bits must be specified as an integer (minimum 256 bits). The default exponent of 65537 can be overridden using the :exponent option. Warning: the custom exponent value is not checked for safety!

Link to this function

to_der(private_key, opts \\ [])

View Source

Specs

to_der(t(), Keyword.t()) :: binary()

Converts a private key to DER (binary) format.

options

Options:

  • :wrap - Wrap the private key in a PKCS#8 PrivateKeyInfo container (default: false)
Link to this function

to_pem(private_key, opts \\ [])

View Source

Specs

to_pem(t(), Keyword.t()) :: String.t()

Converts a private key to PEM format.

options

Options:

  • :wrap - Wrap the private key in a PKCS#8 PrivateKeyInfo container (default: false)
  • :password - If a password is specified, the private key is encrypted using 3DES; to password will be required to decode the PEM entry

Extracts a private key from a PKCS#8 PrivateKeyInfo container.

Specs

wrap(t()) :: X509.ASN.record(:private_key_info)
wrap(X509.ASN.record(:private_key_info)) :: t()

Wraps a private key in a PKCS#8 PrivateKeyInfo container.