README
¶
go-cryptox
Extension of Golang crypto library
Table of Contents
👁️ Overview
go-cryptox provides additional functionality related to cryptography to facilitate the use of crypto in applications.
Please review the module documentation for details on how to properly the functions and classes contained in this module.
✅ Requirements
This module is supported for Go v1.21 and later.
📃 License
This module is distributed under the MIT License.
❓ Questions, Issues and Feature Requests
If you have questions about this project, find a bug or wish to submit a feature request, please submit an issue.
Documentation
¶
Overview ¶
Package cryptox contains functionality for dealing with X509 certificates and cryptography.
This package utilizes the go.innotegrity.dev/errorx package to return errors which can contain caller information that can be used with whatever logging platform you prefer to use.
Index ¶
- Constants
- func DecodePEMBlockFromFile(ctx context.Context, file string) (*pem.Block, error)
- func DecryptPEMBlock(ctx context.Context, b *pem.Block, password []byte) ([]byte, error)
- func DecryptString(ctx context.Context, ciphertext, key string) (string, errorx.Error)
- func EncryptPEMBlock(ctx context.Context, rand io.Reader, blockType string, data, password []byte, ...) (*pem.Block, error)
- func EncryptString(ctx context.Context, plaintext, key string) (string, errorx.Error)
- func GeneratePassword(passwordLength, minSpecialChar, minNum, minUpperCase int) string
- func IsEncryptedPEMBlock(b *pem.Block) bool
- func NewSelfSignedCertificateKeyPair(ctx context.Context, template *x509.Certificate, keyBits int) ([]byte, []byte, error)
- func ParsePEMCertificateBytes(ctx context.Context, contents []byte) ([]*x509.Certificate, error)
- func ParsePEMCertificateFile(ctx context.Context, file string) ([]*x509.Certificate, error)
- func ParsePEMPrivateKeyBytes(ctx context.Context, contents []byte, password []byte) (*rsa.PrivateKey, error)
- func ParsePEMPrivateKeyFile(ctx context.Context, file string, password []byte) (*rsa.PrivateKey, error)
- func ParsePublicKeyFromCertificate(ctx context.Context, cert *x509.Certificate) (*rsa.PublicKey, errorx.Error)
- func Sign(ctx context.Context, contents []byte, privateKey *rsa.PrivateKey) ([]byte, errorx.Error)
- func ValidateCertificate(ctx context.Context, cert *x509.Certificate, roots *CertificatePool, ...) errorx.Error
- func Verify(ctx context.Context, contents, signature []byte, publicKey *rsa.PublicKey) errorx.Error
- type CertificatePool
- type DecryptionError
- type EncryptionError
- type InvalidCertificateError
- type InvalidPublicKeyError
- type JWTAuthECDSAService
- type JWTAuthHMACService
- type JWTAuthRSAService
- type JWTAuthService
- type JWTError
- type LoadCertificateError
- type PEMCipher
- type PEMGeneralError
- type PGPError
- type PGPKeyPair
- type RSAPrivateKeyError
- type SignatureError
- type X509CertificateError
Constants ¶
const ( // Library error codes DecryptionErrorCode = 5001 EncryptionErrorCode = 5002 InvalidPublicKeyErrorCode = 5003 SignatureErrorCode = 5004 InvalidSignatureCode = 5005 LoadCertificateErrorCode = 5006 InvalidCertificateErrorCode = 5007 RSAPrivateKeyErrorCode = 5008 X509CertificateErrorCode = 5009 JWTErrorCode = 5010 PGPErrorCode = 5011 PEMGeneralErrorCode = 5012 )
Variables ¶
This section is empty.
Functions ¶
func DecodePEMBlockFromFile ¶
DecodePEMBlockFromFile loads a file into memory and decodes any PEM data from it.
The following errors are returned by this function: PEMGeneralError
func DecryptPEMBlock ¶
DecryptPEMBlock takes a PEM block encrypted according to RFC 1423 and the password used to encrypt it and returns a slice of decrypted DER encoded bytes.
It inspects the DEK-Info header to determine the algorithm used for decryption. If no DEK-Info header is present, an error is returned. If an incorrect password is detected an IncorrectPasswordError is returned. Because of deficiencies in the format, it's not always possible to detect an incorrect password. In these cases no error will be returned but the decrypted DER bytes will be random noise.
The following errors are returned by this function: DecryptionError
func DecryptString ¶
DecryptString decrypts the given block of ciphertext that was encrypted using the EncryptString() function.
If the string was encrypted using a random key generated by EncryptString(), leave the key empty.
The following errors are returned by this function: DecryptionError
func EncryptPEMBlock ¶
func EncryptPEMBlock(ctx context.Context, rand io.Reader, blockType string, data, password []byte, alg PEMCipher) ( *pem.Block, error)
EncryptPEMBlock returns a PEM block of the specified type holding the given DER encoded data encrypted with the specified algorithm and password according to RFC 1423.
The following errors are returned by this function: EncryptionError
func EncryptString ¶
EncryptString encrypts the given string using the given key.
If the key is empty, a random key is generated and stored with the ciphertext.
The following errors are returned by this function: EncryptionError
func GeneratePassword ¶
GeneratePassword generates a random password with the given characteristics.
func IsEncryptedPEMBlock ¶
IsEncryptedPEMBlock returns whether the PEM block is password encrypted according to RFC 1423.
func NewSelfSignedCertificateKeyPair ¶
func NewSelfSignedCertificateKeyPair(ctx context.Context, template *x509.Certificate, keyBits int) ( []byte, []byte, error)
NewSelfSignedCertificateKeyPair creates a new self-signed certificate using the given template and returns the public certificate and private key, respectively, on success.
The following errors are returned by this function: RSAPrivateKeyError, X509CertificateError
func ParsePEMCertificateBytes ¶
ParsePEMCertificateBytes takes a PEM-formatted byte string and converts it into one or more X509 certificates.
The following errors are returned by this function: X509CertificateError
func ParsePEMCertificateFile ¶
ParsePEMCertificateFile takes a PEM-formatted file and converts it into one or more X509 certificates.
The following errors are returned by this function: X509CertificateError
func ParsePEMPrivateKeyBytes ¶
func ParsePEMPrivateKeyBytes(ctx context.Context, contents []byte, password []byte) (*rsa.PrivateKey, error)
ParsePEMPrivateKeyBytes takes a PEM-formatted byte string and converts it into an RSA private key.
If the private key is encrypted, be sure to include a password or else this function will return an error. If no password is required, you can safely pass nil for the password.
The following errors are returned by this function: RSAPrivateKeyError
func ParsePEMPrivateKeyFile ¶
func ParsePEMPrivateKeyFile(ctx context.Context, file string, password []byte) (*rsa.PrivateKey, error)
ParsePEMPrivateKeyFile takes a PEM-formatted file and converts it into an RSA private key.
If the private key is encrypted, be sure to include a password or else this function will return an error. If no password is required, you can safely pass nil for the password.
The following errors are returned by this function: RSAPrivateKeyError
func ParsePublicKeyFromCertificate ¶
func ParsePublicKeyFromCertificate(ctx context.Context, cert *x509.Certificate) (*rsa.PublicKey, errorx.Error)
ParsePublicKeyFromCertificate parses the RSA public key portion from an X509 certificate.
The following errors are returned by this function: InvalidPublicKeyError
func Sign ¶
Sign takes the content and generates a signature using a private key certificate.
Use the DecodePEMData() function to convert a PEM-formatted certificate into a PEM block. If the private key is encrypted, use the DecryptPEMBlock() function to decrypt it first.
Use the Verify() function to verify the signature produced for the content.
The following errors are returned by this function: InvalidPublicKeyError
func ValidateCertificate ¶
func ValidateCertificate(ctx context.Context, cert *x509.Certificate, roots *CertificatePool, intermediates *CertificatePool, keyUsages []x509.ExtKeyUsage, cn string) errorx.Error
ValidateCertificate verifies the given certificate is completely trusted.
If the certificate was signed with a key that is not trusted by the default system certificate pool, be sure to specify a root CA certificate pool and, if necessary, an intermediate pool containing the certificates required to verify the chain.
If you wish to match against specific X509 extended key usages such as verifying the signing key has the Code Signing key usage, pass those fields in the keyUsages parameter.
If you wish to verify the common name (CN) field of the public key passed in, specify a non-empty string for the cn parameter. This match is case-sensitive.
The following errors are returned by this function: InvalidCertificateError
func Verify ¶
Verify validates that the given contents have not been altered by checking them against the signature and public key provided.
Use the Sign() function to create the signature used by this function to ensure the same hashing algorithm is applied.
The following errors are returned by this function: SignatureError
Types ¶
type CertificatePool ¶
CertificatePool stores X509 certificates.
func NewCertificatePool ¶
NewCertificatePool creates a new CertificatePool object.
If empty is true, return an empty certificate pool instead of a pool containing a copy of all of the system's trusted root certificates.
The following errors are returned by this function: LoadCertificateError
func (*CertificatePool) AddPEMCertificatesFromFile ¶
AddPEMCertificatesFromFile adds one or more PEM-formatted certificates from a file to the certificate pool.
The following errors are returned by this function: LoadCertificateError
type DecryptionError ¶
type DecryptionError struct {
// contains filtered or unexported fields
}
DecryptionErrror occurs when there's an error decrypting ciphertext.
func NewDecryptionError ¶
func NewDecryptionError(msg string, err error) *DecryptionError
NewDecryptionError creates a new DecryptionError error.
func NewDecryptionErrorWithContext ¶ added in v0.1.2
func NewDecryptionErrorWithContext(ctx context.Context, msg string, err error) *DecryptionError
NewDecryptionErrorWithContext creates a new DecryptionError error with context.
type EncryptionError ¶
type EncryptionError struct {
// contains filtered or unexported fields
}
EncryptionErrror occurs when there's an error encrypting plaintext.
func NewEncryptionError ¶
func NewEncryptionError(msg string, err error) *EncryptionError
NewEncryptionError creates a new EncryptionError error.
func NewEncryptionErrorWithContext ¶ added in v0.1.2
func NewEncryptionErrorWithContext(ctx context.Context, msg string, err error) *EncryptionError
NewEncryptionErrorWithContext creates a new EncryptionError error with context.
type InvalidCertificateError ¶
type InvalidCertificateError struct {
// contains filtered or unexported fields
}
InvalidCertificateError occurs when an improperly formatted X509 certificate is encountered.
func NewInvalidCertificateError ¶
func NewInvalidCertificateError(msg string, err error) *InvalidCertificateError
NewInvalidCertificateError creates a new InvalidCertificateError error.
func NewInvalidCertificateErrorWithContext ¶ added in v0.1.2
func NewInvalidCertificateErrorWithContext(ctx context.Context, msg string, err error) *InvalidCertificateError
NewInvalidCertificateErrorWithContext creates a new InvalidCertificateError error with context.
type InvalidPublicKeyError ¶
type InvalidPublicKeyError struct {
// contains filtered or unexported fields
}
InvalidPublicKeyError occurs when an improperly formatted RSA public key is encountered.
func NewInvalidPublicKeyError ¶
func NewInvalidPublicKeyError(msg string, err error) *InvalidPublicKeyError
NewInvalidPublicKeyError creates a new InvalidPublicKeyError error.
func NewInvalidPublicKeyErrorWithContext ¶ added in v0.1.2
func NewInvalidPublicKeyErrorWithContext(ctx context.Context, msg string, err error) *InvalidPublicKeyError
NewInvalidPublicKeyErrorWithContext creates a new InvalidPublicKeyError error with context.
type JWTAuthECDSAService ¶
type JWTAuthECDSAService struct {
// contains filtered or unexported fields
}
JWTAuthECDSAService creates and validates JWT tokens that are signed with a private ECDSA key and validated with a public ECDSA key.
func NewJWTAuthECDSAService ¶
func NewJWTAuthECDSAService(publicKey *ecdsa.PublicKey, privateKey *ecdsa.PrivateKey) *JWTAuthECDSAService
NewJWTAuthECDSAService creates an initializes a new service object.
func (*JWTAuthECDSAService) GenerateToken ¶
func (j *JWTAuthECDSAService) GenerateToken(ctx context.Context, claims jwt.Claims) (string, errorx.Error)
GenerateToken generates a new JWT token with the given claims.
The following errors are returned by this function: JWTError
func (*JWTAuthECDSAService) VerifyToken ¶
func (j *JWTAuthECDSAService) VerifyToken(ctx context.Context, encodedToken string) (*jwt.Token, errorx.Error)
VerifyToken parses and verifies the token string, returning the resulting JWT token for further validation.
The service must use the same secret that was used to generate the token being verified.
The following errors are returned by this function: JWTError
type JWTAuthHMACService ¶
type JWTAuthHMACService struct {
// contains filtered or unexported fields
}
JWTAuthHMACService creates and validates JWT tokens that are signed with an HMAC256-hashed secret.
func NewJWTAuthHMACService ¶
func NewJWTAuthHMACService(secret []byte) *JWTAuthHMACService
NewJWTAuthHMACService creates an initializes a new service object.
func (*JWTAuthHMACService) GenerateToken ¶
func (j *JWTAuthHMACService) GenerateToken(ctx context.Context, claims jwt.Claims) (string, errorx.Error)
GenerateToken generates a new JWT token with the given claims.
The following errors are returned by this function: JWTError
func (*JWTAuthHMACService) VerifyToken ¶
func (j *JWTAuthHMACService) VerifyToken(ctx context.Context, encodedToken string) (*jwt.Token, errorx.Error)
VerifyToken parses and verifies the token string, returning the resulting JWT token for further validation.
The service must use the same secret that was used to generate the token being verified.
The following errors are returned by this function: JWTError
type JWTAuthRSAService ¶
type JWTAuthRSAService struct {
// contains filtered or unexported fields
}
JWTAuthRSAService creates and validates JWT tokens that are signed with a private RSA key and validated with a public RSA key.
func NewJWTAuthRSAService ¶
func NewJWTAuthRSAService(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *JWTAuthRSAService
NewJWTAuthRSAService creates an initializes a new service object.
func (*JWTAuthRSAService) GenerateToken ¶
func (j *JWTAuthRSAService) GenerateToken(ctx context.Context, claims jwt.Claims) (string, errorx.Error)
GenerateToken generates a new JWT token with the given claims.
The following errors are returned by this function: JWTError
func (*JWTAuthRSAService) VerifyToken ¶
func (j *JWTAuthRSAService) VerifyToken(ctx context.Context, encodedToken string) (*jwt.Token, errorx.Error)
VerifyToken parses and verifies the token string, returning the resulting JWT token for further validation.
The service must use the same key pair that was used to generate the token being verified.
The following errors are returned by this function: JWTError
type JWTAuthService ¶
type JWTAuthService interface {
// GenerateToken should generate a new JWT token with the given claims and return the encoded JWT token.
GenerateToken(context.Context, jwt.Claims) (string, errorx.Error)
// VerifyToken should parse and verify the token string and return the resulting JWT token for further validation.
VerifyToken(context.Context, string) (*jwt.Token, errorx.Error)
}
JWTAuthService represents any object that is able to generate new JWT tokens and also validate them.
type JWTError ¶
type JWTError struct {
// contains filtered or unexported fields
}
JWTError occurs when there is an error with a Java Web Token.
func NewJWTError ¶
NewJWTError creates a new JWTError error.
func NewJWTErrorWithContext ¶ added in v0.1.2
NewJWTErrorWithContext creates a new JWTError error with context.
type LoadCertificateError ¶
type LoadCertificateError struct {
// contains filtered or unexported fields
}
LoadCertificateError occurs when there is an error loading one or more certificates.
func NewLoadCertificateError ¶
func NewLoadCertificateError(msg string, err error) *LoadCertificateError
NewLoadCertificateError creates a new LoadCertificateError error.
func NewLoadCertificateErrorWithContext ¶ added in v0.1.2
func NewLoadCertificateErrorWithContext(ctx context.Context, msg string, err error) *LoadCertificateError
NewLoadCertificateErrorWithContext creates a new LoadCertificateError error with context.
type PEMCipher ¶
type PEMCipher int
PEMCipher is just an alias for int.
const ( PEMCipherDES PEMCipher PEMCipher3DES PEMCipherAES128 PEMCipherAES192 PEMCipherAES256 )
Possible values for the EncryptPEMBlock encryption algorithm.
type PEMGeneralError ¶
type PEMGeneralError struct {
// contains filtered or unexported fields
}
PEMGeneralError occurs when there is a general error during PEM-related operations.
func NewPEMGeneralError ¶
func NewPEMGeneralError(msg string, err error) *PEMGeneralError
NewPEMGeneralError creates a new PEMGeneralError error.
func NewPEMGeneralErrorWithContext ¶ added in v0.1.2
func NewPEMGeneralErrorWithContext(ctx context.Context, msg string, err error) *PEMGeneralError
NewPEMGeneralErrorWithContext creates a new PEMGeneralError error with context.
type PGPError ¶
type PGPError struct {
// contains filtered or unexported fields
}
PGPError occurs when there is an error with a PGP operation.
func NewPGPError ¶
NewPGPError creates a new PGPError error.
func NewPGPErrorWithContext ¶ added in v0.1.2
NewPGPErrorWithContext creates a new PGPError error with context.
type PGPKeyPair ¶
type PGPKeyPair struct {
// contains filtered or unexported fields
}
PGPKeyPair represents a PGP key pair.
func NewPGPKeyPair ¶
NewPGPKeyPair returns a new PGP key pair.
Be sure to call ClearPrivateParams on the returned key to clear memory out when finished with the object.
The following errors are returned by this function: PGPError
func NewPGPKeyPairFromArmor ¶
func NewPGPKeyPairFromArmor(ctx context.Context, armoredKey, passphrase string) (*PGPKeyPair, error)
NewPGPKeyPairFromArmor returns a new PGP key pair from the given armored private key.
Be sure to call ClearPrivateParams on the returned key to clear memory out when finished with the object.
The following errors are returned by this function: PGPError
func (*PGPKeyPair) ClearPrivateParams ¶
func (kp *PGPKeyPair) ClearPrivateParams()
ClearPrivateParams clears out memory attached to the private key.
func (*PGPKeyPair) GetArmoredPrivateKey ¶
func (kp *PGPKeyPair) GetArmoredPrivateKey(ctx context.Context) (string, error)
GetArmoredPrivateKey returns the private key wrapped in PGP armor.
The following errors are returned by this function: PGPError
func (*PGPKeyPair) GetArmoredPublicKey ¶
func (kp *PGPKeyPair) GetArmoredPublicKey(ctx context.Context) (string, error)
GetArmoredPublicKey returns the public key wrapped in PGP armor.
The following errors are returned by this function: ErrGetPGPKeyFailure
type RSAPrivateKeyError ¶
type RSAPrivateKeyError struct {
// contains filtered or unexported fields
}
RSAPrivateKeyError occurs when there is an error with an RSA private key.
func NewRSAPrivateKeyError ¶
func NewRSAPrivateKeyError(msg string, err error) *RSAPrivateKeyError
NewRSAPrivateKeyError creates a new RSAPrivateKeyError error.
func NewRSAPrivateKeyErrorWithContext ¶ added in v0.1.2
func NewRSAPrivateKeyErrorWithContext(ctx context.Context, msg string, err error) *RSAPrivateKeyError
NewRSAPrivateKeyErrorWithContext creates a new RSAPrivateKeyError error with context.
type SignatureError ¶
type SignatureError struct {
// contains filtered or unexported fields
}
SignatureError occurs when there is an error signing content with an RSA private key.
func NewSignatureError ¶
func NewSignatureError(msg string, err error) *SignatureError
NewSignatureError creates a new SignatureError error.
func NewSignatureErrorWithContext ¶ added in v0.1.2
func NewSignatureErrorWithContext(ctx context.Context, msg string, err error) *SignatureError
NewSignatureErrorWithContext creates a new SignatureError error with context.
type X509CertificateError ¶
type X509CertificateError struct {
// contains filtered or unexported fields
}
X509CertificateError occurs when there is an error with an X509 certificate.
func NewX509CertificateError ¶
func NewX509CertificateError(msg string, err error) *X509CertificateError
NewX509CertificateError creates a new X509CertificateError error.
func NewX509CertificateErrorWithContext ¶ added in v0.1.2
func NewX509CertificateErrorWithContext(ctx context.Context, msg string, err error) *X509CertificateError
NewX509CertificateErrorWithContext creates a new X509CertificateError error with context.
Source Files