github.com/trustbloc/kms-go@v1.1.2/spi/kms/kms.go (about)

     1  /*
     2   Copyright SecureKey Technologies Inc. All Rights Reserved.
     3  
     4   SPDX-License-Identifier: Apache-2.0
     5  */
     6  
     7  // Package kms provides the KMS interface of the framework. This includes the provider interface necessary for building
     8  // KMS instances and the list of key types supported by the service.
     9  package kms
    10  
    11  import "github.com/trustbloc/kms-go/spi/secretlock"
    12  
    13  // KeyManager manages keys and their storage for the aries framework.
    14  type KeyManager interface {
    15  	// Create a new key/keyset/key handle for the type kt
    16  	// Some key types may require additional attributes described in `opts`
    17  	// Returns:
    18  	//  - keyID of the handle
    19  	//  - handle instance (to private key)
    20  	//  - error if failure
    21  	Create(kt KeyType, opts ...KeyOpts) (string, interface{}, error)
    22  	// Get key handle for the given keyID
    23  	// Returns:
    24  	//  - handle instance (to private key)
    25  	//  - error if failure
    26  	Get(keyID string) (interface{}, error)
    27  	// Rotate a key referenced by keyID and return a new handle of a keyset including old key and
    28  	// new key with type kt. It also returns the updated keyID as the first return value
    29  	// Some key types may require additional attributes described in `opts`
    30  	// Returns:
    31  	//  - new KeyID
    32  	//  - handle instance (to private key)
    33  	//  - error if failure
    34  	Rotate(kt KeyType, keyID string, opts ...KeyOpts) (string, interface{}, error)
    35  	// ExportPubKeyBytes will fetch a key referenced by id then gets its public key in raw bytes and returns it.
    36  	// The key must be an asymmetric key.
    37  	// Returns:
    38  	//  - marshalled public key []byte
    39  	//  - error if it fails to export the public key bytes
    40  	ExportPubKeyBytes(keyID string) ([]byte, KeyType, error)
    41  	// CreateAndExportPubKeyBytes will create a key of type kt and export its public key in raw bytes and returns it.
    42  	// The key must be an asymmetric key.
    43  	// Some key types may require additional attributes described in `opts`
    44  	// Returns:
    45  	//  - keyID of the new handle created.
    46  	//  - marshalled public key []byte
    47  	//  - error if it fails to export the public key bytes
    48  	CreateAndExportPubKeyBytes(kt KeyType, opts ...KeyOpts) (string, []byte, error)
    49  	// PubKeyBytesToHandle transforms pubKey raw bytes into a key handle of keyType. This function is only a utility to
    50  	// provide a public key handle for Tink/Crypto primitive execution, it does not persist the key handle.
    51  	// Some key types may require additional attributes described in `opts`
    52  	// Returns:
    53  	//  - handle instance to the public key of type keyType
    54  	//  - error if keyType is not supported, the key does not match keyType or unmarshal fails
    55  	PubKeyBytesToHandle(pubKey []byte, kt KeyType, opts ...KeyOpts) (interface{}, error)
    56  	// ImportPrivateKey will import privKey into the KMS storage for the given keyType then returns the new key id and
    57  	// the newly persisted Handle.
    58  	// 'privKey' possible types are: *ecdsa.PrivateKey and ed25519.PrivateKey
    59  	// 'kt' possible types are signing key types only (ECDSA keys or Ed25519)
    60  	// 'opts' allows setting the keysetID of the imported key using WithKeyID() option. If the ID is already used,
    61  	// then an error is returned.
    62  	// Returns:
    63  	//  - keyID of the handle
    64  	//  - handle instance (to private key)
    65  	//  - error if import failure (key empty, invalid, doesn't match keyType, unsupported keyType or storing key failed)
    66  	ImportPrivateKey(privKey interface{}, kt KeyType, opts ...PrivateKeyOpts) (string, interface{}, error)
    67  }
    68  
    69  // Store defines the storage capability required by a KeyManager Provider.
    70  type Store interface {
    71  	// Put stores the given key under the given keysetID.
    72  	Put(keysetID string, key []byte) error
    73  	// Get retrieves the key stored under the given keysetID. If no key is found, the returned error is expected
    74  	// to wrap ErrKeyNotFound. KMS implementations may check to see if the error wraps that error type for certain
    75  	// operations.
    76  	Get(keysetID string) (key []byte, err error)
    77  	// Delete deletes the key stored under the given keysetID. A KeyManager will assume that attempting to delete
    78  	// a non-existent key will not return an error.
    79  	Delete(keysetID string) error
    80  }
    81  
    82  // Provider for KeyManager builder/constructor.
    83  type Provider interface {
    84  	StorageProvider() Store
    85  	SecretLock() secretlock.Service
    86  }
    87  
    88  // Creator method to create new key management service.
    89  type Creator func(provider Provider) (KeyManager, error)
    90  
    91  const (
    92  	// AES128GCM key type value.
    93  	AES128GCM = "AES128GCM"
    94  	// AES256GCMNoPrefix key type value.
    95  	AES256GCMNoPrefix = "AES256GCMNoPrefix"
    96  	// AES256GCM key type value.
    97  	AES256GCM = "AES256GCM"
    98  	// ChaCha20Poly1305 key type value.
    99  	ChaCha20Poly1305 = "ChaCha20Poly1305"
   100  	// XChaCha20Poly1305 key type value.
   101  	XChaCha20Poly1305 = "XChaCha20Poly1305"
   102  	// ECDSAP256DER key type value.
   103  	ECDSAP256DER = "ECDSAP256DER"
   104  	// ECDSAP384DER key type value.
   105  	ECDSAP384DER = "ECDSAP384DER"
   106  	// ECDSAP521DER key type value.
   107  	ECDSAP521DER = "ECDSAP521DER"
   108  	// ECDSASecp256k1DER key type value.
   109  	ECDSASecp256k1DER = "ECDSASecp256k1DER"
   110  	// ECDSAP256IEEEP1363 key type value.
   111  	ECDSAP256IEEEP1363 = "ECDSAP256IEEEP1363"
   112  	// ECDSAP384IEEEP1363 key type value.
   113  	ECDSAP384IEEEP1363 = "ECDSAP384IEEEP1363"
   114  	// ECDSAP521IEEEP1363 key type value.
   115  	ECDSAP521IEEEP1363 = "ECDSAP521IEEEP1363"
   116  	// ECDSASecp256k1IEEEP1363 key type value.
   117  	ECDSASecp256k1IEEEP1363 = "ECDSASecp256k1IEEEP1363"
   118  	// ED25519 key type value.
   119  	ED25519 = "ED25519"
   120  	// RSARS256 key type value.
   121  	RSARS256 = "RSARS256"
   122  	// RSAPS256 key type value.
   123  	RSAPS256 = "RSAPS256"
   124  	// HMACSHA256Tag256 key type value.
   125  	HMACSHA256Tag256 = "HMACSHA256Tag256"
   126  	// NISTP256ECDHKW key type value.
   127  	NISTP256ECDHKW = "NISTP256ECDHKW"
   128  	// NISTP384ECDHKW key type value.
   129  	NISTP384ECDHKW = "NISTP384ECDHKW"
   130  	// NISTP521ECDHKW key type value.
   131  	NISTP521ECDHKW = "NISTP521ECDHKW"
   132  	// X25519ECDHKW key type value.
   133  	X25519ECDHKW = "X25519ECDHKW"
   134  	// BLS12381G2 BBS+ key type value.
   135  	BLS12381G2 = "BLS12381G2"
   136  	// CLCredDef key type value.
   137  	CLCredDef = "CLCredDef"
   138  	// CLMasterSecret key type value.
   139  	CLMasterSecret = "CLMasterSecret"
   140  )
   141  
   142  // KeyType represents a key type supported by the KMS.
   143  type KeyType string
   144  
   145  const (
   146  	// AES128GCMType key type value.
   147  	AES128GCMType = KeyType(AES128GCM)
   148  	// AES256GCMNoPrefixType key type value.
   149  	AES256GCMNoPrefixType = KeyType(AES256GCMNoPrefix)
   150  	// AES256GCMType key type value.
   151  	AES256GCMType = KeyType(AES256GCM)
   152  	// ChaCha20Poly1305Type key type value.
   153  	ChaCha20Poly1305Type = KeyType(ChaCha20Poly1305)
   154  	// XChaCha20Poly1305Type key type value.
   155  	XChaCha20Poly1305Type = KeyType(XChaCha20Poly1305)
   156  	// ECDSAP256TypeDER key type value.
   157  	ECDSAP256TypeDER = KeyType(ECDSAP256DER)
   158  	// ECDSASecp256k1TypeDER key type value.
   159  	ECDSASecp256k1TypeDER = KeyType(ECDSASecp256k1DER)
   160  	// ECDSAP384TypeDER key type value.
   161  	ECDSAP384TypeDER = KeyType(ECDSAP384DER)
   162  	// ECDSAP521TypeDER key type value.
   163  	ECDSAP521TypeDER = KeyType(ECDSAP521DER)
   164  	// ECDSAP256TypeIEEEP1363 key type value.
   165  	ECDSAP256TypeIEEEP1363 = KeyType(ECDSAP256IEEEP1363)
   166  	// ECDSAP384TypeIEEEP1363 key type value.
   167  	ECDSAP384TypeIEEEP1363 = KeyType(ECDSAP384IEEEP1363)
   168  	// ECDSAP521TypeIEEEP1363 key type value.
   169  	ECDSAP521TypeIEEEP1363 = KeyType(ECDSAP521IEEEP1363)
   170  	// ECDSASecp256k1TypeIEEEP1363 key type value.
   171  	ECDSASecp256k1TypeIEEEP1363 = KeyType(ECDSASecp256k1IEEEP1363)
   172  	// ED25519Type key type value.
   173  	ED25519Type = KeyType(ED25519)
   174  	// RSARS256Type key type value.
   175  	RSARS256Type = KeyType(RSARS256)
   176  	// RSAPS256Type key type value.
   177  	RSAPS256Type = KeyType(RSAPS256)
   178  	// HMACSHA256Tag256Type key type value.
   179  	HMACSHA256Tag256Type = KeyType(HMACSHA256Tag256)
   180  	// NISTP256ECDHKWType key type value.
   181  	NISTP256ECDHKWType = KeyType(NISTP256ECDHKW)
   182  	// NISTP384ECDHKWType key type value.
   183  	NISTP384ECDHKWType = KeyType(NISTP384ECDHKW)
   184  	// NISTP521ECDHKWType key type value.
   185  	NISTP521ECDHKWType = KeyType(NISTP521ECDHKW)
   186  	// X25519ECDHKWType key type value.
   187  	X25519ECDHKWType = KeyType(X25519ECDHKW)
   188  	// BLS12381G2Type BBS+ key type value.
   189  	BLS12381G2Type = KeyType(BLS12381G2)
   190  	// CLCredDefType type value.
   191  	CLCredDefType = KeyType(CLCredDef)
   192  	// CLMasterSecretType key type value.
   193  	CLMasterSecretType = KeyType(CLMasterSecret)
   194  )