#  -*- text -*-
#
#
#  $Id: 63c6ea45a58363d3b67f6cb23ad2d0727eebf4bf $

#######################################################################
#
#  = Cipher Module
#
#  The `cipher` module is used to transform plaintext in some way that is dependent
#  on a key or key pair, producing encrypted ciphertext.
#
#  Registers the following expansions:
#
#  [options="header,autowidth"]
#  |===
#  | XLAT                                          | Description
#  | `%<inst>.encrypt(<plaintext>...)`             | Encrypts plaintext using `certificate_file`
#  | `%<inst>.decrypt(<ciphertext>...)`            | Decrypts ciphertext using `private_key_file`
#  | `%<inst>.sign(<plaintext>...)`                | Signs plaintext using `private_key_file`
#  | `%<inst>.verify(<signature>, <plaintext>...)`  | Validates a signature using `certificate_file`
#  | `%<inst>.certificate(serial)`                | Returns the serial of `certificate_file`
#  | `%<inst>.certificate(fingerprint, <hash>)`    | Produces a fingerprint of `certificate_file` using the specified hash.
#  | `%<inst>.certificate(not_before)`            | Retrieves the notBefore time from `certificate_file`.
#  | `%<inst>.certificate(not_after)`             | Retrieves the notAfter time from `certificate_file`.
#  |===
#
#  NOTE: `<ciphertext>` and `<signature>` are ingested and excreted to in their raw form.
#  You should use armouring expansions i.e. `%base64.encode(...)`, `%base64.decode(...)` if the values
#  are to be passed outside of FreeRADIUS.
#
#  e.g:
#
#    %base64.encode(%cipher_encrypt(<plaintext>))
#    %cipher_decrypt(%base64.decode(<ciphertext>))
#
#  NOTE: The supported versions are determined _entirely_ by the version of OpenSSL used, we
#  pass the name of the digest off to OpenSSL and it tells _us_ whether it's valid/supported
#  or not.
#
#  OpenSSL >= 1.0.0 should support at least:
#
#   * `md2`     (not recommended)
#   * `md4`     (not recommended)
#   * `md5`     (not recommended)
#   * `sha1`    (widely used but deprecated)
#   * `sha224`
#   * `sha256`  (the default)
#   * `sha384`
#   * `sha512`
#
#  OpenSSL >= 1.1.1 also supports the `sha3` family of digest functions.
#
#   * `sha3_224`
#   * `sha3_256`
#   * `sha3_384`
#   * `sha3_512`
#

#
#  ## Configuration Settings
#
cipher {
	#
	#  type::
	#
	#  Available schemes are:
	#
	#  * `rsa`
	#
	type = rsa

	#
	#  ### RSA asymmetrically keyed ciphering
	#
	rsa {
		#  private_key_password::
		#
		#  Private key used for decrypting and signing data.
		#
		private_key_password = whatever
		private_key_file = ${certdir}/rsa/server.pem

		#
		#  certificate_file::
		#
		#  The PEM encoded certificate used for encrypting data and verifying signatures.
		#
		certificate_file = ${certdir}/rsa/server.pem

		#
		#  verify_mode:: How we verify certificate_file on startup
		#
		#  After reading the certificate file from disk and parsing it we can
		#  apply other checks to ensure it is valid.  Currently we check
		#  the `notBefore` and `notAfter` fields to ensure the certificate is
		#  temporally valid.  Key use checks may be added in future.
		#
		#  [options="header,autowidth"]
		#  |===
		#  | Error | Description
		#  | hard  | Error out if the certificate is not yet valid or has expired.
		#  | soft  | Warn if the certificate is not yet valid or has expired.
		#  | none  | Stay silent if the certificate is not yet valid.
		#  |===
		#
		#  The default is `hard`.
		#
#		verify_mode = "hard"

		#
		#  oaep { ... }::
		#
		#  Parameters for the OAEP RSA padding scheme.
		#
		oaep {
#			oaep_digest = "sha256"
#			mgf1_digest = "sha256"
#			label = ""
		}

		#
		#  signature_digest::
		#
		#  Digest used to ingest the plaintext before signing or verification.
		#
#		signature_digest = "sha256"

		#
		#  padding_type::
		#
		#  The type of padding applied to the plaintext being one of:
		#
		#  * `none` (no padding)
		#  * `pkcs`
		#  * `oaep`
		#  * `x931` (signing only)
		#  * `ssl` (v1/v2)
		#
		#  NOTE: Defaults to *pkcs*.
		#
#		padding_type = pkcs

		#
		#  random_file:: Provides random number generator.
		#
#		random_file = /dev/urandom
	}
}
