github.com/hashicorp/nomad/api@v0.0.0-20240306165712-3193ac204f65/keyring.go (about)

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  package api
     5  
     6  import (
     7  	"fmt"
     8  	"net/url"
     9  )
    10  
    11  // Keyring is used to access the Variables keyring.
    12  type Keyring struct {
    13  	client *Client
    14  }
    15  
    16  // Keyring returns a handle to the Keyring endpoint
    17  func (c *Client) Keyring() *Keyring {
    18  	return &Keyring{client: c}
    19  }
    20  
    21  // EncryptionAlgorithm chooses which algorithm is used for
    22  // encrypting / decrypting entries with this key
    23  type EncryptionAlgorithm string
    24  
    25  const (
    26  	EncryptionAlgorithmAES256GCM EncryptionAlgorithm = "aes256-gcm"
    27  )
    28  
    29  // RootKeyMeta is the metadata used to refer to a RootKey.
    30  type RootKeyMeta struct {
    31  	KeyID       string // UUID
    32  	Algorithm   EncryptionAlgorithm
    33  	CreateTime  int64
    34  	CreateIndex uint64
    35  	ModifyIndex uint64
    36  	State       RootKeyState
    37  }
    38  
    39  // RootKeyState enum describes the lifecycle of a root key.
    40  type RootKeyState string
    41  
    42  const (
    43  	RootKeyStateInactive   RootKeyState = "inactive"
    44  	RootKeyStateActive                  = "active"
    45  	RootKeyStateRekeying                = "rekeying"
    46  	RootKeyStateDeprecated              = "deprecated"
    47  )
    48  
    49  // List lists all the keyring metadata
    50  func (k *Keyring) List(q *QueryOptions) ([]*RootKeyMeta, *QueryMeta, error) {
    51  	var resp []*RootKeyMeta
    52  	qm, err := k.client.query("/v1/operator/keyring/keys", &resp, q)
    53  	if err != nil {
    54  		return nil, nil, err
    55  	}
    56  	return resp, qm, nil
    57  }
    58  
    59  // Delete deletes a specific inactive key from the keyring
    60  func (k *Keyring) Delete(opts *KeyringDeleteOptions, w *WriteOptions) (*WriteMeta, error) {
    61  	wm, err := k.client.delete(fmt.Sprintf("/v1/operator/keyring/key/%v",
    62  		url.PathEscape(opts.KeyID)), nil, nil, w)
    63  	return wm, err
    64  }
    65  
    66  // KeyringDeleteOptions are parameters for the Delete API
    67  type KeyringDeleteOptions struct {
    68  	KeyID string // UUID
    69  }
    70  
    71  // Rotate requests a key rotation
    72  func (k *Keyring) Rotate(opts *KeyringRotateOptions, w *WriteOptions) (*RootKeyMeta, *WriteMeta, error) {
    73  	qp := url.Values{}
    74  	if opts != nil {
    75  		if opts.Algorithm != "" {
    76  			qp.Set("algo", string(opts.Algorithm))
    77  		}
    78  		if opts.Full {
    79  			qp.Set("full", "true")
    80  		}
    81  	}
    82  	resp := &struct{ Key *RootKeyMeta }{}
    83  	wm, err := k.client.put("/v1/operator/keyring/rotate?"+qp.Encode(), nil, resp, w)
    84  	return resp.Key, wm, err
    85  }
    86  
    87  // KeyringRotateOptions are parameters for the Rotate API
    88  type KeyringRotateOptions struct {
    89  	Full      bool
    90  	Algorithm EncryptionAlgorithm
    91  }