Puppet

1

# Certificates and Security

2

1

3

1

## Overview

4

1

5

1

Puppet relies on standards wherever possible. In the case of

6

1

security, it uses standard SSL certificates for client and master

7

1

verification. This means that a client verifies that it's talking

8

1

with the right master and the master verifies that it's talking

9

1

with the right client. Because of the cost of buying signed

10

1

certificates for every client and the complexity of managing your

11

1

own certificate authority (CA), Puppet includes its own CA. This CA

12

1

has been optimized for use with Puppet but could also be used to

13

1

generate certificates for other purposes. The primary goal in

14

1

certificate management within Puppet has been to keep it simple,

15

1

and wherever possible to not make it even noticeable.

16

1

17

1

puppetca is the application for managing Puppet's certification

18

1

authority. It allows you to generate certificates, revoke them,

19

1

sign them, remove them and list pending signature requests. By

20

1

default the Puppet master, puppetmasterd, functions as a

21

1

certificate authority.

22

1

23

1

## Certificates

24

1

25

1

Certificates for clients and masters are generated automatically

26

1

when puppetd or puppetmasterd are run for the first time,

27

1

respectively. puppetd, the client side of Puppet, will accept the

28

1

master's certificate when it first connects to it and save it. From

29

1

then on it will verify that the certificate it gets from the master

30

1

verifies its identity.

31

1

32

1

You can manually copy the master certificate through a secure

33

1

channel to the client if you want to, hence closing the small

34

1

window for a man-in-the-middle attack.

35

1

36

1

### Authentication

37

1

38

1

Certificates are the only method of authentication -- if a client's

39

1

certificate can be verified using standard SSL verification

40

1

mechanisms, then it is considered authenticated. Likewise for

41

1

client validation of the master.

42

1

43

1

### Encryption

44

1

45

1

Puppet also makes use of SSL to encrypt the traffic flow between

46

1

master and clients.

47

1

48

1

### Client Certificate Generation

49

1

50

1

Clients who do not yet have signed certificates will automatically

51

1

generate a key pair and a certificate request, and then will

52

1

connect to the master and provide it with the certificate request.

53

1

If the master has autosign turned on (which is not necessarily

54

1

recommended - see why autosign is dangerous?), then the autosign

55

1

configuration file (which defaults to /etc/puppet/autosign.conf) is

56

1

checked for whether the client's name matches any contents. For

57

1

instance, take the following configuration file:

58

1

59

1

    hostname.domain.com

60

1

    *.secure.domain.com

61

1

62

1

This configuration would autosign certificate requests for

63

1

hostname.domain.com and any hosts coming from

64

1

\*.secure.domain.com.

65

1

66

1

This configuration file is read each time a signature is asked for,

67

1

so changes to it can be short-lived and will be immediately

68

1

noticed.

69

1

70

1

### Master-Side Certificate Management

71

1

72

1

In the normal case, certificate auto-signing will be disabled. In

73

1

these cases, certificates will have to be signed using the puppetca

74

1

utility. Prior to the 1.0 release it is expected that there will be

75

1

email notification of certificate requests waiting to be signed,

76

1

but for now either the logs must be watched or puppetca --list can

77

1

be used list waiting requests.

78

1

79

1

Once a request arrives, puppetca --sign \<hostname> can be used to

80

1

sign the request. Adding the --all flag will sign all outstanding

81

1

requests. A list of all certificates ever issued by Puppet's CA can

82

1

be found in the file $cadir/inventory.txt.

83

1

84

1

All certificate files for a given host can be removed (for

85

1

rebuilding hosts, for instance) with puppetca --clean \<hostname>.

86

1

87

1

Certificates, once issued, can be revoked with puppetca --revoke

88

1

\<hostname|serial>. The server consults the certificate revocation

89

1

list (CRL) every time a client tries to connect to the server; for

90

1

revocations to take effect, the server must be restarted after the

91

1

certificate revocation with puppetca.

92

1

93

1

### Master-Side Client Certificate Generation

94

1

95

1

It is possible to generate certificates for clients on the master

96

1

side, by using puppetca --generate \<hostname>; this will also sign

97

1

the newly generated certificate. You might want to do this if you

98

1

want to automate the conversion of non-Puppet managed servers to

99

1

Puppet. You can run a script that copies the generated client keys

100

1

to the right place on the client, installs Puppet and then runs

101

1

puppetd to get the client's configuration. This would allow you to

102

1

"Puppetize" a server with a single command. When you run puppetca

103

1

--generate \<hostname> three files are generated -

104

1

$signeddir/hostname.pem, $certdir/hostname.pem and

105

1

$privatekeydir/hostname.pem. You need to copy the private key, the

106

1

client certificate, and the certificate for the master (ca.pem) to

107

1

the corresponding directories on the client side. The client public

108

1

key will be extracted from its certificate and put into

109

1

$publickeydir when puppetd is run. The defaults for these

110

1

directories should be subdirectories under /etc/puppet/ssl/ with

111

1

self-explanatory names, look there to find the generated files.

112

1

113

1

