mackms

Documentation

Index

• Constants
• Variables
• type ECDH
  • func (e *ECDH) Curve() ecdh.Curve
  • func (e *ECDH) ECDH(pub *ecdh.PublicKey) ([]byte, error)
  • func (e *ECDH) PublicKey() *ecdh.PublicKey
• type MacKMS
  • func New(context.Context, apiv1.Options) (*MacKMS, error)
  • func (k *MacKMS) Close() error
  • func (k *MacKMS) CreateKey(req *apiv1.CreateKeyRequest) (*apiv1.CreateKeyResponse, error)
  • func (k *MacKMS) CreateSigner(req *apiv1.CreateSignerRequest) (crypto.Signer, error)
  • func (*MacKMS) DeleteCertificate(req *apiv1.DeleteCertificateRequest) error
  • func (*MacKMS) DeleteKey(req *apiv1.DeleteKeyRequest) error
  • func (k *MacKMS) GetPublicKey(req *apiv1.GetPublicKeyRequest) (crypto.PublicKey, error)
  • func (k *MacKMS) LoadCertificate(req *apiv1.LoadCertificateRequest) (*x509.Certificate, error)
  • func (k *MacKMS) LoadCertificateChain(req *apiv1.LoadCertificateChainRequest) ([]*x509.Certificate, error)
  • func (k *MacKMS) SearchKeys(req *apiv1.SearchKeysRequest) (*apiv1.SearchKeysResponse, error)
  • func (k *MacKMS) StoreCertificate(req *apiv1.StoreCertificateRequest) error
  • func (k *MacKMS) StoreCertificateChain(req *apiv1.StoreCertificateChainRequest) error
• type Signer
  • func (s *Signer) Public() crypto.PublicKey
  • func (s *Signer) Sign(_ io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Constants

const Scheme = string(apiv1.MacKMS)

Scheme is the scheme used in uris, the string "mackms".

Variables

var DefaultTag = "com.smallstep.crypto"

DefaultTag is the default tag attribute (kSecAttrApplicationTag) added to all the keys.

Types

type ECDH

type ECDH struct {
	*Signer
}

ECDH extends Signer with ECDH exchange method.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*ECDH) Curve

func (e *ECDH) Curve() ecdh.Curve

Curve returns the ecdh.Curve of the key. If the key is not an ECDSA key it will return nil.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*ECDH) ECDH

func (e *ECDH) ECDH(pub *ecdh.PublicKey) ([]byte, error)

ECDH performs an ECDH exchange and returns the shared secret. The private key and public key must use the same curve.

For NIST curves, this performs ECDH as specified in SEC 1, Version 2.0, Section 3.3.1, and returns the x-coordinate encoded according to SEC 1, Version 2.0, Section 2.3.5. The result is never the point at infinity.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*ECDH) PublicKey

func (e *ECDH) PublicKey() *ecdh.PublicKey

PublicKey returns the ecdh.PublicKey representation of the key. If the key is not an ECDSA or it cannot be converted it will return nil.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

type MacKMS

type MacKMS struct{}

MacKMS is a key manager that uses keys stored in macOS Keychain or in the Secure Enclave.

CreateKey methods can create keys with the following URIs:

• mackms:label=my-name
• mackms:label=my-name;tag=com.smallstep.crypto
• mackms;label=my-name;se=true;bio=true

GetPublicKey and CreateSigner accepts the above URIs as well as the following ones:

• my-name
• mackms:label=my-name;tag=com.smallstep.crypto;hash=ccb792f9d9a1262bfb814a339876f825bdba1261

The above URIs support the following attributes:

• "label" corresponds with Apple's kSecAttrLabel. It is always required and represents the key name. You will be able to see the keys in the Keychain, looking for the value.
• "tag" corresponds with kSecAttrApplicationTag. It defaults to com.smallstep.crypto.
• "se" is a boolean. If set to true, it will store the key in the Secure Enclave. This option requires the application to be code-signed with the appropriate entitlements.
• "bio" is a boolean value. If set to true, sign and verify operations require Touch ID or Face ID. This options requires the key to be in the Secure Enclave.
• "hash" corresponds with kSecAttrApplicationLabel. It is the SHA-1 of the DER representation of an RSA public key using the PKCS #1 format or the SHA-1 of the uncompressed ECDSA point according to SEC 1, Version 2.0, Section 2.3.4.

func New

func New(context.Context, apiv1.Options) (*MacKMS, error)

New returns a new SoftKMS.

func (*MacKMS) Close

func (k *MacKMS) Close() error

Close is a noop that just returns nil.

func (*MacKMS) CreateKey

