Go言語でPKI入門（勝手に復刻）: ACME編

# はじめに

Go言語でPKI入門（勝手に復刻版）

https://qiita.com/twsnmp/items/60ba568f0daca8bae915

のACME編です。

# ACMEについて

Automatic Certificate Management Environment (ACME)は、
サーバー証明書の管理を自動化するための仕組みです。

Let’s Encryptによる証明書発行の自動化のために使われています。

https://letsencrypt.org/ja/how-it-works/

に詳しい説明があります。

# RFC8555

ACMEのプロトコル仕様は、RFC8555で定義されています。

https://tex2e.github.io/rfc-translater/html/rfc8555.html


まじめに全部読んで理解したほうがよいと思いますが、ざっくり要点だけ読んでまとめた図は

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3874862/cc5138a4-780f-47f8-8923-2ff0f77312c0.png)

のようになります。

# stepcaのソースコード分析

インターネット環境でサーバー証明書の発行を自動化したければ、Let’s Encryptを使えばよいのですが、
プラベートな環境でも証明書の発行を自動化したいことがあると思います。その場合に使えるのが、stepca

https://smallstep.com/docs/step-ca/#introduction-to-step-ca

です。使い方を

https://qiita.com/twsnmp/items/1ef467d697cfe13a4617

の記事に書きました。

このサーバーはGo言語で開発されていて、GitHUBで公開されています。

https://github.com/smallstep/certificates

ACMEのソースコードは、パッケージとして他のプロジェクトから使えるような状態ではありません。
そこで、まじめにソースコードを読んで必要部分を整理しました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3874862/10d61d7c-d518-4de7-a04f-de4fc4deb9b5.png)


のような処理です。


# Go言語でACMEサーバーを実装

ここまでの情報を元に、Go言語でACMEサーバーを実装してみました。
そのポイントを説明します。


##  ACMEサーバー用証明書

ACMEサーバーはHTTPSで通信する必要があります。そのためサーバー証明書と秘密鍵が必要です。
以前の記事の応用ですが、サーバー証明書は、

```go
func CreateAcmeServerCertificate() {
	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		panic(err)
	}
	publicKey := &key.PublicKey
	ca, err := x509.ParseCertificate(rootCACertificate)
	if err != nil {
		panic(err)
	}
	certTpl := &x509.Certificate{
		SerialNumber: serial,
		Subject: pkix.Name{
			CommonName:         "acme.example.org",
			OrganizationalUnit: []string{"Example Org Unit"},
			Organization:       []string{"Example Org"},
			Country:            []string{"JP"},
		},
		NotBefore:             time.Now().UTC(),
		NotAfter:              time.Now().AddDate(1, 0, 0).UTC(),
		KeyUsage:              x509.KeyUsageDigitalSignature,
		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
		DNSNames:              []string{"acme.example.com", "localhost"},
		EmailAddresses:        []string{"test@examle.com"},
		IPAddresses:           []net.IP{net.ParseIP("127.0.0.1")},
		IsCA:                  false,
		BasicConstraintsValid: true,
		CRLDistributionPoints: []string{"http://127.0.0.1:5585/crl"},
		OCSPServer:            []string{"http://127.0.0.1:5585/ocsp"},
	}
	cert, err := x509.CreateCertificate(rand.Reader, certTpl, ca, publicKey, rootCAPrivateKey)
	if err != nil {
		panic(err)
	}
	OutPem(cert, "./acme.crt", "CERTIFICATE")
	if b, err := x509.MarshalECPrivateKey(key); err == nil {
		OutPem(b, "./acme.key", "EC PRIVATE KEY")
	}
	serial.Add(serial, big.NewInt(1))
}

```

acme.crtに証明書、acme.keyにサーバー証明書を作成します。


## HTTPSサーバー

ACMEサーバーはHTTPSで動作します。Go言語標準のHTTPパッケージでも作れますが、
より簡単に作るためのEcho


https://echo.labstack.com

を使います。
サーバーの設定は、

