# salt.wheel.key

Wheel system wrapper for the Salt key system to be used in interactions with the Salt Master programmatically.

The key module for the wheel system is meant to provide an internal interface for other Salt systems to interact with the Salt Master. The following usage examples assume that a WheelClient is available:

    import salt.config
    import salt.wheel
    opts = salt.config.master_config('/etc/salt/master')
    wheel = salt.wheel.WheelClient(opts)

Note that importing and using the `WheelClient` must be performed on the same machine as the Salt Master and as the same user that runs the Salt Master, unless `external_auth` is configured and the user is authorized to execute wheel functions.

The function documentation starts with the `wheel` reference from the code sample above and use the `WheelClient` functions to show how they can be called from a Python interpreter.

The wheel key functions can also be called via a `salt` command at the CLI using the `saltutil execution module`.

salt.wheel.key.accept(match, include_rejected=False, include_denied=False)

  Accept keys based on a glob match. Returns a dictionary.

  match

    The glob match of keys to accept.

  include_rejected

    To include rejected keys in the match along with pending keys, set this to `True`. Defaults to `False`.

  include_denied

    To include denied keys in the match along with pending keys, set this to `True`. Defaults to `False`.

      >>> wheel.cmd('key.accept', ['minion1'])
      {'minions': ['minion1']}

salt.wheel.key.accept_dict(match, include_rejected=False, include_denied=False)

  Accept keys based on a dict of keys. Returns a dictionary.

  match

    The dictionary of keys to accept.

  include_rejected

    To include rejected keys in the match along with pending keys, set this to `True`. Defaults to `False`.

    Added in version 2016.3.4.

  include_denied

    To include denied keys in the match along with pending keys, set this to `True`. Defaults to `False`.

    Added in version 2016.3.4.

  Example to move a list of keys from the `minions_pre` (pending) directory to the `minions` (accepted) directory:

      >>> wheel.cmd('key.accept_dict',
      {
          'minions_pre': [
              'jerry',
              'stuart',
              'bob',
          ],
      })
      {'minions': ['jerry', 'stuart', 'bob']}

