.. _pwgen:

Method: Password generator
--------------------------

Description
~~~~~~~~~~~

Generates different types of passwords.

URL Syntax
~~~~~~~~~~

/api/{version}/utils/pwgen

HTTP Method
~~~~~~~~~~~

GET

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| Parameter name |                               Description                                | Parameter type |  Type  | Mandatory |                 Comment                 |
+================+==========================================================================+================+========+===========+=========================================+
| X-Http-Token   | StoredSafe token                                                         | HTTP Header    | String | :sup:`1)` | Preferred method                        |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| token          | StoredSafe token                                                         | URL-parameter  | String | :sup:`1)` | Legacy method                           |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| type           | Type to generate; pronounceable, diceword, opie, secure, bytes or pin    | URL-parameter  | String |           |                                         |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| length         | Set a desired length                                                     | URL-parameter  | String |           | Valid for pronounceable, secure and pin |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| language       | Select language (en\_US or sv\_SE)                                       | URL-parameter  | String |           | Valid for diceword                      |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| delimiter      | Delimiter between dice words (dash '-', space ' ' or default ',.] \_=:') | URL-parameter  | String |           | Valid for diceword and opie             |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| words          | Number of words (diceword)                                               | URL-parameter  | String |           | Valid for diceword                      |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| min\_char      | Minimum number of characters in a word                                   | URL-parameter  | String |           | Valid for diceword                      |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| max\_char      | Maximum number of characters in a word                                   | URL-parameter  | String |           | Valid for diceword                      |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+
| policyid       | Try to match this password policy                                        | URL-parameter  | String |           |                                         |
+----------------+--------------------------------------------------------------------------+----------------+--------+-----------+-----------------------------------------+

.. note:: :sup:`1)` One of the methods is required.

Generators
~~~~~~~~~~

-  secure and pronounceable uses Theodore Ts’o classical pwgen
-  opie uses Thomas Habets fantastic opwgen
-  diceword uses Fredrik Erikssons eminent pwgen
-  bytes uses PHPs random_bytes function for cryptographically secure keys

Defaults
~~~~~~~~

No parameters will give type secure and length 40.

+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
|   Generator   |                      Type                      | Length  | Max length |                            Default Settings                            |
+===============+================================================+=========+============+========================================================================+
| pin           | Integers                                       | 4       | 100        |                                                                        |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
| bytes         | Hexadecimal (length in bytes)                  | 32      | 1024       |                                                                        |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
| pronounceable | alphanumeric                                   | 12      | 1024       |                                                                        |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
| secure        | alphanumeric and symbols                       | 40      | 1024       |                                                                        |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
| opie          | alpha                                          | 128 bit | 128 bit    | delimiter=space                                                        |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+
| diceword      | alpha, national charactes, numbers and symbols |         |            | language=en\_US, words=5, min\_char=2, max\_char=0, delimiter=,.- \_=: |
+---------------+------------------------------------------------+---------+------------+------------------------------------------------------------------------+

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+-------------------------------------------------+---------+
|      Attribute      |                   Description                   |  Type   |
+=====================+=================================================+=========+
| CALLINFO.errorcodes | Number of errors                                | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.general    | Information                                     | Array   |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                    | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.status     | SUCCESS or FAIL                                 | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.passphrase | Generated password                              | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.length     | Length of password                              | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.type       | Password generator used                         | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls | String  |
+---------------------+-------------------------------------------------+---------+
| DATA                | Supplied data in API-call                       | String  |
+---------------------+-------------------------------------------------+---------+
| HEADERS.(headers)   | HTTP Headers                                    | String  |
+---------------------+-------------------------------------------------+---------+
| PARAMS              | Route parameters (empty)                        | Array   |
+---------------------+-------------------------------------------------+---------+
| ERRORCODES          | Error code and text (Only present if errors)    | Object  |
+---------------------+-------------------------------------------------+---------+
| ERRORS              | Error code and text (Only present if errors)    | Array   |
+---------------------+-------------------------------------------------+---------+

Examples
~~~~~~~~

Generates the default type password (secure) of the default length (40 characters).

**Request**

::

        GET /api/1.0/utils/pwgen
        x-http-token: your_storedsafe_token

**Response**


::

        HTTP/2 200
        content-type: application/json; charset=UTF-8
        {
        "CALLINFO": {
                "errorcodes": 0,
                "errors": 0,
                "general": [],
                "handler": "UtilsHandler",
                "status": "SUCCESS",
                "passphrase": "Sz(6Q~si\"`WACS:b\\{[Y~A~Bs+dn\\uTrG5/eG}yf",
                "length": 40,
                "type": "secure"
                "token": "rotated_storedsafe_token"
        },
        "DATA": {
                "token": "your_storedsafe_token"
        },
        "HEADERS": {
                "Accept": "*/*",
                "Host": "safe.domain.cc",
                "User-Agent": "curl/7.64.1",
                "X-Http-Token": "your_storedsafe_token"
        },
                "PARAMS": []
        }