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.



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

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) 



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

def host
  @host
end

#name ⇒ Object (readonly) 



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.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

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:



444
445
446
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 444

def certificate_is_alive?(cert)
  x509_store(:cache => true).verify(cert.content)
end

#check_internal_signing_policies(hostname, csr, allow_dns_alt_names) ⇒ Object 



323
324
325
326
327
328
329
330
331
332
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
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 323

def check_internal_signing_policies(hostname, csr, allow_dns_alt_names)
  # 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)
  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}"
  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 #{cn.inspect} does not match expected certname #{hostname.inspect}"
  end

  if hostname !~ Puppet::SSL::Base::VALID_CERTNAME
    raise CertificateSigningError.new(hostname), "CSR #{hostname.inspect} subject contains unprintable or non-ASCII characters"
  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: #{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

  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 allow_dns_alt_names
      raise CertificateSigningError.new(hostname), "CSR '#{csr.name}' contains subject alternative names (#{csr.subject_alt_names.join(', ')}), which are disallowed. Use `puppet cert --allow-dns-alt-names sign #{csr.name}` to sign this request."
    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.name}' contains a subjectAltName outside the DNS label space: #{csr.subject_alt_names.join(', ')}.  To continue, this CSR needs to be cleaned."
    end

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



468
469
470
471
472
473
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 468

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}"
  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}" 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, !!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
 
# 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, false, request)

  # And make sure we initialize our CRL.
  crl
end

#generate_password ⇒ Object

Generate a new password for the CA.



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

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

  begin
    Puppet.settings.setting(:capass).open('w') { |f| f.print pass }
  rescue Errno::EACCES => detail
    raise Puppet::Error, "Could not write CA password: #{detail}", detail.backtrace
  end

  @password = pass

  pass
end

#inventory ⇒ Object

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



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

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:



190
191
192
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 190

def list(name='*')
  list_certificates(name).collect { |c| c.name }
end

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

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:



207
208
209
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 207

def list_certificates(name='*')
  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.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 213

def next_serial
  serial = 1
  Puppet.settings.setting(:serial).exclusive_open('a+') 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) 


233
234
235
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 233

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

#print(name) ⇒ Object

Print a given host’s certificate as text.



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

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

#revoke(name) ⇒ Object

Revoke a given certificate.

Raises:

  • (ArgumentError) 


243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 243

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}"
  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.



269
270
271
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 269

def setup
  generate_ca_certificate unless @host.certificate
end

#sign(hostname, allow_dns_alt_names = false, self_signing_csr = nil) ⇒ Object

Sign a given certificate request.



274
275
276
277
278
279
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
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 274

def sign(hostname, allow_dns_alt_names = false, self_signing_csr = nil)
  # This is a self-signed certificate
  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
    allow_dns_alt_names = true if hostname == Puppet[:certname].downcase
    unless csr = Puppet::SSL::CertificateRequest.indirection.find(hostname)
      raise ArgumentError, "Could not find certificate request for #{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, allow_dns_alt_names) 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}"

  # 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



459
460
461
462
463
464
465
466
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 459

def verify(name)
  unless cert = Puppet::SSL::Certificate.indirection.find(name)
    raise ArgumentError, "Could not find a certificate for #{name}"
  end
  store = 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) 


476
477
478
 
# File 'lib/puppet/ssl/certificate_authority.rb', line 476

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