//
// 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.
//
=== Keystore

A https://en.wikipedia.org/wiki/Keystore[Java Keystore^] is a container for authorization certificates or public key
certificates, and is often used by Java-based applications for encryption, authentication, and serving over HTTPS.
Its entries are protected by a keystore password. A keystore entry is identified by an alias, and it consists of keys
and certificates that form a trust chain.

A keystore is currently required by the <<saml2sp4ui>> extension in order to sign and / or encrypt the
generated SAML 2.0 requests.

While a sample keystore is provided, it is *strongly* recommended to setup a production keystore; in the following, a
reference procedure for this is reported.

[WARNING]
The procedure below is not meant to cover all possible options and scenarios for generating a keystore, nor to provide
complete coverage of the `keytool` command.

[discrete]
===== Create new keystore

[source,bash]
----
keytool -genkey \
  -keyalg RSA \
  -keysize 2048 \
  -alias saml2sp4ui \
  -dname "CN=SAML2SP,OU=Apache Syncope, O=The ASF, L=Wilmington, ST=Delaware, C=US" \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp4ui.jks
----

This command will create a keystore file with name `saml2sp4ui.jks` in the execution directory, containing a new 2048-bit
RSA key pair, under the specified alias (`saml2sp4ui`); password values for `keypass` and `storepass` are also set.

[discrete]
===== Create new CSR

[source,bash]
----
keytool -certreq \
  -alias saml2sp4ui \
  -keyalg RSA \
  -file certreq.pem \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp4ui.jks
----

This command will create a CSR file with name `certreq.pem` in the execution directory, within the keystore generated
above. +
The generated CSR file can be sent to a Certificate Authority (CA) to request the issuance of a CA-signed certificate.

[discrete]
===== Have the CSR signed by a Certificate Authority (CA)

This step cannot be automated, and is definitely out of the scope of the this document.

Before proceeding, it is fundamental to have ready the root / intermediate CA certificate(s) and the signed certificate.

[discrete]
===== Import the certificates into the keystore

[source,bash]
----
keytool -import \
  -alias root \
  -file cacert.pem \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp4ui.jks
----

This command will import the root / intermediate CA certificate(s) from the `cacert.pem` file into the keystore
generated above.

[source,bash]
----
keytool -import \
  -alias saml2sp4ui \
  -file cert.pem \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp4ui.jks
----

This command will import the signed certificate from the `cert.pem` file into the keystore generated above.

[discrete]
===== Finalize

The keystore file `saml2sp4ui.jks` can now be placed in the <<properties-files-location,configuration directory>>; the
relevant part of the `core.properties` file should be:

....
saml2.sp4ui.keystore=file://${syncope.conf.dir}/saml2sp4ui.jks
saml2.sp4ui.keystore.type=jks
saml2.sp4ui.keystore.storepass=astorepass
saml2.sp4ui.keystore.keypass=akyepass
....
