Skip to content

Latest commit

 

History

History
1610 lines (846 loc) · 38.2 KB

REFERENCE.md

File metadata and controls

1610 lines (846 loc) · 38.2 KB

Reference

Table of Contents

Classes

Defined types

Data types

Classes

libreswan


It is very important you read the documentation that comes with libreswan before attempting to use this module.



This module is designed to install and configure system IPSEC capabilities using libreswan.

It will also configure and maintain the NSS database used by libreswan if you have chosen to let SIMP manage your PKI certificates.

To add and start tunnels that will be managed by libreswan see the manifest libreswan::add_connection.


This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

  • When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.

  • If used independently, all SIMP-managed security subsystems are disabled by default, and must be explicitly opted into by administrators. Please review items referring to simp_options::* for additional information.

  • See the libreswan documentation https://libreswan.org/man/ipsec.conf.5.html for more information regarding these variables.

  • Any variable set to undef will not appear in the configuration file and will default to the value set by libreswan. Those set will appear in the configuration file but can be overwritten using Hiera.

  • See also

Parameters

The following parameters are available in the libreswan class:

service_name

Data type: String

The name of the IPSEC service.

package_name

Data type: String

The name of the libreswan package.

trusted_nets

Data type: Simplib::Netlist

An allowed set of subnetworks (in CIDR notataion) with permitted access explicitly for IPSEC communication

Default value: simplib::lookup('simp_options::trusted_nets', {'default_value' => ['127.0.0.1/32'] })

firewall

Data type: Boolean

Whether to add appropriate rules to allow IPSEC traffic to the SIMP-controlled firewall

Default value: simplib::lookup('simp_options::firewall', {'default_value' => false })

fips

Data type: Boolean

Whether server is in FIPS mode.

  • Affects cryptography allowed to be used by IPSEC.

Default value: simplib::lookup('simp_options::fips', {'default_value' => false })

pki

Data type: Variant[Boolean,Enum['simp']]

  • If 'simp', include simp/pki and use pki::copy to manage application certs in /etc/pki/simp_apps/libreswan/x509
  • If true, do not include simp/pki, but still use pki::copy to manage certs in /etc/pki/simp_apps/libreswan/x509
  • If false, do not include simp/pki and do not use pki::copy to manage certs. You will need to appropriately assign a subset of:
    • app_pki_dir
    • app_pki_key
    • app_pki_cert
    • app_pki_ca
    • app_pki_ca_dir

Default value: simplib::lookup('simp_options::pki', {'default_value' => false })

haveged

Data type: Boolean

Whether to use haveged to ensure adequate entropy

Default value: simplib::lookup('simp_options::haveged', {'default_value' => false })

nssdb_password

Data type: String

Password for the NSS database used by ipsec

Default value: simplib::passgen('nssdb_password')

myid

Data type: Optional[String]

Default value: undef

protostack

Data type: Enum['netkey','klips','mast']

Default value: 'netkey'

interfaces

Data type: Optional[Libreswan::Interfaces]

Default value: undef

listen

Data type: Optional[Simplib::IP]

Default value: undef

ikeport

Data type: Simplib::Port

DEPRECATED

Default value: 500

nflog_all

Data type: Optional[Integer]

Default value: undef

nat_ikeport

Data type: Simplib::Port

DEPRECATED

Default value: 4500

keep_alive

Data type: Optional[Integer]

Default value: undef

virtual_private

Data type: Libreswan::VirtualPrivate

Default value: ['%v4:10.0.0.0/8','%v4:192.168.0.0/16','%v4:172.16.0.0/12']

myvendorid

Data type: Optional[String]

Default value: undef

nhelpers

Data type: Optional[Integer]

Default value: undef

plutofork

Data type: Optional[Enum['yes','no']]

Default value: undef

crlcheckinterval

Data type: Optional[Integer]

Default value: undef

strictcrlpolicy

Data type: Optional[Enum['yes','no']]

Default value: undef

ocsp_enable

Data type: Optional[Enum['yes','no']]

Default value: undef

ocsp_strict

Data type: Optional[Enum['yes','no']]

Default value: undef

ocsp_timeout

Data type: Optional[Integer]

Default value: undef

ocsp_uri

Data type: Optional[Simplib::Uri]

Default value: undef

ocsp_trustname

Data type: Optional[String]

Default value: undef

