//
// 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 <<saml-2-0-service-provider>> 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 saml2sp \
  -dname "CN=SAML2SP,OU=Apache Syncope, O=The ASF, L=Wilmington, ST=Delaware, C=US" \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp.jks
----

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

[discrete]
===== Create new CSR

[source,bash]
----
keytool -certreq \
  -alias saml2sp \
  -keyalg RSA \
  -file certreq.pem \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp.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 saml2sp.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 saml2sp \
  -file cert.pem \
  -keypass akyepass \
  -storepass astorepass \
  -storetype JKS \
  -keystore saml2sp.jks
----

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

[discrete]
===== Finalize

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

....
keystore.name=saml2sp.jks
keystore.type=jks
keystore.storepass=astorepass
keystore.keypass=akyepass
sp.cert.alias=saml2sp
signature.algorithm=RSA_SHA1
....

[NOTE]
The `signature.algorithm` configuration parameter is the signature algorithm
that is used with the key extracted from the keystore referenced in the
parameters. +
The value for this parameter must match one of the
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/ext/saml2sp/common-lib/src/main/java/org/apache/syncope/common/lib/types/SignatureAlgorithm.java[available values^],
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/2_1_X/ext/saml2sp/common-lib/src/main/java/org/apache/syncope/common/lib/types/SignatureAlgorithm.java[available values^],
endif::[]
each of which correspond to a shorthand for an associated
algorithm as defined for use in the XML Signature specification. +
If  `signature.algorithm` is not specified, then either `RSA_SHA1`, `EC_SHA1` or
`DSA_SHA1` is used depending on the type of key that is stored in the keystore.
