Puppet nsstools Module

Table of Contents

1. Overview
2. Description
3. Usage
   • Security Considerations
   • Example
   • Classes
   • Types
   • Functions
4. Limitations
   • Tested Platforms
   • Puppet Version Compatibility
5. Versioning
6. Support
7. Contributing
8. See Also

Overview

Manages NSS certificate databases

Description

This is a puppet module for the basic management of the certificate database format that is used by various Network Security Services (NSS) libraries and tools. It's functionality is implemented using the NSS Tools and OpenSSL packages.

The latter is some what ironically required as although the NSS suite is intended to be used in place of OpenSSL, it mandates the usage of PKCS#12 format files for certain operations. This is unfortunate as it appears to provide no utility for converting between the ASCII .pem format popular for X.509 certificates and PKCS#12. Thus, OpenSSL is required for some operations.

At present, it is capable of creating a new certificate "database" comprised of the cert8.db, key3.db, and secmod.db files. It is also capable of inserting ASCII .pem format X.509 certificates and private keys into a NSS database.

Usage

Security Considerations

This module creates an on-disk file in the path of the NSS database named nss-password.txt. This file contains the password used to encrypt private keys held by the database in plain txt.

Please consider the security implications before using this module.

Example

This is an example of setting up 389 Directory Service NSS db with externally supplied certificates.

nsstools::create { '/etc/dirsrv/slapd-ldap1':
  owner          => 'nobody',
  group          => 'nobody',
  mode           => '0660',
  password       => 'example',
  manage_certdir => false,
  enable_fips    => false,
}

nsstools::add_cert_and_key{ 'Server-Cert':
  certdir => '/etc/dirsrv/slapd-ldap1',
  cert    => '/tmp/foo.pem',
  key     => '/tmp/foo.key',
}

nsstools::add_cert { 'AlphaSSL CA':
  certdir => '/etc/dirsrv/slapd-ldap1',
  cert    => '/tmp/alphassl_intermediate.pem',
}

nsstools::add_cert { 'GlobalSign Root CA':
  certdir => '/etc/dirsrv/slapd-ldap1',
  cert    => '/tmp/globalsign_root.pem',
}

Classes

nsstools

This class is required by all of this module's types. It "owns" installation of the nss-tools package.

# defaults
class { 'nsstools':
  require_openssl => true,
}

• require_openssl

  Bool. Defaults to: true

  Enables/disables a requirement dependency being placed on Class[openssl].

Types

create

Create an empty NSS database with a password file.

# defaults
nsstools::create { <title>:
  password       => <password>, # required
  certdir        => <title>, # defaults to $title
  owner          => undef,
  group          => undef,
  mode           => '0600',
  certdir_mode   => '0700',
  manage_certdir => true,
  enable_fips    => false,
}

• title

  Used as the default value for the certdir parameter. If certdir is not set separately the value must pass validation as an absolute file path.

• password

  String Required

  Password to set on the database. There are Security Considerations to be aware of with this parameter.

• certdir

  String/absolute path Defaults to: title

  Absolute path to the directory to contain the database files. Please be aware that by setting both the title and certdir parameters it may be possible to declare multiple nsstools::create resources that point to the same set of NSS database files -- care must be taken to avoid such a scenario.

• owner

  String Defaults to: undef

  Sets user ownership of the NSS db files.

• group

  String Defaults to: undef

  User that owns the NSS db files.

• mode

  String Defaults to: 0600

• certdir_mode

  String Defaults to: 0700

• enable_fips

  Boolean Defaults to: true

  If true enables FIPS compliance mode on the NSS DB.

add_cert

Insert a certificate into an existing NSS database.

nsstools::add_cert { <title>:
  certdir  => <certdir>, # required
  cert     => <cert>, # required
  key      => <key>, # required
  nickname => <title> # defaults to $title
}

• title

  Used as the default value for the nickname parameter.

• certdir

  String/absolute path required Absolute path to the directory to contain the database files.

• cert

  String/absolute path required

  Absolute path to the certificate in .pem format to add to the database.

