crypto

Documentation

Index

• Constants
• Variables
• func Base64Decode(value []byte) ([]byte, error)
• func Base64Encode(value []byte) []byte
• func CompareHashAndPassphrase(hash []byte, passphrase []byte) (needUpdate bool, err error)
• func DecodeAuthMessage(c MACConfig, key, enc, additionalData []byte) ([]byte, error)
• func EncodeAuthMessage(c MACConfig, key, value, additionalData []byte) ([]byte, error)
• func EncryptWithAES256CBC(key, payload, iv []byte) (string, error)
• func EncryptWithAES256HMAC(encKey, macKey, payload, iv []byte) (string, error)
• func EncryptWithRSA(key string, payload []byte) (string, error)
• func GenerateFromPassphrase(passphrase []byte) ([]byte, error)
• func GenerateRSAKeyPair() (string, []byte, error)
• func GenerateRandomBytes(n int) []byte
• func GenerateRandomSixDigits() string
• func GenerateRandomString(n int) string
• func HashPassWithPBKDF2(password, salt []byte, iterations int) ([]byte, []byte)
• func NewJWT(secret []byte, claims jwt.Claims) (string, error)
• func ParseJWT(tokenString string, keyFunc jwt.Keyfunc, claims jwt.Claims) error
• func Timestamp() int64
• type MACConfig
• type StandardClaims
  • func (claims StandardClaims) Valid() error

Constants

const DefaultPBKDF2Iterations = 100000

DefaultPBKDF2Iterations is the number of iterations used to hash the passphrase on the client-side with the PBKDF2 algorithm.

const EdgePBKDF2Iterations = 10000

EdgePBKDF2Iterations is the number of iterations used to hash the passphrase on the client-side with the PBKDF2 algorithm when the browser is Edge. As Edge doesn't support PBKDF2 in its window.crypto, we have to rely on a slower JS alternative, and to reduce the number of PBKDF2 iterations to avoid freezing the browser.

const MaxPBKDF2Iterations = 1000000

MaxPBKDF2Iterations is the recommended maximal number of iterations for hashing with PBKDF2.

const MinPBKDF2Iterations = 5000

MinPBKDF2Iterations is the recommended minimum number of iterations for hashing with PBKDF2.

Variables

var (
	ErrInvalidHash                 = errors.New("Invalid hash format")
	ErrMismatchedHashAndPassphrase = errors.New("hash and password are different")
	ErrNoUpdateNeeded              = errors.New("hash already has correct parameters")
)

Errors

var SigningMethod = jwt.SigningMethodHS512

SigningMethod is the algorithm choosed for signing JWT. Currently, it is HMAC-SHA-512

Functions

func Base64Decode

func Base64Decode(value []byte) ([]byte, error)

Base64Decode decodes a value using base64.

func Base64Encode

func Base64Encode(value []byte) []byte

Base64Encode encodes a value using base64.

func CompareHashAndPassphrase

func CompareHashAndPassphrase(hash []byte, passphrase []byte) (needUpdate bool, err error)

CompareHashAndPassphrase compares a derived key with the possible cleartext equivalent. The parameters used in the provided derived key are used. The comparison performed by this function is constant-time.

It returns an error if the derived keys do not match. It also returns a needUpdate boolean indicating whether or not the passphrase hash has outdated parameters and should be recomputed.

func DecodeAuthMessage

func DecodeAuthMessage(c MACConfig, key, enc, additionalData []byte) ([]byte, error)

DecodeAuthMessage verifies a message authentified with message authentication code and returns the message value algon with the issued time of the message.

func EncodeAuthMessage

func EncodeAuthMessage(c MACConfig, key, value, additionalData []byte) ([]byte, error)

EncodeAuthMessage associates the given value with a message authentication code for integrity and authenticity.

If the value, when base64 encoded with a fixed size header is longer than the configured maximum length, it will panic.

Message format (name prefix is in MAC but removed from message):

