Skip to content

Commit 6617c93

Browse files
marainomaraino
committed
Add new example and docs on the client SDK.
1 parent 7eb8aeb commit 6617c93

File tree

2 files changed

+287
-4
lines changed

2 files changed

+287
-4
lines changed

‎examples/README.md

+135-4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,137 @@
1-
# Example
1+
# Examples
22

3-
# Bootstrap Client & Server
3+
## Basic client usage
4+
5+
The basic-client example shows the use of the most of the functioanlity of the
6+
`ca.Client`, those methods works as an SDK for integrating other services with
7+
the Certificate Authority (CA).
8+
9+
In [basic-client/client.go](/examples/basic-client/client.go) we first can see
10+
the initialization of the client:
11+
12+
```go
13+
client, err := ca.NewClient("https://localhost:9000", ca.WithRootSHA256("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d"))
14+
```
15+
16+
The previous code uses the CA address and the root certificate fingerprint.
17+
The CA url will be present in the token, and the root fingerprint can be present
18+
too if the `--root root_ca.crt` option is use in the creation of the token. If
19+
this is the case is simpler to rely in the token and use just:
20+
21+
```go
22+
client, err := ca.Bootstrap(token)
23+
```
24+
25+
After the initialization there're examples of all the client methods, they are
26+
just a convenient way to use the CA API endpoints. The first method `Health`
27+
returns the status of the CA server, on the first implementation if the server
28+
is up it will return just ok.
29+
30+
```go
31+
health, err := client.Health()
32+
// Health is a struct created from the JSON response {"status": "ok"}
33+
```
34+
35+
The next method `Root` is used to get and verify the root certificate. We will
36+
pass a finger print, it will download the root certificate from the CA and it
37+
will make sure that the fingerprint matches. This method uses an insecure HTTP
38+
client as it might be used in the initialization of the client, but the response
39+
is considered secure because we have compared against the given digest.
40+
41+
```go
42+
root, err := client.Root("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d")
43+
```
44+
45+
After Root we have the most important method `Sign`, this is used to sign a
46+
Certificate Signing Request that we provide. To secure this request we use
47+
the one-time-token. You can build your own certificate request and add it in
48+
the `*api.SignRequest`, but the ca package contains a method that will create a
49+
secure random key, and create the CSR based on the information in the token.
50+
51+
```go
52+
// Create a CSR from token and return the sign request, the private key and an
53+
// error if something failed.
54+
req, pk, err := ca.CreateSignRequest(token)
55+
if err != nil { ... }
56+
57+
// Do the sign request and return the signed certificate
58+
sign, err := client.Sign(req)
59+
if err != nil { ... }
60+
```
61+
62+
To renew the certificate we can use the `Renew` method, the certificate renewal
63+
relies on a mTLS connection with a previous certificate, so we will need to pass
64+
a transport with the previous certificate.
65+
66+
```go
67+
// Get a cancelable context to stop the renewal goroutines and timers.
68+
ctx, cancel := context.WithCancel(context.Background())
69+
defer cancel()
70+
// Create a transport from with the sign response and the private key.
71+
tr, err := client.Transport(ctx, sign, pk)
72+
if err != nil { ... }
73+
// Renew the certificate and get the new ones.
74+
// The return type are equivalent to ones in the Sign method.
75+
renew, err := client.Renew(tr)
76+
if err != nil { ... }
77+
```
78+
79+
All the previous methods map with one endpoint in the CA API, but the API
80+
provides a couple more that are used for creating the tokens. For those we have
81+
a couple of methods, one that returns a list of provisioners and one that
82+
returns the encrypted key of one provisioner.
83+
84+
```go
85+
// Without options it will return the first 20 provisioners
86+
provisioners, err := client.Provisioners()
87+
// We can also set a limit up to 100
88+
provisioners, err := client.Provisioners(ca.WithProvisionerLimit(100))
89+
// With a pagination cursor
90+
provisioners, err := client.Provisioners(ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"))
91+
// Or combining both
92+
provisioners, err := client.Provisioners(
93+
ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"),
94+
ca.WithProvisionerLimit(100),
95+
)
96+
97+
// Return the encrypted key of one of the returned provisioners. The key
98+
// returned is an encrypted JWE with the private key used to sign tokens.
99+
key, err := client.ProvisionerKey("DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk")
100+
```
101+
102+
The example shows also the use of some helper methods used to get configured
103+
tls.Config objects that can be injected in servers and clients. These methods,
104+
are also configured to auto-renew the certificate once two thirds of the
105+
duration of the certificate has passed, approximately.
106+
107+
```go
108+
// Get a cancelable context to stop the renewal goroutines and timers.
109+
ctx, cancel := context.WithCancel(context.Background())
110+
defer cancel()
111+
// Get tls.Config for a server
112+
tlsConfig, err := client.GetClientTLSConfig(ctx, sign, pk)
113+
// Get tls.Config for a client
114+
tlsConfig, err := client.GetClientTLSConfig(ctx, sign, pk)
115+
// Get an http.Transport for a client, this can be used as a http.RoundTripper
116+
// in an http.Client
117+
tr, err := client.Transport(ctx, sign, pk)
118+
```
119+
120+
To run the example you need to start the certificate authority:
121+
122+
```
123+
certificates $ bin/step-ca examples/pki/config/ca.json
124+
2018/11/02 18:29:25 Serving HTTPS on :9000 ...
125+
```
126+
127+
And just run the client.go with a new token:
128+
```
129+
certificates $ export STEPPATH=examples/pki
130+
certificates $ export STEP_CA_URL=https://localhost:9000
131+
certificates $ go run examples/basic-client/client.go $(step ca new-token client.smallstep.com))
132+
```
133+
134+
## Bootstrap Client & Server
4135

