//
// 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.
//
=== Control JWT signature

As explained <<rest-authentication-and-authorization,above>>, the REST authentication process generates, in case of
success, a unique signed JWT (JSON Web Token). +
Such JWT values are signed by Apache Syncope according to the https://tools.ietf.org/html/rfc7515[JWS^]
(JSON Web Signature) specification.

[[jws-hmac]]
==== Hash-based Message Authentication Code

This is the default configuration, where Core and clients posses a shared secret, configured under `core.properties`
as the `jwsKey` property value.

.Default JWS configuration
====
[source,properties]
----
security.jwsAlgorithm=HS512 // <1>
security.jwsKey=ZW7pRixehFuNUtnY5Se47IemgMryTzazPPJ9CGX5LTCmsOJpOgHAQEuPQeV9A28f // <2>
----
<1> Valid values are `HS256`, `HS384` and `HS512`
<2> Any alphanumeric value satisfying the https://tools.ietf.org/html/rfc7518#section-3.2[length requirement^] can be
used
====


[[jws-rsa]]
==== RSA Public-Key Cryptography

This configuration requires to specify a key pair: the former key value, said _private_, must be kept secret for internal
Core usage while the latter key value, said _public_, is to be shared with clients.

The commands below will generate the required key pair via OpenSSL and format their values for usage with
`core.properties`:

[source,bash]
----
$ openssl genrsa -out private_key.pem 2048
$ openssl pkcs8 -topk8 -in private_key.pem -inform pem -out jws.privateKey -outform pem -nocrypt
$ openssl rsa -pubout -in private_key.pem -out jws.publicKey
$ echo `sed '1d;$d' jws.privateKey | awk '{printf "%s", $0}'`:`sed '1d;$d' jws.publicKey | awk '{printf "%s", $0}'`
----

.JWS configuration with RSA PKCS#1
====
[source,properties]
----
security.jwsAlgorithm=RS512 // <1>
security. :MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnV02gD0aCAL1o5uTLJDbXBmpJDBOBxIWfKENifFzVNvWU+0KuUz++vfzvDh+T2+epj1C7MGEqHMnKwAET84wCqca/mDe8Nv86OTLAUWbAEoKQsZwnmCwlrSc5s2P2GJQB3bLt44/+MLgHGKM0dcROXtoBI9AUOl8+zRC4XHhGaW1yHikg6JS3Qiq1Wdb3Q9Kvx3Y2NqngQAqnhvMmF7I9jIgDCWOnX/NGQqqR5HA/ZoX86lKORHFgg+183DiUETVCpARDm3pqv/7beTRxW1pwXhnkyQXMl1e1Kqm453eocAQUtXerrAGoBkOEVgxzwTJNNgXRBcq2Y4CVzNQtYlP/QIDAQAB // <2>
----
<1> Valid values are `RS256`, `RS384` and `RS512`
<2> Value is obtained by the commands above; the public key value is the string after the `:` sign, e.g.
```
QB3bLt44/+MLgHGKM0dcROXtoBI9AUOl8+zRC4XHhGaW1yHikg6JS3Qiq1Wdb3Q9Kvx3Y2NqngQAqnhvMmF7I9jIgDCWOnX/NGQqqR5HA/ZoX86lKORHFgg+183DiUETVCpARDm3pqv/7beTRxW1pwXhnkyQXMl1e1Kqm453eocAQUtXerrAGoBkOEVgxzwTJNNgXRBcq2Y4CVzNQtYlP/QIDAQAB
``` 
====

[TIP]
Longer RSA keys offer stronger protection against cracking. The JWS specification suggests at least 2048 bits.
Please consider that higher CPU usage is involved with longer keys.