```go
var baseURL = "https://127.0.0.1:9001"

func ACMEServer() {
	e := echo.New()
	e.Use(middleware.RequestLoggerWithConfig(middleware.RequestLoggerConfig{
		LogStatus:        true,
		LogURI:           true,
		LogMethod:        true,
		LogContentLength: true,
		LogValuesFunc: func(c echo.Context, v middleware.RequestLoggerValues) error {
			fmt.Printf("%s %v %v %s\n", v.Method, v.URI, v.Status, v.ContentLength)
			return nil
		},
	}))
    // ここでeにACMEの処置を追加する
	if err := e.StartTLS(":9001", "acme.crt", "acme.key"); err != http.ErrServerClosed {
		log.Fatal(err)
	}
}

```

のようにします。先ほど作った証明書と秘密鍵を使ってHTTPSで起動しています。
eにACMEのリクエストの処理を追加すれば、ACMEサーバーになります。

## /directory

APIのURLを取得するたための最初のエントリーです。

```go
    var baseURL = "https://127.0.0.1:9001"
	e.GET("/directory", func(c echo.Context) error {
		d := Directory{
			NewNonce:   baseURL + "/new-nonce",
			NewAccount: baseURL + "/new-account",
			NewOrder:   baseURL + "/new-order",
			RevokeCert: baseURL + "/revoke-cert",
			KeyChange:  baseURL + "/key-change",
		}
		return c.JSON(http.StatusOK, d)
	})

```

Echoを使っているので簡単にJSONの応答を返せます。

## /nonce

noceの生成は、HEADとGETで処理をします。
HEADの場合とGETの場合で応答コードが違います。

```go
	e.HEAD("/new-nonce", func(c echo.Context) error {
		addHeader(c)
		return c.NoContent(http.StatusOK)
	})
	e.GET("/new-nonce", func(c echo.Context) error {
		addHeader(c)
		return c.NoContent(http.StatusNoContent)
	})
```


### 共通の処理

共通のヘッダを返す処理とnoceを作る処理は


```go
func addHeader(c echo.Context) {
	c.Response().Header().Add("Replay-Nonce", CreateNonce())
	c.Response().Header().Add("Link", baseURL+"/directory/index")
	c.Response().Header().Add(echo.HeaderCacheControl, "no-store")
}
func CreateNonce() string {
	b := make([]byte, 32)
	if _, err := rand.Read(b); err != nil {
		return "bad nonce"
	}
	var s string
	for _, v := range b {
		s += string(v%byte(94) + 33)
	}
	return base64.RawURLEncoding.EncodeToString([]byte(s))
}

```


## /new-account

アカウントの作成です。

```go

	e.POST("/new-account", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("new-account err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		jwk := extractJWK(jws)
		if jwk == nil {
			log.Println("new-account jwk not found")
			return c.JSON(http.StatusBadRequest, err)
		}
		payload, err := jws.Verify(jwk)
		if err != nil {
			log.Printf("new-account err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		var nar NewAccountRequest
		if err := json.Unmarshal(payload, &nar); err != nil {
			log.Printf("new-account err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// narのチェック、
		acc := &Account{
			ID:        jwk.KeyID,
			Key:       jwk,
			Status:    "valid",
			Contact:   nar.Contact,
			OrdersURL: baseURL + "/account/yErbu3KD7bEdxbXsBlaJ82l5VRdtos5W/orders",
		}
		accMap[acc.ID] = acc
		c.Response().Header().Add("Location", baseURL+"/account/"+acc.ID)
		return c.JSON(http.StatusCreated, acc)
	})
```

## /new-order

証明書の発行を受け付けます。
オーダーを受付をチェックしてOKなら登録します。

