#  -*- text -*-
#
#
#  $Id: 47be0d44eeff5e85c0eba6c7461553d76b17cc4d $

#######################################################################
#
#  = 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, FreeRADIUS simply passes the name of the
#  digest off to OpenSSL and it tells _us_ whether it's
#  valid/supported or not.
#
#  OpenSSL should support at least:
#
#  * `md2`     (not recommended)
#  * `md4`     (not recommended)
#  * `md5`     (not recommended)
#  * `sha1`    (widely used but deprecated)
#  * `sha224`
#  * `sha256`  (the default)
#  * `sha384`
#  * `sha512`
#  * `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
	}
}
