ifcrypto

Documentation

Index

• Variables
• type Chipher
• type Cipherable
• type Digester
• type HashAlgorithm
  • func (alg HashAlgorithm) GetHasher() hash.Hash
  • func (alg HashAlgorithm) GetHasherWithKey(key []byte, parent hash.Hash) hash.Hash
• type Key
• type KeyPair
• type KeyType
• type KeyUsage
• type PEMWriter
• type PrivateKey
• type PublicKey
• type SignAlgorithm
• type Signer
• type Verifier

Variables

var KeySizes = map[KeyType][]int{
	KeyTypeRsa:           {2048, 3072, 4096},
	KeyTypeEccNistP:      {256, 384, 521},
	KeyTypeEccSecgP256k1: {256},
	KeyTypeSymmetric:     {},
}

KeySizes specifies which key sizes a `KeyType` may assume.

If omitted, empty array, it is possibly unlimited.

Types

type Chipher

type Chipher string

const (
	ChiperAES256 Chipher = "aes256"
)

type Cipherable

type Cipherable interface {
	// Encrypt will encrypt the _plaintext_ using the key.
	Encrypt(
		c ifctx.ServiceContext,
		plaintext []byte,
		key Key,
		cipher Chipher,
	) (encrypted []byte, err error)

	// Decrypt will decrypt the _encrypted_ using the key.
	Decrypt(
		c ifctx.ServiceContext,
		encrypted []byte,
		key Key,
		cipher Chipher,
	) (plaintext []byte, err error)
}

Cipherable is a encrypt / decrypt capable implementation.

NOTE: Some keys do implement `crypto.Decrypter`, thus is able to decrypt via the key directly.

type Digester

type Digester interface {
	// Digest will generate digest using the `hash.Hash`, optional _key_
	// on the _msg_ and return the digest.
	//
	// NOTE: Key is only needed when a hash algorithm needs a key, otherwise
	// set it to nil.
	//
	// The `HashAlgorithm` is interpreted in sequential order.
	//
	// .Example Multi Hash Digest
	// [source,go]
	// ----
	// hmacSha256Digester := NewDigester().Digest(key, msg, HashSha256, HashHMac)
	// ----
	Digest(key, msg []byte, h ...HashAlgorithm) ([]byte, error)
}

Digester is capable of producing a digest with or without a key.

type HashAlgorithm

type HashAlgorithm string

const (
	HashNone   HashAlgorithm = "none"
	HashSha256 HashAlgorithm = "sha256"
	HashSha512 HashAlgorithm = "sha512"
	HashHMac   HashAlgorithm = "hmac"
)

func (HashAlgorithm) GetHasher

func (alg HashAlgorithm) GetHasher() hash.Hash

GetHasher returns the hash algorithm for the type.

If _HashAlgorithmNone_ nil is returned.

.Requesting a SHA256 [source,go] ---- sha256 := HashSha256.GetHasher() ----

func (HashAlgorithm) GetHasherWithKey

func (alg HashAlgorithm) GetHasherWithKey(key []byte, parent hash.Hash) hash.Hash

GetHasher returns the hash algorithm for the type.

If _HashAlgorithmNone_ nil is returned.

Parent is used when the current hash algorithm relies on a another.

.Requesting a SHA256 HMAC [source,go] ---- hmacSha256 := HashHMac.GetHasher(key, HashSha256.GetHasher()) ----

type Key

type Key interface {
	// GetID returns a id of the key.
	//
	// This is always specific of the backing _KMS_ system. For example, in _AWS_ this is a _ARN_ to
	// a key in the _KMS_.
	GetID() string
	// GetKeyUsage gets the keys usage. Some keys may have multiple usages.
	GetKeyUsage() []KeyUsage
	// GetKeySize returns the number of bits of the key
	GetKeySize() int
	// GetKeyType returns this keys `KeyType`.
	GetKeyType() KeyType
	// GetSupportedChiphers returns all the chipers that the key be used with.
	GetSupportedChiphers() []Chipher
	// CanSign checks if the current _Key_ may participate in _alg_ `SignAlgorithm` to do sign operations with.
	CanSign(alg SignAlgorithm) bool
	// CanVerify checks if the current _Key_ may participate in _alg_ `SignAlgorithm` to do verify on
	CanVerify(alg SignAlgorithm) bool
	// GetKey gets the underlying key, if any.
	//
	// Some keys are remote and not possible to fetch. In such situations the function returns a remote id,
	// most often the same as GetID() returns.
	GetKey() interface{}
	// IsSymmetric returns `true` if this is a `KeyTypeSymmetric`
	//
	// This is a convenience function instead of `GetKeyType`.
	IsSymmetric() bool
	// IsPrivate returns `true` if this is a `KeyType` other than `KeyTypeSymmetric` and is a private key.
	//
	// If `KeyTypeSymmetric` it will return `true` since all symmetric keys are considered as private.
	IsPrivate() bool
	// IsRemoteKey returns `true` if the key is not present in current process memory.
	//
	// Typically hardware units or remote services will not reveal their private key. In such case, this
	// method returns `true`. If present in memory such as a `*rsa.PrivateKey` it returns `false`.
	IsRemoteKey() bool
}