<---------------- MAC input ---------------->
                         <---------- Message ---------->
| name | additional data |    time |  value  |     hmac |
| ---- |       ---       | 8 bytes |   ---   | 32 bytes |

func EncryptWithAES256CBC

func EncryptWithAES256CBC(key, payload, iv []byte) (string, error)

EncryptWithAES256CBC uses AES-256-CBC to encrypt the payload, and returns a bitwarden cipher string. See https://github.com/jcs/rubywarden/blob/master/API.md#example

func EncryptWithAES256HMAC

func EncryptWithAES256HMAC(encKey, macKey, payload, iv []byte) (string, error)

EncryptWithAES256HMAC uses AES-256-CBC with HMAC SHA-256 to encrypt the payload, and returns a bitwarden cipher string.

func EncryptWithRSA

func EncryptWithRSA(key string, payload []byte) (string, error)

EncryptWithRSA uses RSA-2048-OAEP-SHA1 to encrypt the payload, and returns a bitwarden cipher string.

func GenerateFromPassphrase

func GenerateFromPassphrase(passphrase []byte) ([]byte, error)

GenerateFromPassphrase returns the derived key of the passphrase using the parameters provided. The parameters are prepended to the derived key and separated by the "$" character (0x24). If the parameters provided are less than the minimum acceptable values, an error will be returned.

func GenerateRSAKeyPair

func GenerateRSAKeyPair() (string, []byte, error)

GenerateRSAKeyPair generates a key pair that can be used for RSA. The private key is exported as PKCS#8, and the public key is exported as PKIX, and then encoded in base64.

func GenerateRandomBytes

func GenerateRandomBytes(n int) []byte

GenerateRandomBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func GenerateRandomSixDigits

func GenerateRandomSixDigits() string

GenerateRandomSixDigits returns a random string made of 6 digits

func GenerateRandomString

func GenerateRandomString(n int) string

GenerateRandomString generates a secure random string of length N

func HashPassWithPBKDF2

func HashPassWithPBKDF2(password, salt []byte, iterations int) ([]byte, []byte)

HashPassWithPBKDF2 will hash a password with the PBKDF2 algorithm and same parameters as it's done in client side. It returns the hashed password encoded in base64, but also the master key.

func NewJWT

func NewJWT(secret []byte, claims jwt.Claims) (string, error)

NewJWT creates a JWT token with the given claims, and signs it with the secret

func ParseJWT

func ParseJWT(tokenString string, keyFunc jwt.Keyfunc, claims jwt.Claims) error

ParseJWT parses a string and checkes that is a valid JSON Web Token

func Timestamp

func Timestamp() int64

Timestamp returns the current timestamp, in seconds.

Types

type MACConfig

type MACConfig struct {
	Name   string
	MaxAge time.Duration
	MaxLen int
}

MACConfig contains all the options to encode or decode a message along with a proof of integrity and authenticity.

Key is the secret used for the HMAC key. It should contain at least 16 bytes and should be generated by a PRNG.

Name is an optional message name that won't be contained in the MACed messaged itself but will be MACed against.

type StandardClaims

type StandardClaims struct {
	Audience  string `json:"aud,omitempty"`
	ExpiresAt int64  `json:"exp,omitempty"`
	IssuedAt  int64  `json:"iat,omitempty"`
	Issuer    string `json:"iss,omitempty"`
	NotBefore int64  `json:"nbf,omitempty"`
	Subject   string `json:"sub,omitempty"`
}

StandardClaims are a structured version of the JWT Claims Set, as referenced at https://datatracker.ietf.org/doc/html/rfc7519#section-4. They do not follow the specification exactly, since they were based on an earlier draft of the specification and not updated. The main difference is that they only support integer-based date fields and singular audiences.

func (StandardClaims) Valid

func (claims StandardClaims) Valid() error

Valid validates time based claims "exp, iat, nbf". There is no accounting for clock skew. As well, if any of the above claims are not in the token, it will still be considered a valid claim.