func (k *MacKMS) CreateKey(req *apiv1.CreateKeyRequest) (*apiv1.CreateKeyResponse, error)

CreateKey generates a new key on the Keychain or Secure Enclave using the Apple Security framework.

func (*MacKMS) CreateSigner

func (k *MacKMS) CreateSigner(req *apiv1.CreateSignerRequest) (crypto.Signer, error)

CreateSigner returns a new crypto.Signer from the given URI in the request signing key.

func (*MacKMS) DeleteCertificate

func (*MacKMS) DeleteCertificate(req *apiv1.DeleteCertificateRequest) error

DeleteCertificate deletes the certificate referenced by the URI in the request name.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*MacKMS) DeleteKey

func (*MacKMS) DeleteKey(req *apiv1.DeleteKeyRequest) error

DeleteKey deletes the key referenced by the URI in the request name.

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*MacKMS) GetPublicKey

func (k *MacKMS) GetPublicKey(req *apiv1.GetPublicKeyRequest) (crypto.PublicKey, error)

GetPublicKey returns the public key from the given URI in the request name.

func (*MacKMS) LoadCertificate

func (k *MacKMS) LoadCertificate(req *apiv1.LoadCertificateRequest) (*x509.Certificate, error)

LoadCertificate returns an x509.Certificate by its label and/or serial number. By default Apple Keychain will use the certificate common name as the label.

Valid names (URIs) are:

• mackms:label=test@example.com
• mackms:serial=2c273934eda8454d2595a94497e2395a
• mackms:label=test@example.com;serial=2c273934eda8454d2595a94497e2395a

func (*MacKMS) LoadCertificateChain

func (k *MacKMS) LoadCertificateChain(req *apiv1.LoadCertificateChainRequest) ([]*x509.Certificate, error)

LoadCertificateChain returns the leaf certificate by label and/or serial number and its intermediate certificates. By default Apple Keychain will use the certificate common name as the label.

Valid names (URIs) are:

• mackms:label=test@example.com
• mackms:serial=2c273934eda8454d2595a94497e2395a
• mackms:label=test@example.com;serial=2c273934eda8454d2595a94497e2395a

func (*MacKMS) SearchKeys

func (k *MacKMS) SearchKeys(req *apiv1.SearchKeysRequest) (*apiv1.SearchKeysResponse, error)

SearchKeys searches for keys according to the query URI in the request. By default, all keys managed by the KMS using the default tag, and both Secure Enclave as well as non-Secure Enclave keys will be returned.

• "" will return all keys managed by the KMS (using the default tag)
• "mackms:" will return all keys managed by the KMS (using the default tag)
• "mackms:label=my-label" will return all keys using label "my-label" (and the default tag)
• "mackms:hash=the-hash" will return all keys having hash "hash" (and the default tag; generally one result)
• "mackms:tag=my-tag" will search for all keys with "my-tag"
• "mackms:se=true" will return all Secure Enclave keys managed by the KMS (using the default tag)
• "mackms:se=false" will return all non-Secure Enclave keys managed by the KMS (using the default tag)

Experimental

Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.

func (*MacKMS) StoreCertificate

func (k *MacKMS) StoreCertificate(req *apiv1.StoreCertificateRequest) error

StoreCertificate stores a certificate in the Apple Keychain. There is no need to provide a label in the URI as Apple will use the CommonName as the default label, but if one is provided, the certificate in the Keychain will be updated with the given label:

Valid names (URIs) are:

• "" will use the common name as the label
• "mackms:" will use the common name
• "mackms:label=my-label" will use "my-label"
• "mackms:my-label" will use the "my-label"

func (*MacKMS) StoreCertificateChain

func (k *MacKMS) StoreCertificateChain(req *apiv1.StoreCertificateChainRequest) error

StoreCertificateChain stores a certificate chain in the Apple Keychain. There is no need to provide a label in the URI as Apple will use the CommonName as the default label, but if one is provided, the leaf certificate in the Keychain will be updated with the given label:

Valid names (URIs) are:

• "" will use the common name as the label
• "mackms:" will use the common name
• "mackms:label=my-label" will use "my-label"
• "mackms:my-label" will use the "my-label"

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

Signer implements the crypto.Signer interface using macOS Keychain or the Secure Enclave.

func (*Signer) Public

func (s *Signer) Public() crypto.PublicKey

Public returns the public key corresponding to the private key.

func (*Signer) Sign

func (s *Signer) Sign(_ io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Sign signs digest with the private key. For an RSA key, the resulting signature will be either a PKCS #1 v1.5 or PSS signature (as indicated by opts). For an ECDSA key, it will be a DER-serialized, ASN.1 signature structure.