salt.wheel.key.delete(match)

  Delete keys based on a glob match. Returns a dictionary.

  match

    The glob match of keys to delete.

      >>> wheel.cmd_async({'fun': 'key.delete', 'match': 'minion1'})
      {'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

salt.wheel.key.delete_dict(match)

  Delete keys based on a dict of keys. Returns a dictionary.

  match

    The dictionary of keys to delete.

      >>> wheel.cmd_async({'fun': 'key.delete_dict',
      'match': {
          'minions': [
              'jerry',
              'stuart',
              'bob',
          ],
      }})
      {'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

salt.wheel.key.finger(match, hash_type=None)

  Return the matching key fingerprints. Returns a dictionary.

  match

    The key for with to retrieve the fingerprint.

  hash_type

    The hash algorithm used to calculate the fingerprint

      >>> wheel.cmd('key.finger', ['minion1'])
      {'minions': {'minion1': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

salt.wheel.key.finger_master(hash_type=None)

  Return the fingerprint of the master's public key

  hash_type

    The hash algorithm used to calculate the fingerprint

      >>> wheel.cmd('key.finger_master')
      {'local': {'master.pub': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

salt.wheel.key.gen(id_=None, keysize=2048)

  Generate a key pair. No keys are stored on the master. A key pair is returned as a dict containing pub and priv keys. Returns a dictionary containing the `pub` and `priv` keys with their generated values.

  id_

    Set a name to generate a key pair for use with salt. If not specified, a random name will be specified.

  keysize

    The size of the key pair to generate. The size must be `2048`, which is the default, or greater. If set to a value less than `2048`, the key size will be rounded up to `2048`.

      >>> wheel.cmd('key.gen')
      {'pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
      ...
      BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\niQIDAQAB\n
      -----END PUBLIC KEY-----',
      'priv': '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
      ...
      QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\n
      -----END RSA PRIVATE KEY-----'}

salt.wheel.key.gen_accept(id_, keysize=2048, force=False)

  Generate a key pair then accept the public key. This function returns the key pair in a dict, only the public key is preserved on the master. Returns a dictionary.

  id_

    The name of the minion for which to generate a key pair.

  keysize

    The size of the key pair to generate. The size must be `2048`, which is the default, or greater. If set to a value less than `2048`, the key size will be rounded up to `2048`.

  force

    If a public key has already been accepted for the given minion on the master, then the gen_accept function will return an empty dictionary and not create a new key. This is the default behavior. If `force` is set to `True`, then the minion's previously accepted key will be overwritten.

      >>> wheel.cmd('key.gen_accept', ['foo'])
      {'pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
      ...
      BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\niQIDAQAB\n
      -----END PUBLIC KEY-----',
      'priv': '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
      ...
      QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\n
      -----END RSA PRIVATE KEY-----'}

  We can now see that the `foo` minion's key has been accepted by the master:

      >>> wheel.cmd('key.list', ['accepted'])
      {'minions': ['foo', 'minion1', 'minion2', 'minion3']}

salt.wheel.key.gen_keys(keydir=None, keyname=None, keysize=None, user=None)

  Generate minion RSA public keypair

salt.wheel.key.gen_signature(priv, pub, signature_path, auto_create=False, keysize=None)

  Generate master public-key-signature

salt.wheel.key.key_str(match)

  Return information about the key. Returns a dictionary.

  match

    The key to return information about.

      >>> wheel.cmd('key.print', ['minion1'])
      {'minions': {'minion1': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B
      ...
      TWugEQpPt\niQIDAQAB\n-----END PUBLIC KEY-----'}}

salt.wheel.key.list_(match)

  List all the keys under a named status. Returns a dictionary.

  match

    The type of keys to list. The `pre`, `un`, and `unaccepted` options will list unaccepted/unsigned keys. `acc` or `accepted` will list accepted/signed keys. `rej` or `rejected` will list rejected keys. Finally, `all` will list all keys.

      >>> wheel.cmd('key.list', ['accepted'])
      {'minions': ['minion1', 'minion2', 'minion3']}

salt.wheel.key.list_all()

  List all the keys. Returns a dictionary containing lists of the minions in each salt-key category, including `minions`, `minions_rejected`, `minions_denied`, etc. Returns a dictionary.

      >>> wheel.cmd('key.list_all')
      {'local': ['master.pem', 'master.pub'], 'minions_rejected': [],
      'minions_denied': [], 'minions_pre': [],
      'minions': ['minion1', 'minion2', 'minion3']}

salt.wheel.key.master_key_str()

  Returns master's public key. Returns a dictionary

      >>> wheel.cmd('key.master_key_str')
      {'local': {'master.pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B
      ...
      TWugEQpPt\niQIDAQAB\n-----END PUBLIC KEY-----'}}

salt.wheel.key.name_match(match)

  List all the keys based on a glob match

salt.wheel.key.reject(match, include_accepted=False, include_denied=False)

  Reject keys based on a glob match. Returns a dictionary.

  match

    The glob match of keys to reject.

  include_accepted

    To include accepted keys in the match along with pending keys, set this to `True`. Defaults to `False`.

  include_denied

    To include denied keys in the match along with pending keys, set this to `True`. Defaults to `False`.

      >>> wheel.cmd_async({'fun': 'key.reject', 'match': 'minion1'})
      {'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

salt.wheel.key.reject_dict(match, include_accepted=False, include_denied=False)

  Reject keys based on a dict of keys. Returns a dictionary.

  match

    The dictionary of keys to reject.

  include_accepted

    To include accepted keys in the match along with pending keys, set this to `True`. Defaults to `False`.

    Added in version 2016.3.4.

  include_denied

    To include denied keys in the match along with pending keys, set this to `True`. Defaults to `False`.

    Added in version 2016.3.4.

      >>> wheel.cmd_async({'fun': 'key.reject_dict',
      'match': {
          'minions': [
              'jerry',
              'stuart',
              'bob',
          ],
      }})
      {'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}