```go
	e.POST("/new-order", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("new-order err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		acc, err := lookupJWKAndAccount(jws)
		if err != nil {
			log.Printf("new-order err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		payload, err := jws.Verify(acc.Key)
		if err != nil {
			log.Printf("new-order err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		var nor NewOrderRequest
		if err := json.Unmarshal(payload, &nor); err != nil {
			log.Printf("new-order err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		now := time.Now().UTC().Truncate(time.Second)
		// norのチェック、
		o := &Order{
			ID:                CreateNonce(),
			AccountID:         acc.ID,
			Status:            "pending",
			Identifiers:       nor.Identifiers,
			ExpiresAt:         now.Add(time.Hour * 24),
			AuthorizationIDs:  make([]string, len(nor.Identifiers)),
			AuthorizationURLs: make([]string, len(nor.Identifiers)),
			NotBefore:         nor.NotBefore,
			NotAfter:          nor.NotAfter,
		}
		for i, identifier := range o.Identifiers {
			azID := CreateNonce()
			// identifierのタイプ(ホスト名、IPなど)から
			// CAが発行できる証明書であることをチェックし
			// チャレンジのタイプを設定する
			chTypes := []string{}
			switch identifier.Type {
			case "ip":
				chTypes = append(chTypes, "http-01")
				chTypes = append(chTypes, "tls-alpn-01")
			case "dns":
				chTypes = append(chTypes, "dns-01")
				if strings.HasPrefix(identifier.Value, "*") {
					chTypes = append(chTypes, "http-01")
					chTypes = append(chTypes, "tls-alpn-01")
				}
			case "permanent-identifier":
				// TPM,Apple,YubiKeyなどのデバイス
				chTypes = append(chTypes, "device-attest-01")
			case "wireapp-user":
				// OpenID Connect
			case "wireapp-device":
				// OpenID Connect
			}
			az := &Authorization{
				ID:         azID,
				AccountID:  acc.ID,
				Identifier: identifier,
				ExpiresAt:  o.ExpiresAt,
				Status:     "pending",
				Challenges: []*Challenge{},
				Token:      CreateNonce(),
			}
			for _, chType := range chTypes {
				chID := CreateNonce()
				az.Challenges = append(az.Challenges,
					&Challenge{
						ID:              chID,
						AccountID:       acc.ID,
						AuthorizationID: azID,
						Type:            chType,
						Value:           identifier.Value,
						Token:           az.Token,
						Status:          "pending",
						URL:             baseURL + "/challenge/" + azID + "/" + chID,
					})
			}
			o.AuthorizationIDs[i] = az.ID
			o.AuthorizationURLs[i] = baseURL + "/authz/" + azID
			authzMap[az.ID] = az
		}
		if o.NotBefore.IsZero() {
			o.NotBefore = now
		}
		if o.NotAfter.IsZero() {
			o.NotAfter = o.NotBefore.Add(time.Hour * 24)
		}
		if nor.NotBefore.IsZero() {
			o.NotBefore = o.NotBefore.Add(-time.Hour * 24)
		}
		o.FinalizeURL = baseURL + "/order/" + o.ID + "/finalize"
		if o.CertificateID != "" {
			o.CertificateURL = baseURL + "/certificate" + o.CertificateID
		}
		orderMap[o.ID] = o
		c.Response().Header().Add("Location", baseURL+"/order/"+o.ID)
		return c.JSON(http.StatusCreated, o)
	})


```

## /authz/:id

Authorizationをチェックします。
証明書の審査状況のチェックです。

```go
	e.POST("/authz/:id", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("authz err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		id := c.Param("id")
		acc, err := lookupJWKAndAccount(jws)
		if err != nil {
			log.Printf("authz err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// Check ID
		az, ok := authzMap[id]
		if !ok {
			log.Printf("authz not found id=%s", id)
			return c.JSON(http.StatusBadRequest, err)
		}
		if az.AccountID != acc.ID {
			log.Printf("authz not owner %s!=%s", az.AccountID, acc.ID)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("account id %s!=%s", az.AccountID, acc.ID))
		}
		c.Response().Header().Add("Location", baseURL+"/authz/"+az.ID)
		return c.JSON(http.StatusOK, az)
	})


```

## /challenge/:authzID/:chID

証明書発行の審査を要求します。


