Class: Puppet::SSL::CertificateAuthority

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/ssl/certificate_authority.rb,
lib/puppet/ssl/certificate_authority/interface.rb

Overview

The class that knows how to sign certificates. It creates a ‘special’ SSL::Host whose name is ‘ca’, thus indicating that, well, it’s the CA. There’s some magic in the indirector/ssl_file terminus base class that does that for us.

This class mostly just signs certs for us, but

it can also be seen as a general interface into all of the SSL stuff.

Defined Under Namespace

Classes: AutosignAlways, AutosignCommand, AutosignConfig, AutosignNever, CertificateSigningError, CertificateVerificationError, Interface

Constant Summary collapse

RequestExtensionWhitelist =

We will only sign extensions on this whitelist, ever. Any CSR with a requested extension that we don’t recognize is rejected, against the risk that it will introduce some security issue through our ignorance of it.

Adding an extension to this whitelist simply means we will consider it further, not that we will always accept a certificate with an extension requested on this list.

%w{subjectAltName}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ CertificateAuthority

Returns a new instance of CertificateAuthority.



155
156
157
158
159
160
161
162
163
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 155

def initialize
  Puppet.settings.use :main, :ssl, :ca

  @name = Puppet[:certname]

  @host = Puppet::SSL::Host.new(Puppet::SSL::Host.ca_name)

  setup
end

Instance Attribute Details

#host ⇒ Object (readonly)

Returns the value of attribute host.



61
62
63
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 61

def host
  @host
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



61
62
63
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 61

def name
  @name
end

Class Method Details

.ca? ⇒ Boolean

Returns:

  • (Boolean) 


51
52
53
54
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 51

def self.ca?
  # running as ca? - ensure boolean answer
  !!(Puppet[:ca] && Puppet.run_mode.master?)
end

.instance ⇒ Object

If this process can function as a CA, then return a singleton instance.



57
58
59
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 57

def self.instance
  ca? ? singleton_instance : nil
end

.singleton_instance ⇒ Object 



39
40
41
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 39

def self.singleton_instance
  @singleton_instance ||= new
end

Instance Method Details

#autosign(csr) ⇒ Void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

If autosign is configured, autosign the csr we are passed.

Parameters:

Returns:

  • (Void) 


67
68
69
70
71
72
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 67

def autosign(csr)
  if autosign?(csr)
    Puppet.info _("Autosigning %{csr}") % { csr: csr.name }
    sign(csr.name)
  end
end

#autosign?(csr) ⇒ true, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Determine if a CSR can be autosigned by the autosign store or autosign command

Parameters:

Returns:

  • (true, false) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 79

def autosign?(csr)
  auto = Puppet[:autosign]

  decider = case auto
    when false
      AutosignNever.new
    when true
      AutosignAlways.new
    else
      file = Puppet::FileSystem.pathname(auto)
      if Puppet::FileSystem.executable?(file)
        Puppet::SSL::CertificateAuthority::AutosignCommand.new(auto)
      elsif Puppet::FileSystem.exist?(file)
        AutosignConfig.new(file)
      else
        AutosignNever.new
      end
    end

  decider.allowed?(csr)
end

#certificate_is_alive?(cert) ⇒ Boolean

Deprecated.

use Puppet::SSL::CertificateAuthority#verify or Puppet Server certificate status API

Utility method which is API for PE license checking. This is used rather than ‘verify` because

1) We have already read the certificate from disk into memory.
   To read the certificate from disk again is just wasteful.
2) Because we're checking a large number of certificates against
   a transient CertificateAuthority, we can relatively safely cache
   the X509 Store that actually does the verification.

Long running instances of CertificateAuthority will certainly want to use ‘verify` because it will recreate the X509 Store with the absolutely latest CRL.