[This article](http://watzmann.net/blog/index.php/2006/08/07/using_pregenerated_certs_with_puppet)

114

1

provides an example of an implementation approach that uses USB

115

1

keys to transfer the certificates from the master to client. Other

116

1

approaches could include transferring the certificates during the

118

1

[JumpStart](http://en.wikipedia.org/wiki/Jumpstart_(Solaris)), or

119

1

similar

120

1

[OS post-installation script](http://www.openbsd.org/faq/faq4.html#site)

121

1

process.

122

1

123

1

### Master-Side Client Certificate Revocation

124

1

125

1

As Puppet deploys a full

126

1

[PKI](http://en.wikipedia.org/wiki/Public_key_infrastructure), it

127

1

also allows to revoke a client certificate, if this client

128

1

certificate or private key is compromised.

129

1

130

1

When a client certificate is revoked, its serial number is added to

131

1

the current Certificate Revocation List (CRL for short). Since this

132

1

file is signed by the CA certificate the CRL itself can be verified

133

1

and can't be tampered.

134

1

135

1

When a revoked client connects to the puppetmaster to check-out its

136

1

configuration its connection is denied (provided you instructed

137

1

your proxy if you use one to check the CRL, see [[Using Mongrel]] ,

138

1

[[Using Mongrel Nginx]] , [[Using Mongrel Pound]] , [[Using

139

1

Passenger]]

140

1

141

1

The CRL if used to revoke only client certificate needs to be

142

1

present only on the master. To revoke a certificate, issue on the

143

1

master: puppetca --revoke \<hostname>

144

1

145

1

### Manual CA Configuration (optional)

146

1

147

1

If you are very paranoid you can consider setting up a separate CA

148

1

manually rather than relying on puppet's built-in CA. You can

149

1

thereby restrict CA access to least privilege rather than letting

150

1

puppetd and puppetmasterd do the work for you. Beware! This is for

151

1

SSL experts only...

152

1

153

1

Adapt default permissions and locations for CA files and

154

1

directories in your puppet installation's default.rb along the

155

1

following lines. If you don't do this puppetmasterd will change

156

1

permissions back to default each time you start it up. You have to

157

1

install all keys and certificates *before* launching

158

1

puppetmasterd/puppetd for the first time:

159

1

160

1

-   root CA key: neither readable nor writeable by

161

1

    puppetd/puppetmasterd or any other process, possibly installed on a

162

1

    separate and specially secured machine where you'll do the signing

163

1

    of client certificate requests

164

1

-   trusted root CA certificate: readable but not writeable by

165

1

    puppetd/puppetmasterd

166

1

-   client CA keys: readable but not writeable by the process to be

167

1

    authenticated, not readable by any other process

168

1

-   certificate revocation list: readable but not writeable by

169

1

    puppetmasterd

170

1

171

1

Be aware though that a separate CA will not protect your puppet

172

1

clients in all cases when your puppetmasterd has been compromised

173

1

(see [#1590](http://projects.reductivelabs.com/issues/show/1590)

174

1

for a discussion). According to your individual security policy

175

1

you'll have to put other measures in place to keep malicious users

176

1

from accessing puppetmasterd and puppetd processes or their

177

1

configuration in the first place.

178

1

179

1

## Access and Authorization

180

1

181

1

Puppet currently has few network functions, so security has so far

182

1

been treated by them individually. It is expected that there will

183

1

be some system-wide security hooks prior to the 1.0 release, but

184

1

the certificate authentication already provides significant

185

1

security.

186

1

187

1

Recommendations on approaches are heartily recommended.

188

1

189

1

## Examples

190

1

191

1

To introduce a client machine to the puppet server, first run

192

1

puppetd on the client with the waitforcert parameter:

193

1

194

1

    $ puppetd --waitforcert 30 --server puppetserver.domain.net -v

195

1

196

1

The client will request a certificate from the certificate

197

1

authority facility on the server called puppetserver.domain.net.

198

1

199

1

Assuming that the machine puppetserver is not set to autosign any

200

1

new certificate requests (this is the default), you'll need to list

201

1

the certificate requests from the command line on the server with

202

1

an invocation like this:

203

1

204

1

    $ puppetca --list

205

1

206

1

You'll then be able to pick out the request by name (quite

207

1

possibly, it will be the only request waiting) and instruct the

208

1

certificate authority to sign the request:

209

1

210

1

    $ puppetca --sign puppetclient-37.domain.net

211

1

212

1

## Common Caveats

213

1

214

1

-   When trying to run puppetd on a client and you get something

215

1

    like the following:

216

1

        warning: Certificate validation failed; consider using the certname configuration option

217

1

        err: Could not retrieve catalog: Certificates were not trusted: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

218

1

222

1

    Check that the clocks between the puppetmaster and client are in

223

1

    sync, if the client is behind when the certificate was generated,

224

1

    then the client sees that the start date of the certificate is in

225

1

    the future and therefore is invalid. Just for reference you can

226

1

    find out this info from the cert using the following:

227

1

        openssl x509 -text -noout -in /var/lib/puppet/ssl/certs/hostname.tld.pem | grep -A2 Validity

228

1

                Validity

229

1

                    Not Before: Apr 19 23:21:29 2009 GMT

230

1

                    Not After : Apr 18 23:21:29 2014 GMT

Certificates And Security