Key represents a single key.

The key may or may not be present in memory, it may be within a hardware unit or in a service such as _AWS KMS_ and the `Key` instance is merely a info block.

type KeyPair

type KeyPair interface {
	// Key - holds the private portion of this key.
	PrivateKey
	// GetPublic returns the public portion of the key
	GetPublic() PublicKey
}

KeyPair contains a private and a public key.

NOTE: Some properties may differ from the main private key and the public key. For example a private key may be configured to only sign a message, whereas the public key may be used only for verification.

type KeyType

type KeyType string

KeyType is the type of key

const (
	KeyTypeRsa           KeyType = "rsa"
	KeyTypeEccNistP      KeyType = "ecc-nist-p"
	KeyTypeEccSecgP256k1 KeyType = "ecc-secg_p256K1"
	// KeyTypeSymmetric is a key to use for symmetric operations in contrast to all other
	// `KeyType` where those are asymmetric.
	KeyTypeSymmetric KeyType = "symmetric"
)

type KeyUsage

type KeyUsage string

KeyUsage is the usage of a key.

NOTE: Some keys may have multiple _KeyUsage_.

const (
	// KeyUsageSign allows this key to sign a message
	KeyUsageSign KeyUsage = "sign"
	// KeyUsageVerify allows the key to verify / authenticate a message
	KeyUsageVerify KeyUsage = "verify"
	// KeyUsageDecrypt allows the key to decrypt a message
	KeyUsageDecrypt KeyUsage = "decrypt"
	// KeyUsageEncrypt allows the key do encrypt a message
	KeyUsageEncrypt KeyUsage = "encrypt"
)

type PEMWriter

type PEMWriter interface {

	// PEMWrite will write the key onto _w_.
	//
	// If private key, and _public_ is `true`, it
	// will in addition write the public portion as well.
	PEMWrite(w io.Writer, public bool) error
}

PEMWriter allows for writing the key

type PrivateKey

type PrivateKey interface {
	crypto.PrivateKey
	Key
}

PrivateKey is a explicit private `Key`

type PublicKey

type PublicKey interface {
	crypto.PublicKey
	Key
}

PublicKey is a explicit public `Key`

type SignAlgorithm

type SignAlgorithm string

SignAlgorithm specifies which type of signing algorithm being used to sign or verify.

const (
	SignAlgorithmRsaPssSha256      SignAlgorithm = "rsa-pss-sha256"
	SignAlgorithmRsaPssSha384      SignAlgorithm = "rsa-pss-sha384"
	SignAlgorithmRsaPssSha512      SignAlgorithm = "rsa-pss-sha512"
	SignAlgorithmRsaPkcs1V15Sha256 SignAlgorithm = "rsa-pkcs1-v1.5-sha256"
	SignAlgorithmRsaPkcs1V15Sha384 SignAlgorithm = "rsa-pkcs1-v1.5-sha384"
	SignAlgorithmRsaPkcs1V15Sha512 SignAlgorithm = "rsa-pkcs1-v1.5-sha512"
	SignAlgorithmEcdSha256         SignAlgorithm = "ecd-sha256"
	SignAlgorithmEcdSha384         SignAlgorithm = "ecd-sha384"
	SignAlgorithmEcdSha512         SignAlgorithm = "ecd-sha512"
)

Enum values for SignAlgorithm

type Signer

type Signer interface {
	// Sign will sign the _msg_ using the provided _key_.
	Sign(
		c ifctx.ServiceContext,
		msg []byte,
		key Key,
		signAlgorithm SignAlgorithm,
		tags ...coremodel.Meta,
	) error
}

Signer is a entity that may sign a signature.

NOTE: Some keys do implement `crypto.Signer` interface directly on the key.

type Verifier

type Verifier interface {
	// Verify will verify the _msg_ using the provided _key_
	Verify(
		c ifctx.ServiceContext,
		msg []byte,
		key Key,
		signAlgorithm SignAlgorithm,
		tags ...coremodel.Meta,
	) error
}

Verifier is implemented by those who may verify a signature.