• nickname

  String defaults to: title

  The "nickname" of the certificate in the database.

• trustargs

  String defaults to: CT,,

  The certificate trust attributes in the database.

add_cert_and_key

Insert a certificate and it's associated private key an existing NSS database.

nsstools::add_cert_and_key { <title>:
  certdir  => <certdir>, # required
  cert     => <cert>, # required
  key      => <key>, # required
  nickname => <title> # defaults to $title
}

• title

  Used as the default value for the nickname parameter.

• certdir

  String/absolute path required

  Absolute path to the directory to contain the database files.

• cert

  String/absolute path required

  Absolute path to the certificate in .pem format to add to the database.

• key

  String/absolute path required

  Absolute path to the private key in .pem format (unencrypted) to add to the database.

• nickname

  String defaults to: title

  The "nickname" of the certificate in the database.

create_cert_and_key

Create a certificate and it's associated private key directly in an existing NSS database.

nsstools::create_cert_and_key { <title>:
  nickname => <title>, # defaults to $title
  subject  => <subject>, # required
  certdir  => <certdir>, # required
}

• title

  Used as the default value for the nickname parameter.

• nickname

  String defaults to: title

  The "nickname" of the certificate in the database.

• subject

  String required

  The subject of the certificate. The subject identification format follows RFC #1485.

• keytype

  String defaults to: 'rsa'

  The type of key to generate with the self signed cert. Valid options: ras|dsa|ec|all

• noisefile

  String/absolute path defaults to: '/var/log/messages'

  The path to a file to use as noise to generate the cert. The minimum file size is 20 bytes.

• certdir

  String/absolute path required

  Absolute path to the directory that contains the already created NSS database.

Functions

nsstools_add_cert

Iterates over a hash of cert nickname/path pairs (key/value) and creates nsstools::add_cert resources.

nsstools_add_cert(
  '/etc/dirsrv/slapd-ldap1',
  {
    'AlphaSSL CA'        => '/tmp/alphassl_intermediate.pem',
    'GlobalSign Root CA' => '/tmp/globalsign_root.pem',
  }
)

Would effectively define these resources:

nsstools::add_cert { 'AlphaSSL CA':
  certdir => '/etc/dirsrv/slapd-ldap1',
  cert    => '/tmp/alphassl_intermediate.pem',
}

nsstools::add_cert { 'GlobalSign Root CA':
  certdir => '/etc/dirsrv/slapd-ldap1',
  cert    => '/tmp/globalsign_root.pem',
}

Limitations

The functionality of this module is rather basic, it does not have facilities for:

• Inserting PKCS#12 files directly (trivial to add)
• Removal or purging of certificates

At present, only support for $::osfamily == 'RedHat' has been implemented. Adding other Linux distributions and operatingsystems should be trivial.

Tested Platforms

• el5.x
• el6.x
• el7.x

Puppet Version Compatibility

Versions	Puppet 2.7	Puppet 3.x	Puppet 4.x
1.x	yes	yes	no
2.x	no	yes	yes

Contributing

1. Fork it on github
2. Make a local clone of your fork
3. Create a topic branch. Eg, feature/mousetrap
4. Make/commit changes
   • Commit messages should be in imperative tense
   • Check that linter warnings or errors are not introduced - bundle exec rake lint
   • Check that Rspec-puppet unit tests are not broken and coverage is added for new features - bundle exec rake spec
   • Documentation of API/features is updated as appropriate in the README
   • If present, beaker acceptance tests should be run and potentially updated - bundle exec rake beaker
5. When the feature is complete, rebase / squash the branch history as necessary to remove "fix typo", "oops", "whitespace" and other trivial commits
6. Push the topic branch to github
7. Open a Pull Request (PR) from the topic branch onto parent repo's master branch

Versioning

Please log tickets and issues at github

See Also

• Network Security Services (NSS) libraries and tools.
• NSS Tools
• certutil
• PKCS#12
• pk12util
• OpenSSL
• openssl