syslog

Data type: Optional[String]

Default value: undef

klipsdebug

Data type: String

DEPRECATED

Default value: 'none'

plutodebug

Data type: String

Default value: 'none'

uniqueids

Data type: Optional[Enum['yes','no']]

Default value: undef

plutorestartoncrash

Data type: Optional[Enum['yes','no']]

Default value: undef

logfile

Data type: Optional[Stdlib::Absolutepath]

Default value: undef

logappend

Data type: Optional[Enum['yes','no']]

Default value: undef

logtime

Data type: Optional[Enum['yes','no']]

Default value: undef

ddos_mode

Data type:

Optional[Enum['busy',
    'unlimited','auto']]

Default value: undef

ddos_ike_treshold

Data type: Optional[Integer]

Default value: undef

dumpdir

Data type: Stdlib::Absolutepath

Default value: '/var/run/pluto'

statsbin

Data type: Optional[String]

Default value: undef

ipsecdir

Data type: Stdlib::Absolutepath

The directory to store all ipsec configuration information.

Default value: '/etc/ipsec.d'

secretsfile

Data type: Stdlib::Absolutepath

Default value: '/etc/ipsec.secrets'

perpeerlog

Data type: Optional[Enum['yes','no']]

DEPRECATED

Default value: undef

perpeerlogdir

Data type: Stdlib::Absolutepath

DEPRECATED

Default value: '/var/log/pluto/peer'

fragicmp

Data type: Optional[Enum['yes','no']]

Default value: undef

hidetos

Data type: Optional[Enum['yes','no']]

Default value: undef

overridemtu

Data type: Optional[Integer]

Default value: undef

block_cidrs

Data type: Optional[Array[Simplib::IP::V4::CIDR]]

List of CIDRs to which communication should never be allowed

Default value: undef

clear_cidrs

Data type: Optional[Array[Simplib::IP::V4::CIDR]]

List of CIDRs to which communication should always be in the clear

Default value: undef

clear_private_cidrs

Data type: Optional[Array[Simplib::IP::V4::CIDR]]

List of CIDRs to which communication will be in the clear, or, if the other side initiates IPSEC, use encryption

Default value: undef

private_cidrs

Data type: Optional[Array[Simplib::IP::V4::CIDR]]

List of CIDRs to which communication should always be private

Default value: undef

private_clear_cidrs

Data type: Array[Simplib::IP::V4::CIDR]

List of CIDRs to which communication should be private if possible but in the clear otherwise

Default value: ['0.0.0.0/0']

libreswan::config

Configures ipsec.conf and necessary directories.

libreswan::config::firewall

Ensures that the required firewall rules are defined

libreswan::config::pki

Ensure that the simp/pki PKI certificates are loaded into the IPSEC NSS Database.

Parameters

The following parameters are available in the libreswan::config::pki class:

app_pki_external_source

Data type: String

  • If $pki = 'simp' or true, this is the directory from which certs will be copied, via pki::copy.
  • If $pki = false, this variable has no effect.

Default value: simplib::lookup('simp_options::pki::source', { 'default_value' => '/etc/pki/simp/x509' })

app_pki_dir

Data type: Stdlib::Absolutepath

Controls the base path of the other app_pki_* parameters.

Default value: '/etc/pki/simp_apps/libreswan/x509'

app_pki_key

Data type: Stdlib::Absolutepath

Path and name of the private SSL key file

Default value: "${app_pki_dir}/private/${facts['networking']['fqdn']}.pem"

app_pki_cert

Data type: Stdlib::Absolutepath

Path and name of the public SSL certificate

Default value: "${app_pki_dir}/public/${facts['networking']['fqdn']}.pub"

app_pki_ca

Data type: Stdlib::Absolutepath

Path and name of the CA.

Default value: "${app_pki_dir}/cacerts/cacerts.pem"

libreswan::config::pki::nsspki

Called when the certificates change or when the database is initialized.

Parameters

The following parameters are available in the libreswan::config::pki::nsspki class:

certname

Data type: String[1]

The name of the certificate to be used

Default value: $facts['networking']['fqdn']

libreswan::install

Installs the appropriate packages.

libreswan::service

Ensure that the appropriate services are running.

Defined types

libreswan::connection

You can can set up defaults for all of your connections by using the name 'default'. This will create a file default.conf with a 'conn %default' header. Then, all settings in default.conf will be used as defaults for connections specified in other files.

