README
¶
surl
Create signed URLs in Go.
This is a trimmed down and optimized version of leg100/surl.
What's changed:
- ! Remove support for base58 expiry.
- ! Remove support for path formatter, only support query formatter.
- ! All
Optionnow haveWithprefix. - ! Optimized query formatter logic, this results in incompatible link format between this fork and
original
leg100/surlimplementation. - Support for changing expiry and signature query parameter name.
This fork can be configured to sign/verify link in a compatible way with original leg100/surl library's default config
using WithCompatMode. However, it is only guaranteed to compatible with v2.0.0
or this commit
Installation
go get -u github.com/mawngo/surl
Usage
package main
import (
"fmt"
"log"
"time"
"github.com/mawngo/surl"
)
func main() {
signer := surl.New([]byte("secret_key"))
// Create a signed URL that expires in one hour.
signed, _ := signer.Sign("https://example.com/a/b/c?foo=bar", time.Now().Add(time.Hour))
fmt.Println(signed)
// Outputs something like:
// https://example.com/a/b/c?foo=bar&expiry=1753548646&signature=QgtNxB9MsXQagB6m6vDe2j2WbuOncCcJcI34ze4AJUQ
err := signer.Verify(signed)
if err != nil {
log.Fatal("verification failed: ", err.Error())
}
fmt.Println("verification succeeded")
}
Notes
- Any change in the order of the query parameters in a signed URL renders it invalid, unless
SkipQueryis specified.
Documentation
¶
Index ¶
- Constants
- Variables
- type CompatLevel
- type Option
- func WithBase32Expiry() Option
- func WithCompatMode(mode CompatLevel) Option
- func WithDisableHashPool() Option
- func WithExpiryParam(name string) Option
- func WithHexExpiry() Option
- func WithPrefixPath(prefix string) Option
- func WithSignatureParam(name string) Option
- func WithSkipQuery() Option
- func WithSkipScheme() Option
- type Signer
Constants ¶
const ( // VerifyCompatible can verify both leg100/surl (default configuration) and optimized url. VerifyCompatible = 1 // SignVerifyCompatible produce url that is similar to leg100/surl (default configuration). // Auto enable [VerifyCompatible] when set. SignVerifyCompatible = 2 )
Variables ¶
var ( // ErrInvalidSignature is returned when the signature is invalid. ErrInvalidSignature = errors.New("invalid signature") // ErrInvalidFormat is returned when the format of the signed URL is // invalid. ErrInvalidFormat = errors.New("invalid format") // ErrExpired is returned when a signed URL has expired. ErrExpired = errors.New("URL has expired") )
Functions ¶
This section is empty.
Types ¶
type CompatLevel ¶
type CompatLevel int
CompatLevel specify the compatibility mode for Signer. By default, we use incompatible mode for maximum performance. Url that signed by this Signer can't be verified by leg100/surl. Url that signed by leg100/surl Signer can't be verified by this optimized Signer.
type Option ¶
type Option func(*Signer)
Option permits customizing the construction of a Signer.
func WithBase32Expiry ¶
func WithBase32Expiry() Option
WithBase32Expiry instructs Signer to use base32 to encode the expiry.
func WithCompatMode ¶
func WithCompatMode(mode CompatLevel) Option
WithCompatMode configure compatibility behavior between Signer and leg100/surl.
func WithDisableHashPool ¶ added in v1.2.0
func WithDisableHashPool() Option
WithDisableHashPool disable the hash pool used for generating signature. Using pool greatly improving performance in high concurrency scenario.
Deprecated. Pooling hash is now mandatory, this option has no effect and will be removed in the future.
func WithExpiryParam ¶
WithExpiryParam configure the query parameter name of expiry. This option will be ignored when WithCompatMode set to SignVerifyCompatible.
func WithHexExpiry ¶
func WithHexExpiry() Option
WithHexExpiry instructs Signer to use hex to encode the expiry.
func WithPrefixPath ¶
WithPrefixPath 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 computation.
func WithSignatureParam ¶
WithSignatureParam configure the query parameter name of signature. This option will be ignored when WithCompatMode set to SignVerifyCompatible.
func WithSkipQuery ¶
func WithSkipQuery() Option
WithSkipQuery instructs Signer to skip the query string when computing 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 WithSkipScheme ¶
func WithSkipScheme() Option
WithSkipScheme instructs Signer to skip the scheme when computing the signature. This is useful, say, if you generate signed URLs in production, where you use https, but you want to use these URLs in development too, where you use http.
type Signer ¶
type Signer struct {
// 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 truncated. Options alter the default format and behavior of signed URLs.
func (*Signer) SignInto ¶
SignInto add signature into the url with the given lifespan.
Any modification to the url after signed will make it invalid, except for:
- RawQuery when WithSkipQuery is enabled (removing signature and expiry still invalidates the url).
- Scheme when WithSkipScheme is enabled.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
default
command
|
|
|
prefix
command
|
|
|
skip_query
command
|
|
|
skip_scheme
command
|