The highest tagged major version is
README
¶
surl
Create signed URLs using go.
Installation
go get github.com/leg100/surl@latest
Usage
package main
import (
"fmt"
"time"
"github.com/leg100/surl"
)
func main() {
signer := surl.New([]byte("secret_sesame"))
// Create a signed URL that expires in one hour.
signed, _ := signer.Sign("https://example.com/a/b/c?foo=bar", time.Hour)
fmt.Println("signed url:", signed)
// Outputs something like:
// https://example.com/signed/pTn2am3eh8Ndz7ZTb6ya2gOMA5XtnFRd-1M__TNQr9o.1664441797/a/b/c?foo=bar
err := signer.Verify(signed)
if err != nil {
fmt.Println("verification failed:", err.Error())
}
fmt.Println("verification succeeded")
}
Notes
- Only the path and query are signed; the scheme and hostname are skipped when producing the signature. The query too can be skipped with the
SkipQueryoption. - Any change in the order of the query parameters in a signed URL renders it invalid, unless
SkipQueryis specified.
TODO:
- base58 encode expiry
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidSignature is returned when the provided token's // signature is not valid. ErrInvalidSignature = errors.New("invalid signature") // ErrInvalidSignedURL is returned when the signed URL's format is // invalid. ErrInvalidSignedURL = errors.New("invalid signed URL") // ErrExpired is returned by when the signed URL's expiry has been // exceeded. ErrExpired = errors.New("URL has expired") // Default formatter is the query formatter. DefaultFormatter = WithQueryFormatter() )
Functions ¶
This section is empty.
Types ¶
type Formatter ¶
type Formatter interface {
// AddExpiry adds an expiry to a URL
AddExpiry(*url.URL, time.Time)
// AddSignature adds a signature to a URL
AddSignature(*url.URL, []byte)
// ExtractSignature extracts a signature from a URL, returning the modified
// URL and the signature.
ExtractSignature(*url.URL) (*url.URL, []byte, error)
// ExtractExpiry extracts an expiry from a URL, returning the modified URL
// and the signature.
ExtractExpiry(*url.URL) (*url.URL, time.Time, error)
}
Formatter adds/extracts the signature and expiry to/from a URL according to a specific format
type Option ¶
type Option func(*Signer)
Option permits customising the construction of a Signer
func PrefixPath ¶
PrefixPath prefixes the signed URL's path with a string. This can make it easier for a server to differentiate between signed and non-signed URLs. Note: the prefix is not part of the signature calculation.
func SkipQuery ¶
func SkipQuery() Option
SkipQuery instructs Signer to skip the query string when calculating the signature. This is useful, say, if you have pagination query parameters but you want to use the same signed URL regardless of their value.
func WithPathFormatter ¶
func WithPathFormatter() Option
WithPathFormatter instructs Signer to store the signature and expiry in the path of a signed URL.
func WithQueryFormatter ¶
func WithQueryFormatter() Option
WithQueryFormatter instructs Signer to use query parameters to store the signature and expiry in a signed URL.
type PathFormatter ¶
type PathFormatter struct {
// contains filtered or unexported fields
}
PathFormatter includes the signature and expiry in a message according to the format: <sig>.<exp>/<data>. Suitable for URL paths as an alternative to using query parameters.
func (*PathFormatter) AddExpiry ¶
func (f *PathFormatter) AddExpiry(unsigned *url.URL, expiry time.Time)
AddExpiry adds expiry as a path component e.g. /foo/bar -> 390830893/foo/bar
func (*PathFormatter) AddSignature ¶
func (f *PathFormatter) AddSignature(payload *url.URL, sig []byte)
AddSignature adds signature as a path component alongside the expiry e.g. abZ3G/foo/bar -> /KKLJjd3090fklaJKLJK.abZ3G/foo/bar
func (*PathFormatter) ExtractExpiry ¶
ExtractExpiry decodes and splits the expiry and data from the payload.
func (*PathFormatter) ExtractSignature ¶
ExtractSignature decodes and splits the signature and payload from the signed message.
type QueryFormatter ¶
type QueryFormatter struct {
// contains filtered or unexported fields
}
QueryFormatter includes the signature and expiry as URL query parameters according to the format: /path?expiry=<exp>&signature=<sig>.
func (*QueryFormatter) AddExpiry ¶
func (f *QueryFormatter) AddExpiry(unsigned *url.URL, exp time.Time)
AddExpiry adds expiry as a query parameter e.g. /foo/bar -> /foo/bar?expiry=<exp>
func (*QueryFormatter) AddSignature ¶
func (f *QueryFormatter) AddSignature(payload *url.URL, sig []byte)
AddSignature adds signature as a query parameter alongside the expiry e.g. /foo/bar?expiry=<exp> -> /foo/bar?expiry=<exp>&signature=<sig>
func (*QueryFormatter) ExtractExpiry ¶
ExtractExpiry decodes and splits the expiry and data from the payload.
func (*QueryFormatter) ExtractSignature ¶
ExtractSignature decodes and splits the signature and payload from the signed message.
type Signer ¶
type Signer struct {
Formatter
// contains filtered or unexported fields
}
Signer is capable of signing and verifying signed URLs with an expiry.
func New ¶
New constructs a new signer, performing the one-off task of generating a secure hash from the key. The key must be between 0 and 64 bytes long; anything longer is stripped off.
Source Files
Directories