keypairs/README.md

64 lines
2.1 KiB
Markdown
Raw Normal View History

2019-02-11 18:48:18 +00:00
# go-keypairs
2020-04-10 17:59:44 +00:00
JSON Web Key (JWK) support and type safety lightly placed over top of Go's `crypto/ecdsa` and `crypto/rsa`
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
Useful for JWT, JOSE, etc.
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
```go
key, err := keypairs.ParsePrivateKey(bytesForJWKOrPEMOrDER)
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
pub, err := keypairs.ParsePublicKey(bytesForJWKOrPEMOrDER)
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
jwk, err := keypairs.MarshalJWKPublicKey(pub, time.Now().Add(2 * time.Day))
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
kid, err := keypairs.ThumbprintPublicKey(pub)
```
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
# API Documentation
2019-02-11 18:48:18 +00:00
2020-05-10 19:11:26 +00:00
See <https://pkg.go.dev/git.rootprojects.org/root/keypairs>
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
# Philosophy
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
Go's standard library is great.
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
Go has _excellent_ crytography support and provides wonderful
primitives for dealing with them.
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
I prefer to stay as close to Go's `crypto` package as possible,
just adding a light touch for JWT support and type safety.
2019-02-11 18:48:18 +00:00
# Type Safety
2020-04-10 17:59:44 +00:00
`crypto.PublicKey` is a "marker interface", meaning that it is **not typesafe**!
2019-02-11 18:48:18 +00:00
2020-04-10 17:59:44 +00:00
`go-keypairs` defines `type keypairs.PrivateKey interface { Public() crypto.PublicKey }`,
2019-02-11 18:48:18 +00:00
which is implemented by `crypto/rsa` and `crypto/ecdsa`
(but not `crypto/dsa`, which we really don't care that much about).
2020-04-10 17:59:44 +00:00
Go1.15 will add `[PublicKey.Equal(crypto.PublicKey)](https://github.com/golang/go/issues/21704)`,
which will make it possible to remove the additional wrapper over `PublicKey`
and use an interface instead.
2019-02-11 18:48:18 +00:00
Since there are no common methods between `rsa.PublicKey` and `ecdsa.PublicKey`,
go-keypairs lightly wraps each to implement `Thumbprint() string` (part of the JOSE/JWK spec).
2020-04-10 17:59:44 +00:00
## JSON Web Key (JWK) as a "codec"
2019-02-11 18:48:18 +00:00
Although there are many, many ways that JWKs could be interpreted
2020-04-10 17:59:44 +00:00
(possibly why they haven't made it into the standard library), `go-keypairs`
follows the basic pattern of `encoding/x509` to `Parse` and `Marshal`
2019-02-11 18:48:18 +00:00
only the most basic and most meaningful parts of a key.
I highly recommend that you use `Thumbprint()` for `KeyID` you also
get the benefit of not losing information when encoding and decoding
between the ASN.1, x509, PEM, and JWK formats.
2019-08-19 20:48:28 +00:00
# LICENSE
2020-04-10 17:59:44 +00:00
Copyright (c) 2020-present AJ ONeal
2019-08-19 20:48:28 +00:00
Copyright (c) 2018-2019 Big Squid, Inc.
This work is licensed under the terms of the MIT license.
For a copy, see <https://opensource.org/licenses/MIT>.