5136
On this example we are going to see the Certificate Authority running, as well
6137
as a simple Server using TLS and a simple client doing TLS requests to the
@@ -18,7 +149,7 @@ certificates $ bin/step-ca examples/pki/config/ca.json
18149
We will start the server and we will type `password` when step asks for the
19150
provisioner password:
20151
```
21-
certificates $ export STEPPATH=examples/pki
152+
certificates $ export STEPPATH=examples/pki
22153
certificates $ export STEP_CA_URL=https://localhost:9000
23154
certificates $ go run examples/bootstrap-server/server.go $(step ca new-token localhost))
24155
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
@@ -56,7 +187,7 @@ detected a TLS client configuration.
56187

57188
But if we the client with the certificate name Mike we'll see:
58189
```
59-
certificates $ export STEPPATH=examples/pki
190+
certificates $ export STEPPATH=examples/pki
60191
certificates $ export STEP_CA_URL=https://localhost:9000
61192
certificates $ go run examples/bootstrap-client/client.go $(step ca new-token Mike)
62193
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)

‎examples/basic-client/client.go

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"encoding/json"
6+
"fmt"
7+
"net"
8+
"net/http"
9+
"os"
10+
"time"
11+
12+
"github.com/smallstep/certificates/ca"
13+
)
14+
15+
func printResponse(name string, v interface{}) {
16+
b, err := json.MarshalIndent(v, "", " ")
17+
if err != nil {
18+
panic(err)
19+
}
20+
fmt.Printf("%s response:\n%s\n\n", name, b)
21+
}
22+
23+
func main() {
24+
if len(os.Args) != 2 {
25+
fmt.Fprintf(os.Stderr, "Usage: %s <token>\n", os.Args[0])
26+
os.Exit(1)
27+
}
28+
29+
token := os.Args[1]
30+
31+
// To create the client using ca.NewClient we need:
32+
// * The CA address "https://localhost:9000"
33+
// * The root certificate fingerprint
34+
// 84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d to get
35+
// the root fingerprint we can use `step certificate fingerprint root_ca.crt`
36+
client, err := ca.NewClient("https://localhost:9000", ca.WithRootSHA256("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d"))
37+
if err != nil {
38+
panic(err)
39+
}
40+
41+
// Other ways to initialize the client would be:
42+
// * With the Bootstrap functionality (recommended):
43+
// client, err := ca.Bootstrap(token)
44+
// * Using the root certificate instead of the fingerprint:
45+
// client, err := ca.NewClient("https://localhost:9000", ca.WithRootFile("../pki/secrets/root_ca.crt"))
46+
47+
// Get the health of the CA
48+
health, err := client.Health()
49+
if err != nil {
50+
panic(err)
51+
}
52+
printResponse("Health", health)
53+
54+
// Get and verify a root CA
55+
root, err := client.Root("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d")
56+
if err != nil {
57+
panic(err)
58+
}
59+
printResponse("Root", root)
60+
61+
// We can use ca.CreateSignRequest to generate a new sign request with a
62+
// randomly generated key.
63+
req, pk, err := ca.CreateSignRequest(token)
64+
if err != nil {
65+
panic(err)
66+
}
67+
sign, err := client.Sign(req)
68+
if err != nil {
69+
panic(err)
70+
}
71+
printResponse("Sign", sign)
72+
73+
// Renew a certificate with a transport that contains the previous
74+
// certificate. We should created a context that allows us to finish the
75+
// renewal goroutine.∑
76+
ctx, cancel := context.WithCancel(context.Background())
77+
defer cancel() // Finish the renewal goroutine
78+
tr, err := client.Transport(ctx, sign, pk)
79+
if err != nil {
80+
panic(err)
81+
}
82+
renew, err := client.Renew(tr)
83+
if err != nil {
84+
panic(err)
85+
}
86+
printResponse("Renew", renew)
87+
88+
// Get tls.Config for a server
89+
ctxServer, cancelServer := context.WithCancel(context.Background())
90+
defer cancelServer()
91+
tlsConfig, err := client.GetServerTLSConfig(ctxServer, sign, pk)
92+
if err != nil {
93+
panic(err)
94+
}
95+
// An http server will use the tls.Config like:
96+
_ = &http.Server{
97+
Addr: ":443",
98+
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
99+
w.Write([]byte("Hello world"))
100+
}),
101+
TLSConfig: tlsConfig,
102+
}
103+
104+
// Get tls.Config for a client
105+
ctxClient, cancelClient := context.WithCancel(context.Background())
106+
defer cancelClient()
107+
tlsConfig, err = client.GetClientTLSConfig(ctxClient, sign, pk)
108+
// An http.Client will need to create a transport first
109+
_ = &http.Client{
110+
Transport: &http.Transport{
111+
TLSClientConfig: tlsConfig,
112+
// Options set in http.DefaultTransport
113+
Proxy: http.ProxyFromEnvironment,
114+
DialContext: (&net.Dialer{
115+
Timeout: 30 * time.Second,
116+
KeepAlive: 30 * time.Second,
117+
DualStack: true,
118+
}).DialContext,
119+
MaxIdleConns: 100,
120+
IdleConnTimeout: 90 * time.Second,
121+
TLSHandshakeTimeout: 10 * time.Second,
122+
ExpectContinueTimeout: 1 * time.Second,
123+
},
124+
}
125+
126+
// But we can just use client.Transport to get the default configuration
127+
ctxTransport, cancelTransport := context.WithCancel(context.Background())
128+
defer cancelTransport()
129+
tr, err = client.Transport(ctxTransport, sign, pk)
130+
// And http.Client will use the transport like
131+
_ = &http.Client{
132+
Transport: tr,
133+
}
134+
135+
// Get provisioners and provisioner keys. In this example we add two
136+
// optional arguments with the initial cursor and a limit.
137+
//
138+
// A server or a client should not need this functionality, they are used to
139+
// sign (private key) and verify (public key) tokens. The step cli can be
140+
// used for this purpose.
141+
provisioners, err := client.Provisioners(ca.WithProvisionerCursor(""), ca.WithProvisionerLimit(100))
142+
if err != nil {
143+
panic(err)
144+
}
145+
printResponse("Provisioners", provisioners)
146+
// Get encrypted key
147+
key, err := client.ProvisionerKey("DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk")
148+
if err != nil {
149+
panic(err)
150+
}
151+
printResponse("Provisioner Key", key)
152+
}

0 commit comments

Comments
 (0)