```go
	e.POST("/challenge/:authzID/:chID", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("challenge err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		authzID := c.Param("authzID")
		chID := c.Param("chID")
		acc, err := lookupJWKAndAccount(jws)
		if err != nil {
			log.Printf("challenge err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// Check ID
		az, ok := authzMap[authzID]
		if !ok {
			log.Printf("challenge not found id=%s", authzID)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("id not found %s", authzID))
		}
		if az.AccountID != acc.ID {
			log.Printf("challenge acc id mismatch az=%s acc=%s", az.AccountID, acc.ID)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("acount id  mismatch %s!=%s", az.AccountID, acc.ID))
		}
		// Challengeを探す
		var ch *Challenge
		for _, c := range az.Challenges {
			if c.ID == chID {
				ch = c
			}
		}
		if ch == nil {
			return c.JSON(http.StatusBadRequest, fmt.Errorf("challenge not found id=%s", chID))
		}
		switch ch.Type {
		case "http-01":
			// ここでHTTPのチェックをしてOKならStatusをvalidにすればよい
			if err := http01Validate(acc, ch); err != nil {
				log.Printf("challenge http01Validate err=%v", err)
				return c.JSON(http.StatusBadRequest, err)
			}
		case "tls-alpn-01":
			if err := tlsalpn01Validate(acc, ch); err != nil {
				return c.JSON(http.StatusBadRequest, err)
			}
		case "dns-01":
			if err := dns01Validate(acc, ch); err != nil {
				return c.JSON(http.StatusBadRequest, err)
			}
		case "device-attest-01":
			{
				payload, err := jws.Verify(acc.Key)
				if err != nil {
					log.Printf("challenge err=%v", err)
					return c.JSON(http.StatusBadRequest, err)
				}
				deviceAttest01Validate(acc, az, ch, payload)
			}
		default:
			return c.JSON(http.StatusBadRequest, fmt.Errorf("challenge not supported type=%s", ch.Type))
		}
		ch.Status = "valid"
		c.Response().Header().Add("Location", baseURL+"/challenge/"+az.ID+"/"+chID)
		c.Response().Header().Add("Link", fmt.Sprintf("<%s/authz/%s>;rel=up", baseURL, az.ID))
		return c.JSON(http.StatusOK, ch)
	})


```

ここで、チャレンジの方式がいろいろでてきます。
サーバーの証明証ではDNSのTXTレコードを書き換える方法、HTTPの応答を書き換える方法、TLSの応答を書き換える方法などがあります。
デバイスの証明書のためには、TPMやAppleハードを使ったのデバイス用チャレンジもあります。
HTTPのチャレンジのみ後で紹介します。

## /order/:id/finalize

チャレンジが成功した後、証明書の発行を行います。
そのリクエストの処理は


```go
	e.POST("/order/:id/finalize", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		id := c.Param("id")
		acc, err := lookupJWKAndAccount(jws)
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// Check ID
		o, ok := orderMap[id]
		if !ok {
			log.Printf("finalize not found id=%s", id)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("order not found id=%s", id))
		}
		if o.AccountID != acc.ID {
			log.Printf("finalize acc id mismatch o=%s acc=%s", o.AccountID, acc.ID)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("account id missmatch %s!=%s", o.AccountID, acc.ID))
		}
		payload, err := jws.Verify(acc.Key)
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		var fr FinalizeRequest
		if err := json.Unmarshal(payload, &fr); err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		csrBytes, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(fr.CSR, "="))
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		fr.csr, err = x509.ParseCertificateRequest(csrBytes)
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		if err := fr.csr.CheckSignature(); err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		cert, err := CreateCertificateFromCSRSub(csrBytes)
		certID := serial.String()
		serial.Add(serial, big.NewInt(1))
		if err != nil {
			log.Printf("finalize err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		pemCert := string(pem.EncodeToMemory(
			&pem.Block{
				Type:  "CERTIFICATE",
				Bytes: cert,
			},
		)) + "\n" +
			string(pem.EncodeToMemory(
				&pem.Block{
					Type:  "CERTIFICATE",
					Bytes: rootCACertificate,
				},
			))
		certMap[certID] = &Certificate{
			ID:          certID,
			OrderID:     o.ID,
			AccountID:   o.AccountID,
			Certificate: []byte(pemCert),
		}
		o.Status = "valid"
		o.CertificateID = certID
		o.CertificateURL = baseURL + "/certificate/" + o.CertificateID
		c.Response().Header().Add("Location", baseURL+"/order/"+id)
		return c.JSON(http.StatusOK, o)
	})


```

送信されたCSRから証明書を発行すればよいです。証明書の発行は、CA側の処理です。


## /certificate/:id

発行した証明書をダウンロードするための処理です。

```go
	e.POST("/certificate/:id", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("certificate err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		id := c.Param("id")
		acc, err := lookupJWKAndAccount(jws)
		if err != nil {
			log.Printf("err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// Check ID
		cert, ok := certMap[id]
		if !ok {
			log.Printf("certificate not found id=%s", id)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("cert not fond id=%s", id))
		}
		if cert.AccountID != acc.ID {
			log.Printf("certificate acc id mismatch o=%s acc=%s", cert.AccountID, acc.ID)
			return c.JSON(http.StatusBadRequest, err)
		}
		return c.Blob(http.StatusOK, "application/pem-certificate-chain", cert.Certificate)
	})

```