Not all available, connection-related, libreswan settings are defined here. However, should you need a missing setting you can manually create a correctly-formatted, connection configuration file in the IPSEC configuration directory. This file must have a .conf suffix.

  • Manually generated configuration files are not managed, or purged, by Puppet.

The following parameters correspond to libreswan settings for which the default values are different from the libreswan defaults. You can override the defaults by passing in different data in the definition parameters.

The rest of the parameters map one-to-one to libreswan settings and are undef.

Any undef parameter will not appear in the generated configuration file for the connection. See libreswan documentation for the setting defaults when omitted from a connection's configuration. https://libreswan.org/man/ipsec.conf.5.html, the CONN:SETTINGS section

Parameters

The following parameters are available in the libreswan::connection defined type:

dir

Data type: Stdlib::Absolutepath

The absolute path to the IPSEC configuration directory.

Default value: '/etc/ipsec.d'

keyingtries

Data type: Integer

The number of times a connection will try to reconnect before exiting.

Default value: 10

ike

Data type: String

The ciphers used in the connection.

Default value: 'aes-sha2'

phase2alg

Data type: String

The ciphers used in the second part of the connection.

Default value: 'aes-sha2'

left

Data type: Optional[Libreswan::ConnAddr]

Default value: undef

right

Data type: Optional[Libreswan::ConnAddr]

Default value: undef

connaddrfamily

Data type: Optional[Enum['ipv4','ipv6']]

Default value: undef

leftaddresspool

Data type: Optional[Array[Simplib::IP,2,2]]

Default value: undef

leftsubnet

Data type:

Optional[Variant[
    Enum['%no','%priv'],
    Pattern['^vhost:*'],
    Pattern['^vnet:*'],
    Simplib::IP::CIDR]]

Default value: undef

leftsubnets

Data type: Optional[Array[Simplib::IP::CIDR]]

Default value: undef

leftprotoport

Data type: Optional[String]

Default value: undef

leftsourceip

Data type: Optional[Simplib::IP]

Default value: undef

leftupdown

Data type: Optional[String]

Default value: undef

leftcert

Data type: Optional[String]

Default value: undef

leftrsasigkey

Data type: Optional[String]

Default value: undef

leftrsasigkey2

Data type: Optional[String]

Default value: undef

leftsendcert

Data type:

Optional[Enum['yes', 'no',
    'never','always','sendifasked']]

Default value: undef

leftnexthop

Data type:

Optional[Variant[
    Enum['%direct','%defaultroute'],
    Simplib::IP]]

Default value: undef

leftid

Data type: Optional[String]

Default value: undef

leftca

Data type: Optional[String]

Default value: undef

rightid

Data type: Optional[String]

Default value: undef

rightrsasigkey

Data type: Optional[String]

Default value: undef

rightrsasigkey2

Data type: Optional[String]

Default value: undef

rightca

Data type: Optional[String]

Default value: undef

rightaddresspool

Data type: Optional[Array[Simplib::IP,2,2]]

Default value: undef

rightsubnets

Data type: Optional[Array[Simplib::IP::CIDR]]

Default value: undef

rightsubnet

Data type:

Optional[Variant[
    Enum['%no','%priv'],
    Pattern['^vhost:*'],
    Pattern['^vnet:*'],
    Simplib::IP::CIDR]]

Default value: undef

rightprotoport

Data type: Optional[String]

Default value: undef

rightsourceip

Data type: Optional[Simplib::IP]

Default value: undef

rightupdown

Data type: Optional[String]

Default value: undef

rightcert

Data type: Optional[String]

Default value: undef

rightsendcert

Data type:

Optional[Enum['yes', 'no',
    'never','always','sendifasked']]

Default value: undef

rightnexthop

Data type:

Optional[Variant[
    Enum['%direct','%defaultroute'],
    Simplib::IP]]

Default value: undef

auto

Data type:

Optional[Enum['add','start',
    'ondemand', 'ignore']]

Default value: undef

authby

Data type:

Optional[Enum['rsasig','secret',
    'secret|rsasig', 'never', 'null']]

Default value: undef

type

Data type:

Optional[Enum['tunnel','transport',
    'passthough','reject','drop']]

Default value: undef

ikev2

Data type:

Optional[Enum['insist','permit',
    'propose','never','yes', 'no']]

Default value: undef

mobike

Data type: Optional[Enum['yes', 'no']]

Default value: undef

phase2

Data type: Optional[Enum['esp', 'ah']]

Default value: undef

ikepad

Data type: Optional[Enum['yes','no']]

Default value: undef

fragmentation

Data type: Optional[Enum['yes','no','force']]

Default value: undef

sha2_truncbug

Data type: Optional[Enum['yes','no']]

Default value: undef

narrowing

Data type: Optional[Enum['yes','no']]

Default value: undef

sareftrack

Data type:

Optional[Enum['yes','no',
    'conntrack']]

Default value: undef

leftxauthserver

Data type: Optional[Enum['yes','no']]

Default value: undef

rightxauthserver

Data type: Optional[Enum['yes','no']]

Default value: undef

leftxauthusername

Data type: Optional[String]

Default value: undef

rightxauthusername

Data type: Optional[String]

Default value: undef

leftxauthclient

Data type: Optional[Enum['yes','no']]

Default value: undef

rightxauthclient

Data type: Optional[Enum['yes','no']]

Default value: undef

leftmodecfgserver

Data type: Optional[Enum['yes','no']]

Default value: undef

rightmodecfgserver

Data type: Optional[Enum['yes','no']]

Default value: undef

leftmodecfgclient

Data type: Optional[Enum['yes','no']]

Default value: undef

rightmodecfgclient

Data type: Optional[Enum['yes','no']]

Default value: undef

xauthby

Data type:

Optional[Enum['file','pam',
    'alwaysok']]

Default value: undef

xauthfail

Data type: Optional[Enum['hard','soft']]

Default value: undef

modecfgpull

Data type: Optional[Enum['yes','no']]

Default value: undef

modecfgdns

Data type: Optional[Array[Simplib::IP]]

Support 3.23+ DNS configuration

Default value: undef

modecfgdns1

Data type: Optional[Simplib::IP]

Support <= 3.22 domain configuration

Default value: undef

modecfgdns2

Data type: Optional[Simplib::IP]

Support <= 3.22 domain configuration

Default value: undef

modecfgdomain

Data type: Optional[String]

Support <= 3.22 domain configuration

Default value: undef

modecfgdomains

Data type: Optional[Array[String]]

Support 3.23+ domains configuration

Default value: undef

modecfgbanner

Data type: Optional[String]

Default value: undef

nat_ikev1_method

Data type:

Optional[Enum['drafts','rfc',
    'both']]

Default value: undef

dpddelay

Data type: Optional[Pattern[/\d+[smh]$/]]

Default value: undef

dpdtimeout

Data type: Optional[Pattern[/\d+[smh]$/]]

Default value: undef

dpdaction

Data type:

Optional[Enum['hold', 'clear',
    'restart']]

Default value: undef

libreswan::nss::init_db

Initializes the NSS database, sets the correct password, and configures FIPS if necessary.

Parameters

The following parameters are available in the libreswan::nss::init_db defined type:

dbdir

Data type: Stdlib::Absolutepath

Directory where the NSS database will be created.

password

Data type: String

Password used to protect the database.

  • Each NSS database is broken up into tokens used for different types of certificates, Smart cards, FIPS compliant, non-FIPS. This util sets the FIPS and non-FIPS token to they same password. The tokens are defined by $libreswan::nsstoken. You can add tokens to array if there are other parts of the database you want to protect.
destroyexisting

Data type: Boolean

If true, it will remove the existing database before running the init command.

Default value: false

fips

Data type: Boolean

Default value: simplib::lookup('simp_options::fips', { 'default_value' => false })

token

Data type: String

Default value: 'NSS Certificate DB'

nsspassword

Data type: Stdlib::Absolutepath

Default value: "${dbdir}/nsspassword"

init_command

Data type: Optional[String[1]]

Command used to create the cert db.

Default value: simplib::lookup('libreswan::nss::init_db::init_command', { 'default_value' => undef })

libreswan::nss::loadcacerts

Adds the CA certificates to the NSS trust store.

Parameters

The following parameters are available in the libreswan::nss::loadcacerts defined type:

dbdir

Data type: Stdlib::Absolutepath

The directory where the DB is located

nsspwd_file

Data type: Stdlib::Absolutepath

Default value: "${dbdir}/nsspassword"