Additionally, this method explicitly returns a boolean whereas ‘verify` will raise an error if the certificate has been revoked.

Parameters:

Returns:

  • (Boolean) —

    true if signed, false if unsigned or revoked

Author:



479
480
481
482
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 479

def certificate_is_alive?(cert)
  Puppet.deprecation_warning(_("Puppet::SSL::CertificateAuthority#certificate_is_alive? is deprecated. Please use Puppet::SSL::CertificateAuthority#verify or the certificate status API to query certificate information. See https://docs.puppet.com/puppet/latest/http_api/http_certificate_status.html"))
  x509_store(:cache => true).verify(cert.content)
end

#check_internal_signing_policies(hostname, csr, options = {}) ⇒ Object 



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 333

def check_internal_signing_policies(hostname, csr, options = {})
  options[:allow_authorization_extensions] ||= false
  options[:allow_dns_alt_names] ||= false
  # This allows for masters to bootstrap themselves in certain scenarios
  options[:allow_dns_alt_names] = true if hostname == Puppet[:certname].downcase

  # Reject unknown request extensions.
  unknown_req = csr.request_extensions.reject do |x|
    RequestExtensionWhitelist.include? x["oid"] or
      Puppet::SSL::Oids.subtree_of?('ppRegCertExt', x["oid"], true) or
      Puppet::SSL::Oids.subtree_of?('ppPrivCertExt', x["oid"], true) or
      Puppet::SSL::Oids.subtree_of?('ppAuthCertExt', x["oid"], true)
  end

  if unknown_req and not unknown_req.empty?
    names = unknown_req.map {|x| x["oid"] }.sort.uniq.join(", ")
    raise CertificateSigningError.new(hostname), _("CSR has request extensions that are not permitted: %{names}") % { names: names }
  end

  # Do not sign misleading CSRs
  cn = csr.content.subject.to_a.assoc("CN")[1]
  if hostname != cn
    raise CertificateSigningError.new(hostname), _("CSR subject common name %{name} does not match expected certname %{expected}") % { name: cn.inspect, expected: hostname.inspect }
  end

  if hostname !~ Puppet::SSL::Base::VALID_CERTNAME
    raise CertificateSigningError.new(hostname), _("CSR %{hostname} subject contains unprintable or non-ASCII characters") % { hostname: hostname.inspect }
  end

  # Wildcards: we don't allow 'em at any point.
  #
  # The stringification here makes the content visible, and saves us having
  # to scrobble through the content of the CSR subject field to make sure it
  # is what we expect where we expect it.
  if csr.content.subject.to_s.include? '*'
    raise CertificateSigningError.new(hostname), _("CSR subject contains a wildcard, which is not allowed: %{subject}") % { subject: csr.content.subject.to_s }
  end

  unless csr.content.verify(csr.content.public_key)
    raise CertificateSigningError.new(hostname), _("CSR contains a public key that does not correspond to the signing key")
  end

  auth_extensions = csr.request_extensions.select do |extension|
    Puppet::SSL::Oids.subtree_of?('ppAuthCertExt', extension['oid'], true)
  end

  if auth_extensions.any? && !options[:allow_authorization_extensions]
    ext_names = auth_extensions.map do |extension|
      extension['oid']
    end

    raise CertificateSigningError.new(hostname), _("CSR '%{csr}' contains authorization extensions (%{extensions}), which are disallowed by default. Use `puppet cert --allow-authorization-extensions sign %{csr}` to sign this request.") % { csr: csr.name, extensions: ext_names.join(', ') }
  end

  unless csr.subject_alt_names.empty?
    # If you alt names are allowed, they are required. Otherwise they are
    # disallowed. Self-signed certs are implicitly trusted, however.
    unless options[:allow_dns_alt_names]
      raise CertificateSigningError.new(hostname), _("CSR '%{csr}' contains subject alternative names (%{alt_names}), which are disallowed. Use `puppet cert --allow-dns-alt-names sign %{csr}` to sign this request.") % { csr: csr.name, alt_names: csr.subject_alt_names.join(', ') }
    end

    # If subjectAltNames are present, validate that they are only for DNS
    # labels, not any other kind.
    unless csr.subject_alt_names.all? {|x| x =~ /^DNS:/ }
      raise CertificateSigningError.new(hostname), _("CSR '%{csr}' contains a subjectAltName outside the DNS label space: %{alt_names}.  To continue, this CSR needs to be cleaned.") % { csr: csr.name, alt_names: csr.subject_alt_names.join(', ') }
    end

    # Check for wildcards in the subjectAltName fields too.
    if csr.subject_alt_names.any? {|x| x.include? '*' }
      raise CertificateSigningError.new(hostname), _("CSR '%{csr}' subjectAltName contains a wildcard, which is not allowed: %{alt_names}  To continue, this CSR needs to be cleaned.") % { csr: csr.name, alt_names: csr.subject_alt_names.join(', ') }
    end
  end

  return true                 # good enough for us!
end

#crl ⇒ Object

Retrieves (or creates, if necessary) the certificate revocation list.



102
103
104
105
106
107
108
109
110
111
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 102

def crl
  unless defined?(@crl)
    unless @crl = Puppet::SSL::CertificateRevocationList.indirection.find(Puppet::SSL::CA_NAME)
      @crl = Puppet::SSL::CertificateRevocationList.new(Puppet::SSL::CA_NAME)
      @crl.generate(host.certificate.content, host.key.content)
      Puppet::SSL::CertificateRevocationList.indirection.save(@crl)
    end
  end
  @crl
end

#destroy(name) ⇒ Object

Delegates this to our Host class.



114
115
116
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 114

def destroy(name)
  Puppet::SSL::Host.destroy(name)
end

#fingerprint(name, md = :SHA256) ⇒ Object 



504
505
506
507
508
509
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 504

def fingerprint(name, md = :SHA256)
  unless cert = Puppet::SSL::Certificate.indirection.find(name) || Puppet::SSL::CertificateRequest.indirection.find(name)
    raise ArgumentError, _("Could not find a certificate or csr for %{name}") % { name: name }
  end
  cert.fingerprint(md)
end

#generate(name, options = {}) ⇒ Object

Generates a new certificate.

Returns:

  • Puppet::SSL::Certificate

Raises:

  • (ArgumentError) 


120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 120

def generate(name, options = {})
  raise ArgumentError, _("A Certificate already exists for %{name}") % { name: name } if Puppet::SSL::Certificate.indirection.find(name)

  # Pass on any requested subjectAltName field.
  san = options[:dns_alt_names]

  host = Puppet::SSL::Host.new(name)
  host.generate_certificate_request(:dns_alt_names => san)
  # CSR may have been implicitly autosigned, generating a certificate
  # Or sign explicitly
  host.certificate || sign(name, {allow_dns_alt_names: !!san})
end

#generate_ca_certificate ⇒ Object

Generate our CA certificate.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 134

def generate_ca_certificate
  generate_password unless password?

  host.generate_key unless host.key

  # Create a new cert request.  We do this specially, because we don't want
  # to actually save the request anywhere.
  request = Puppet::SSL::CertificateRequest.new(host.name)

  # We deliberately do not put any subjectAltName in here: the CA
  # certificate absolutely does not need them. --daniel 2011-10-13
  request.generate(host.key)

  # Create a self-signed certificate.
  @certificate = sign(host.name, {allow_dns_alt_names: false,
                                  self_signing_csr: request})

  # And make sure we initialize our CRL.
  crl
end

#generate_password ⇒ Object

Generate a new password for the CA.



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 171

def generate_password
  pass = ""
  20.times { pass += (rand(74) + 48).chr }

  begin
    # random password is limited to ASCII characters 48 ('0') through 122 ('z')
    Puppet.settings.setting(:capass).open('w:ASCII') { |f| f.print pass }
  rescue Errno::EACCES => detail
    raise Puppet::Error, _("Could not write CA password: %{detail}") % { detail: detail }, detail.backtrace
  end

  @password = pass

  pass
end

#inventory ⇒ Object

Retrieve (or create, if necessary) our inventory manager.



166
167
168
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 166

def inventory
  @inventory ||= Puppet::SSL::Inventory.new
end

#list(name = '*') ⇒ Array<String>

Lists the names of all signed certificates.

Parameters:

  • name (Array<string>) (defaults to: '*') —

    filter to cerificate names

Returns:

  • (Array<String>) 


192
193
194
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 192

def list(name='*')
  Puppet::SSL::Certificate.indirection.search(name).collect { |c| c.name }
end

#list_certificates(name = '*') ⇒ Array<Puppet::SSL::Certificate>

Deprecated.

Use Puppet::SSL::CertificateAuthority#list or Puppet Server Certificate status API

Return all the certificate objects as found by the indirector API for PE license checking.

Created to prevent the case of reading all certs from disk, getting just their names and verifying the cert for each name, which then causes the cert to again be read from disk.

Parameters:

  • name (Array<string>) (defaults to: '*') —

    filter to cerificate names

Returns:

Author:



211
212
213
214
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 211

def list_certificates(name='*')
  Puppet.deprecation_warning(_("Puppet::SSL::CertificateAuthority#list_certificates is deprecated. Please use Puppet::SSL::CertificateAuthority#list or the certificate status API to query certificate information. See https://docs.puppet.com/puppet/latest/http_api/http_certificate_status.html"))
  Puppet::SSL::Certificate.indirection.search(name)
end

#next_serial ⇒ Object

Read the next serial from the serial file, and increment the file so this one is considered used.



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 218

def next_serial
  serial = 1
  # the serial is 4 hex digits - limited to ASCII
  Puppet.settings.setting(:serial).exclusive_open('a+:ASCII') do |f|
    f.rewind
    serial = f.read.chomp.hex
    if serial == 0
      serial = 1
    end

    f.truncate(0)
    f.rewind

    # We store the next valid serial, not the one we just used.
    f << "%04X" % (serial + 1)
  end

  serial
end

#password? ⇒ Boolean

Does the password file exist?

Returns:

  • (Boolean) 


239
240
241
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 239

def password?
  Puppet::FileSystem.exist?(Puppet[:capass])
end

#print(name) ⇒ Object

Print a given host’s certificate as text.



244
245
246
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 244

def print(name)
  (cert = Puppet::SSL::Certificate.indirection.find(name)) ? cert.to_text : nil
end

#revoke(name) ⇒ Object

Revoke a given certificate.

Raises:

  • (ArgumentError) 


249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 249

def revoke(name)
  raise ArgumentError, _("Cannot revoke certificates when the CRL is disabled") unless crl

  cert = Puppet::SSL::Certificate.indirection.find(name)

  serials = if cert
              [cert.content.serial]
            elsif name =~ /^0x[0-9A-Fa-f]+$/
              [name.hex]
            else
              inventory.serials(name)
            end

  if serials.empty?
    raise ArgumentError, _("Could not find a serial number for %{name}") % { name: name }
  end

  serials.each do |s|
    crl.revoke(s, host.key.content)
  end
end

#setup ⇒ Object

This initializes our CA so it actually works. This should be a private method, except that you can’t any-instance stub private methods, which is awesome. This method only really exists to provide a stub-point during testing.



275
276
277
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 275

def setup
  generate_ca_certificate unless @host.certificate
end

#sign(hostname, options = {}) ⇒ Object

Sign a given certificate request.



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 280

def sign(hostname, options={})
  options[:allow_authorization_extensions] ||= false
  options[:allow_dns_alt_names] ||= false
  options[:self_signing_csr] ||= nil

  self_signing_csr = options.delete(:self_signing_csr)

  if self_signing_csr
    # # This is a self-signed certificate, which is for the CA.  Since this
    # # forces the certificate to be self-signed, anyone who manages to trick
    # # the system into going through this path gets a certificate they could
    # # generate anyway.  There should be no security risk from that.
    csr = self_signing_csr
    cert_type = :ca
    issuer = csr.content
  else
    unless csr = Puppet::SSL::CertificateRequest.indirection.find(hostname)
      raise ArgumentError, _("Could not find certificate request for %{hostname}") % { hostname: hostname }
    end

    cert_type = :server
    issuer = host.certificate.content

    # Make sure that the CSR conforms to our internal signing policies.
    # This will raise if the CSR doesn't conform, but just in case...
    check_internal_signing_policies(hostname, csr, options) or
      raise CertificateSigningError.new(hostname), _("CSR had an unknown failure checking internal signing policies, will not sign!")
  end

  cert = Puppet::SSL::Certificate.new(hostname)
  cert.content = Puppet::SSL::CertificateFactory.
    build(cert_type, csr, issuer, next_serial)

  signer = Puppet::SSL::CertificateSigner.new
  signer.sign(cert.content, host.key.content)

  Puppet.notice _("Signed certificate request for %{hostname}") % { hostname: hostname }

  # Add the cert to the inventory before we save it, since
  # otherwise we could end up with it being duplicated, if
  # this is the first time we build the inventory file.
  inventory.add(cert)

  # Save the now-signed cert.  This should get routed correctly depending
  # on the certificate type.
  Puppet::SSL::Certificate.indirection.save(cert)

  # And remove the CSR if this wasn't self signed.
  Puppet::SSL::CertificateRequest.indirection.destroy(csr.name) unless self_signing_csr

  cert
end

#verify(name) ⇒ Boolean

Verify a given host’s certificate. The certname is passed in, and the indirector will be used to locate the actual contents of the certificate with that name.

Parameters:

  • name (String) —

    certificate name to verify

Returns:

  • (Boolean) —

    true if signed, there are no cases where false is returned

Raises:

  • (ArgumentError) —

    if the certificate name cannot be found (i.e. doesn’t exist or is unsigned)

  • (CertificateVerficationError) —

    if the certificate has been revoked



495
496
497
498
499
500
501
502
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 495

def verify(name)
  unless cert = Puppet::SSL::Certificate.indirection.find(name)
    raise ArgumentError, _("Could not find a certificate for %{name}") % { name: name }
  end
  store = create_x509_store

  raise CertificateVerificationError.new(store.error), store.error_string unless store.verify(cert.content)
end

#waiting? ⇒ Boolean

List the waiting certificate requests.

Returns:

  • (Boolean) 


512
513
514
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 512

def waiting?
  Puppet::SSL::CertificateRequest.indirection.search("*").collect { |r| r.name }
end