### /revoke-cert

証明書を失効します。
登録した人の失効リクエストか検証しています。

```go
	e.POST("/revoke-cert", func(c echo.Context) error {
		addHeader(c)
		jws, err := getJWS(c)
		if err != nil {
			log.Printf("revoke-cert err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		var jwk *jose.JSONWebKey
		var acc *Account
		if canExtractJWKFrom(jws) {
			jwk = extractJWK(jws)
			if jwk == nil {
				log.Println("revoke-cert no jwk")
				return c.JSON(http.StatusBadRequest, fmt.Errorf("missing jwk"))
			}
		} else {
			acc, err = lookupJWKAndAccount(jws)
			if err != nil {
				log.Printf("revoke-cert err=%v", err)
				return c.JSON(http.StatusBadRequest, err)
			}
			jwk = acc.Key
		}
		payload, err := jws.Verify(jwk)
		if err != nil {
			log.Printf("revoke-cert err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		var rvr RevokeReqest
		if err := json.Unmarshal(payload, &rvr); err != nil {
			log.Printf("revoke-cert err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		// nvrのチェック、
		certBytes, err := base64.RawURLEncoding.DecodeString(rvr.Certificate)
		if err != nil {
			log.Printf("revoke-cert err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		certToBeRevoked, err := x509.ParseCertificate(certBytes)
		if err != nil {
			log.Printf("revoke-cert err=%v", err)
			return c.JSON(http.StatusBadRequest, err)
		}
		serial := certToBeRevoked.SerialNumber.String()
		cert, ok := certMap[serial]
		if !ok {
			log.Printf("revoke-cert not found serial=%s", serial)
			return c.JSON(http.StatusBadRequest, fmt.Errorf("cert not found serial=%s", serial))
		}
		// ここで失効できるかチェックする
		// jwkが送信された場合とアカウントから取得した場合でチェック方法が変わる
		if acc != nil {
			// アカウントの場合は、登録しているアカウントが証明書の所有者
			if acc.ID != cert.AccountID {
				log.Printf("revoke-cert not owner serial=%s", serial)
				return c.JSON(http.StatusBadRequest, fmt.Errorf("you do not owwn this cert serial=%s", serial))
			}
		} else {
			// 失効する証明書の秘密鍵で検証する
			if _, err := jws.Verify(certToBeRevoked.PublicKey); err != nil {
				log.Printf("revoke-cert err=%v", err)
				return c.JSON(http.StatusBadRequest, err)
			}
		}
		revokedMap[serial] = cert
		delete(certMap, serial)
		return c.NoContent(http.StatusOK)
	})


```

## HTTPのチャンレンジ

証明書を要求しているサーバーの８０番ポートのHTTPサーバーに
GETリクエストを送信してチャレンジで指定した値がかえることで検証します。
とてもシンプルです。

```go
func http01Validate(acc *Account, ch *Challenge) error {
	u := &url.URL{Scheme: "http", Host: ch.Value, Path: fmt.Sprintf("/.well-known/acme-challenge/%s", ch.Token)}
	client := &http.Client{
		Timeout: 30 * time.Second,
		Transport: &http.Transport{
			Proxy: http.ProxyFromEnvironment,
			TLSClientConfig: &tls.Config{
				InsecureSkipVerify: true,
			},
		},
	}
	r, err := client.Get(u.String())
	if err != nil {
		return err
	}
	defer r.Body.Close()
	body, err := io.ReadAll(r.Body)
	if err != nil {
		return err
	}
	keyAuth := strings.TrimSpace(string(body))
	expected, err := KeyAuthorization(ch.Token, acc.Key)
	if err != nil {
		return err
	}
	if keyAuth != expected {
		return fmt.Errorf("http get %s != %s", keyAuth, expected)
	}
	return nil
}

```

## 余談

ここで紹介した内容は、TWSNMPシリーズにACMEサーバーを組み込むために調べたことです。
組み込んだ結果

https://note.com/twsnmp/n/n7763f95e64d4

に反映されています。

詳しいソースコードを知りたい方は、

https://github.com/twsnmp/twsnmpfc

か

https://github.com/twsnmp/twsnmpfk

の

`pki/acme.go`

を参照してください。