//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
//
==== Set admin credentials

[WARNING]
The procedure below affects only the `Master` <<domains,domain>>; for other domains check <<domains-management,above>>.

The credentials are defined in the `security.properties` file; text encoding must be set to UTF-8:

* `adminUser` - administrator username (default `admin`)
* `adminPassword` - administrator password (default `password`)'s hashed value
* `adminPasswordAlgorithm` - algorithm to be used for hash evaluation (default `SSHA256`, also supported are
`SHA1`, `SHA256`, `SHA512`, `SMD5`, `SSHA1`, `SSHA512` and `BCRYPT`)

.Generate SHA1 password value on GNU / Linux
====
The `sha1sum` command-line tool of http://www.gnu.org/software/coreutils/[GNU Core Utilities^] can be used as follows:
[source,bash]
....
echo -n "new_password" | sha1sum
....

Please beware that any shell special character must be properly escaped for the command above to produce the expected
hashed value.
====

.Generate SSHA256 password value on GNU / Linux
====
....
$ python3 pySSHA/ssha.py -p password -enc sha256 -s 666ac543 \
 | sed 's/{.*}//' | xargs echo -n | base64 -d | xxd -p | tr -d $'\n' | xargs echo
....

Several tools involved here:

* https://github.com/peppelinux/pySSHA-slapd[pySSHA-slapd^]
* http://man7.org/linux/man-pages/man1/xargs.1.html[xargs^]
* http://man7.org/linux/man-pages/man1/echo.1.html[echo^]
* http://man7.org/linux/man-pages/man1/base64.1.html[base64^]
* https://linux.die.net/man/1/xxd[xxd^]
* http://man7.org/linux/man-pages/man1/tr.1.html[tr^]

The command above will:

. generate a `SHA256` hash for input value `password` with suffixed salt `666ac543` (4 bytes in hex format), via `ssha.py`
. remove the `{SSHA256}` prefix from the generated value and newline, via `sed` and `xargs`
. since the generated value is Base64-encoded while Syncope requires Hexadecimal format, perform the required conversion
via `base64`, `xxd` and `tr`
. append newline to ease copy / paste, via `xargs` and `echo`
====