cert

Data type: Stdlib::Absolutepath

The absolute path to the public portion CA certificate.

token

Data type: String

Default value: 'NSS Certificate DB'

certtype

Data type: Enum['PEM','DER']

The format the certificate is in. PEM and DER are currently acceptable.

Default value: 'PEM'

libreswan::nss::loadcerts

Load a server certificate into the NSS database.

Parameters

The following parameters are available in the libreswan::nss::loadcerts defined type:

dbdir

Data type: Stdlib::Absolutepath

The directory where the NSS Database is located.

nsspwd_file

Data type: Stdlib::Absolutepath

The file which contains the password if there is one.

Default value: "${dbdir}/nsspassword"

cert

Data type: Stdlib::Absolutepath

The absolute path to the public portion of the cert.

token

Data type: String

Default value: 'NSS Certificate DB'

key

Data type: Optional[Stdlib::Absolutepath]

The absolute path to the private portion of the cert.

Default value: undef

certtype

Data type: Enum['PEM','P12']

The format the certificate is in.

Default value: 'PEM'

Data types

Libreswan::ConnAddr

Valid libreswan connection addresses

Alias of

Variant[Enum[
    '%any',
    '%defaultroute',
    '%opportunistic',
    '%opportunisticgroup',
    '%group'
  ], Simplib::IP::V4, Simplib::IP::V6, Pattern['^%[a-zA-Z]+\d+$']]

Libreswan::IP::V4::VirtualPrivate

Matches valid IPv4 CIDR Mask addresses Base Regex taken from Ruby core's Resolv::IPv4::Regex

Reference: ruby/lib/resolv.rb

Copyright 2010 Tanaka Akira kr@fsij.org Released under the guidance of the Ruby COPYING file section 2(a) Commit 4e3a98d383eb3c420df5208d83f9aba70b504e33

Alias of Pattern['^(?-mix:\A%v4:(!)?((?x-mi:0|1(?:[0-9][0-9]?)?|2(?:[0-4][0-9]?|5[0-5]?|[6-9])?|[3-9][0-9]?))\.((?x-mi:0|1(?:[0-9][0-9]?)?|2(?:[0-4][0-9]?|5[0-5]?|[6-9])?|[3-9][0-9]?))\.((?x-mi:0|1(?:[0-9][0-9]?)?|2(?:[0-4][0-9]?|5[0-5]?|[6-9])?|[3-9][0-9]?))\.((?x-mi:0|1(?:[0-9][0-9]?)?|2(?:[0-4][0-9]?|5[0-5]?|[6-9])?|[3-9][0-9]?))/(3[012]|[12][0-9]|[0-9])\z)$']

Libreswan::IP::V6::VirtualPrivate

Matches valid IPv4 CIDR Mask addresses Base Regex taken from Ruby core's Resolv::IPv4::Regex

Reference: ruby/lib/resolv.rb

Copyright 2010 Tanaka Akira kr@fsij.org Released under the guidance of the Ruby COPYING file section 2(a) Commit 4e3a98d383eb3c420df5208d83f9aba70b504e33

Alias of Pattern['^(?x-mi:(\A%v6:(!)?(?x-mi:(?:(?x-mi:(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}/(12[0-8]|1[01][0-9]|[0-9]?[0-9])\z))|(?:(?x-mi:((?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?)::((?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?)/(12[0-8]|1[01][0-9]|[0-9]?[0-9])\z))|(?:(?x-mi:((?:[0-9A-Fa-f]{1,4}:){6,6})(\d+)\.(\d+)\.(\d+)\.(\d+)/(12[0-8]|1[01][0-9]|[0-9]?[0-9])\z))|(?:(?x-mi:((?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4})*)?)::((?:[0-9A-Fa-f]{1,4}:)*)(\d+)\.(\d+)\.(\d+)\.(\d+)/(12[0-8]|1[01][0-9]|[0-9]?[0-9]))))\z))$']

Libreswan::Interfaces

Valid libreswan interfaces

Alias of

Array[Variant[
    Enum['%none','%defaultroute'],
    Pattern['(\w+=\w+)']
  ]]

Libreswan::VirtualPrivate

Valid virtual private addresses

Alias of

Array[Variant[
    Libreswan::IP::V4::VirtualPrivate,
    Libreswan::IP::V6::VirtualPrivate
  ]]