README
¶
securly
Secure Command and Response Made Simple
Summary
Documentation
¶
Overview ¶
Package securly provides functionality for securely encoding, decoding, encrypting and decrypting messages sent over the wire.
The main types in this package are: - Message: Represents a secure message with a payload and optional files. - Encryption: Contains instructions for how to encrypt the response.
The package relies on the https://github.com/lestrrat-go/jwx/v2 library for JSON Web Encryption (JWE) and JSON Web Key (JWK) handling.
Usage: ¶
To encode a message:
msg := securly.Message{
Payload: []byte("your payload"),
Files: map[string][]byte{
"file1.txt": []byte("file content"),
},
}
encoded, err := msg.Encode()
if err != nil {
log.Fatalf("failed to encode message: %v", err)
}
To encrypt a message:
encrypted, err := msg.Encrypt()
if err != nil {
log.Fatalf("failed to encrypt message: %v", err)
}
Index ¶
- Constants
- Variables
- type DecoderOption
- type DecryptOption
- type EncryptOption
- type Encryption
- type File
- type Message
- func (m Message) Encode() (data []byte, isEncrypted bool, err error)
- func (m Message) Encrypt(opts ...EncryptOption) ([]byte, error)
- func (z *Message) MarshalMsg(b []byte) (o []byte, err error)
- func (z *Message) Msgsize() (s int)
- func (m Message) Sign(opts ...SignOption) ([]byte, error)
- func (z *Message) UnmarshalMsg(bts []byte) (o []byte, err error)
- type SignOption
Constants ¶
const ( // EncryptedContentType is the content type for encrypted messages. EncryptedContentType = "application/securly+jwe" // SignedContentType is the content type for signed messages. SignedContentType = "application/securly+jws" )
Variables ¶
var ( ErrInvalidPayload = errors.New("invalid payload") ErrInvalidSHA = errors.New("invalid SHA") ErrInvalidSignAlg = errors.New("invalid signature algorithm") ErrInvalidEncryptionAlg = errors.New("invalid encryption algorithm") ErrInvalidSignature = errors.New("invalid signature") ErrUnsafeAlgorithm = errors.New("unsafe algorithm for use in the clear") )
Functions ¶
This section is empty.
Types ¶
type DecoderOption ¶
type DecoderOption interface {
// contains filtered or unexported methods
}
Option is a functional option for the Instructions constructor.
func NoVerification ¶
func NoVerification() DecoderOption
NoVerification does not verify the signature or credentials, but decodes the Message. Generally this is only useful if testing. DO NOT use this in production. This will intentionally conflict with the TrustedRootCA() option.
func RequirePolicies ¶
func RequirePolicies(policies ...string) DecoderOption
RequirePolicies specifies a list of policies that must be present in the signing chain intermediates.
func TrustRootCAs ¶
func TrustRootCAs(certs ...*x509.Certificate) DecoderOption
TrustRootCAs specifies a list of root CAs to trust when verifying the signature.
type DecryptOption ¶
type DecryptOption interface {
// contains filtered or unexported methods
}
EncodeOption is a functional option for the Instructions constructor.
func DecryptWith ¶
func DecryptWith(key jwk.Key) DecryptOption
func DecryptWithRaw ¶
func DecryptWithRaw(raw any) DecryptOption
type EncryptOption ¶
type EncryptOption interface {
// contains filtered or unexported methods
}
EncryptOption is a functional option for the Instructions constructor.
func EncryptWith ¶
func EncryptWith(alg jwa.KeyEncryptionAlgorithm, key jwk.Key) EncryptOption
EncryptWith sets the key encryption algorithm and key to use for encryption. If set, this will override the key and algorithm set in the Message. The value set in the message will be sent over the wire if this option is set.
func EncryptWithRaw ¶
func EncryptWithRaw(alg jwa.KeyEncryptionAlgorithm, raw any) EncryptOption
type Encryption ¶
type Encryption struct {
// Alg is the algorithm used to encrypt the payload.
Alg jwa.KeyEncryptionAlgorithm `msg:"alg"`
// Key is the key used to encrypt the payload.
Key jwk.Key `msg:"key"`
}
Encryption is the instructions for how to encrypt the response.
func (*Encryption) IsZero ¶
func (e *Encryption) IsZero() bool
func (Encryption) MarshalMsg ¶
func (z Encryption) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (Encryption) Msgsize ¶
func (z Encryption) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Encryption) UnmarshalMsg ¶
func (z *Encryption) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
type File ¶
type File struct {
// Data is the file content.
Data []byte `msg:"data"`
// Size is the file size. Note that the data slice may not be the full file
// content.
Size int64 `msg:"size,omitempty"`
// Mode is the file mode.
Mode fs.FileMode `msg:"mode,omitempty"`
// ModTime is the file modification time.
ModTime time.Time `msg:"modtime,omitempty"`
// Owner is the file owner.
Owner string `msg:"owner,omitempty"`
// UID is the file owner's User ID.
UID uint32 `msg:"uid,omitempty"`
// Group is the file group.
Group string `msg:"group,omitempty"`
// GID is the file group's Group ID.
GID uint32 `msg:"gid,omitempty"`
}
A File describes a single file.
func (*File) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Message ¶
type Message struct {
// Payload is the main payload of the message.
Payload []byte `msg:"payload"`
// Files is a map of filenames to file data. When sent over the wire, the
// file signatures are sent and validated to ensure the files are not
// tampered with.
Files map[string]File `msg:"files,omitempty"`
// Response is the instructions for how to encrypt the response, if that is
// required.
Response *Encryption `msg:"response,omitzero"`
}
Message is a secure message.
func Decode ¶
func Decode(buf []byte, opts ...DecoderOption) (*Message, error)
Decode converts a slice of bytes into a *Message if possible. Depending on the options provided, the function may also verify the signature of the message.
This function defaults secure, so it will verify the signature of the message. If you want to skip this verification, you can pass the NoVerification() option.
func Decrypt ¶
func Decrypt(buf []byte, opts ...DecryptOption) (*Message, error)
Decrypt converts a byte slice into a *Message and decodes it it using the provided key.
func (Message) Encode ¶
Encode converts a Message into a slice of bytes based on the data present in the Response field. If the Response field is nil, the message is encoded as an unsigned message. If the Response field is present, the message is encrypted using the provided instructions.
func (Message) Encrypt ¶
func (m Message) Encrypt(opts ...EncryptOption) ([]byte, error)
Encrypt encrypts the message using the provided options.
func (*Message) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (*Message) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
type SignOption ¶ added in v0.0.2
type SignOption interface {
// contains filtered or unexported methods
}
SignOption is a functional option for the Instructions constructor.
func NoSignature ¶
func NoSignature() SignOption
NoSignature indicates that the Message should not be signed. It cannot be used with any SignWith options or an error will be returned. This is to ensure that the caller is aware that the Message will not be signed.
func SignWith ¶
func SignWith(alg jwa.SignatureAlgorithm, public *x509.Certificate, private jwk.Key, intermediates ...*x509.Certificate, ) SignOption
SignWith sets the signing algorithm, public key, and private key used to sign the Message, as well as any intermediaries.
The following combinations are valid (the public/private keys must match): - ES256, private: *ecdsa.PrivateKey - ES384, private: *ecdsa.PrivateKey - ES512, private: *ecdsa.PrivateKey - RS256, private: *rsa.PrivateKey - RS384, private: *rsa.PrivateKey - RS512, private: *rsa.PrivateKey - PS256, private: *rsa.PrivateKey - PS384, private: *rsa.PrivateKey - PS512, private: *rsa.PrivateKey - EdDSA, private: ed25519.PrivateKey
Unfortunately, to make this work the private type needs to be an interface{}.
func SignWithRaw ¶
func SignWithRaw(alg jwa.SignatureAlgorithm, public *x509.Certificate, private any, intermediates ...*x509.Certificate, ) SignOption
Source Files