====== Modules - Certificates [crt] ======

CRT module was designed to handle various certificate authority implementations via specific **drivers**. Currently, there is one driver implemented - the **CAW** driver that handles the communication with CAW certificate authority (bundled in the module).

===== Architecture =====

 Module consists of those basic parts:
  * **GUI** - Users can manage their certificates or request a new one via standard CzechIdM web GUI
  * **Registration authority** - When user requests for a certificate, the request is processed by appropriate driver. 
  * **Certificate store** - users' certificates are stored in CzechIdM for future download or e.g. provisioning (send to other managed system)
  * **Drivers** - Driver implements mainly the communication mechanism between CzechIdM and CA (e.g. CAW or Microsoft CA). Currently CzechIdM provides the driver for CAW, others can be implemented on demand. If the request from registration authority does not contain CSR, driver creates it.
  * **CAW** - Our CA implementation based on openssl.
  * **RESTful API** - Standard communication API. Use it e.g. when users request for a new certificate via some external registration authority software.

{{ :devel:documentation:ca_new_without_ad.png | CRT module architecture}}


===== Active operations with certificate =====

  * **Generate** - Generate a new certificate. The user must select a certification authority, a certificate type (Authentication, Signing, Encryption), and a password. The password will be required to open a downloaded storage with a private key and a user certificate. The password will be stored in the confidential storage in IdM. If the certificate generation is complete, password will be removed from the IdM.
  * **Generate by CSR** - Generate a certificate from an existing request (**Certificate Signing Request**). The user has a certificate request already generated in the CSR format. This request contains all the necessary information to generate. The user must only select authority and file with CSR request. In this case, it does not enter or store any password (the private part of the certificate already has the user with).
  * **Renew** -  Extending the validity of an existing certificate. Extensions can only be made on a valid certificate.
  * **Revocate** - Certificate invalidation. For example, if the private part of the certificate is compromised, you must revoke the certificate to prevent further abuse.
  * **Archivate** - Certificate is archived ("soft delete"). Archived certificates cannot be renewed or revoked. They are still controlled for expiration (see long running tasks and notifications below).
  * **Cancel request** - Certificate request can be canceled, when request is in concept state.
  * **Download certificate** - Public and private (if exists) certificate can be downloaded. Private certificate can be downloaded just by certificate owner.

===== Managing of certificates =====

All certificates that IdM manages are stored in the certificate store. All operations over certificates (validation, download, notifications) are only performed over the certificates stored directly in the IDM.

In the certificate store, you can get the certificate in the following ways:
     * It is generated by the appropriate **CA** (see below).
     * **Manually** uploaded by the user via GUI. You can also upload certificates that are not managed by the certification authority within this module. In this case, only expiration is validated. Otherwise, the certificate is validated directly against the certification authority (for example, checking the CSR revocation).
     * **Synchronized** within identity synchronization (not implemented at this time).
     * Uploaded via **REST api** (the same as uploaded by user via GUI).

<note tip>We supports upload in **PEM** and **DER** format. Downloaded (public) certificates are always in the **PEM** format.</note>


{{ :devel:documentation:crt_certificates.png |}}
===== Driver =====
Driver provides communication with an external CA. The certification authority can have any interface (**REST** api, **Web service**, **Bash** command, ...) and very different behavior (**synchronous** / **asynchronous**). The driver is used to implement communication with a specific CA. The driver thus allows communication with any authority to go through the standardized interface provided by the driver and with which CRT module can works.

The CRT module contains a **CAW-driver**. This is a driver implementation that communicates with our internal certification authority (CAW). This authority is based on **openssl** and the **CAW-driver** uses for communication **Bash** commands.

===== Authority configuration =====
Each certification authority needs specific configuration parameters.

These may include:
    * User and password for authentication.
    * Location of CA (url, path on server).
    * Global parameters (type of certificate, organization for which we want to generate certificates, ...).
    * ...

Obviously, for each certification authority, the driver must have a specific set of parameters. For easier development and configuration of the CA, the configuration is implemented as a JAVA class that contains fields corresponding to the given parameters. This configuration class then generates a configuration definition (EAV) that is represented in the GUI by a dynamic form. With this approach, configuration items can be clearly displayed, entered and validated. 

Bellow is show authority detail uses the CAW-driver:

{{ :devel:documentation:crt_config_authority.png |}}

===== Certificate requests =====
Each active operation performed on a certification authority (generation, renew, revocation) is performed by a request (crt-request).
The request contains all the necessary information to perform the operation. 
For example, for generate certificate it is: Certificate type, certification authority, user defined password, request status.

The request is necessary in the case of asynchronous processing, here the situation where the external CA does not execute the operation immediately, but it is necessary check CA for the result again. In this case, the request is in the **In progress** state.
The same situation occurs when we require a workflow approval before the request is executed. Even in this case, the request is the holder of the current status, in this case **In approval**.

<note tip>If some error occures during processing of the request, then this error message will be persisted in this request and state will be in the state **Exception**.</note>


{{ :devel:documentation:crt_requests.png |}}


===== Approving of certificate requests =====
If it is required approving all active operations before implementation, it is possible to enable approval in the CA configuration according to the selected workflow process. In this configuration, it is also possible to choose the roles used in the approval process. By default, all users with these roles will be able to approve/disapprove that request.

{{ :devel:documentation:crt_wf_config.png |}}

The CRT module contains "**crt-approve-request**" process that is used as the default setting for each new CA.

<note important>The "**crt-approve-request**" process only requires approval for new certificate generating requirements. For "Renew" and "Revocation" operations, approval is not required and the process ends immediately.</note>

{{ :devel:documentation:crt_approve_wf.png?1000 |}}

===== Notification configuration =====

Configured notification topics (email by default):
  * **certificateExpiredOwner** - When certificate is expired, notification is sent to certificate owner. 
    * Can be disabled by property ''idm.sec.crt.processor.certificate-expired-notification-owner-processor.enabled=false''.
  * **certificateExpiredAdmin** - When certificate is expired, notification is sent to certificate admin. 
    * Certificate admins are identities with role configured by property ''idm.sec.crt.processor.certificate-expired-notification-admin-processor.adminRole''. When no identity is found, then notification isn't sent. 
    * Can be disabled by property ''idm.sec.crt.processor.certificate-expired-notification-admin-processor.enabled=false''.
  * **certificateExpirationWarningOwner** - [[#certificateexpirationwarningownertaskexecutor|CertificateExpirationWarningOwnerTaskExecutor]]
  * **certificateExpirationWarningAdmin** - [[#certificateexpirationwarningadmintaskexecutor|CertificateExpirationWarningAdminTaskExecutor]]
  * **certificateRevokedOwner** - When certificate is revoked, notification is sent to certificate owner.
    * Can be disabled by property ''idm.sec.crt.processor.certificate-revoked-notification-owner-processor.enabled=false''.
  * **certificateRevokedAdmin** - When certificate is revoked, notification is sent to certificate admin. 
    * Certificate admins are identities with role configured by property ''idm.sec.crt.processor.certificate-revoked-notification-admin-processor.adminRole''. When no identity is found, then notification isn't sent. 
    * Can be disabled by property ''idm.sec.crt.processor.certificate-revoked-notification-admin-processor.enabled=false''.
  * **certificateCreatedOwner** - When certificate is created, notification is sent to certificate owner.
    * Can be disabled by property ''idm.sec.crt.processor.certificate-created-notification-owner-processor.enabled=false''.
  * **certificateCreatedAdmin** - When certificate is created, notification is sent to certificate admin. 
    * Certificate admins are identities with role configured by property ''idm.sec.crt.processor.certificate-created-notification-admin-processor.adminRole''. When no identity is found, then notification isn't sent. 
    * Can be disabled by property ''idm.sec.crt.processor.certificate-created-notification-admin-processor.enabled=false''.
  * **requestApproved** - When certificate request is approved, notification is sent to certificate owner.
  * **requestDisapproved** - When certificate request is disapproved, notification is sent to certificate owner.

Each topic has template with the same name with ''Crt'' prefix in module resources.

===== Security configuration =====

Authoritazion policies have to be configured to work with certificates, cards and certificate authorities. Authorities can be configured on a role and then role can be assigned to identity.

==== Create request and download certificate ====

If we want to an identity can request a certificates, we set authorization policies as follows:
  * Permission to read and download one's own identity certificates: Certificates (CrtCertificate) | Read | SelfCertificateEvaluator
  * Permission to read, create, update and cancel one's own identity certificate requests: Certificate requests (CrtRequest) | Create, Read, Update | SelfRequestEvaluator
  * Enabling the autocomplete for entities:
    * Certificate authorities (CrtAuthority) | Displaying in autocomplete, selections | BasePermissionEvaluator

When request is created, certificate authority has to be selected (autocomplete authorities permission). Request is created (as concept), description can be edited and then request is submitted to approving (if approving is configured). After certificate is generated, identity can read, renew and revoke him.

<note tip>Renew and revoke certificate is controlled by create request permission (''CERTIFICATEREQUEST_CREATE'').</note>

<note tip>Certificate authority public certificate can be downloaded from authority info card, when autocomplete permission to certificate authority is granted.</note>

==== Upload certificate ====
Certificate generated by third party authority can be uploaded to CzechIdM (or synchronized from target system).
If we want to an identity can upload certificate, we set authorization policies as follows:
  * Permission to read, create and download one's own identity certificates: Certificates (CrtCertificate) | Read, Create | SelfCertificateEvaluator

==== Certificate request approver ====
If we want to an identity can approve certificate request, we can use ''RequestByWfInvolvedIdentityEvaluator'' authorization policy evaluator. This evaluator grants permission to read certificate requests, which can be approved by logged identity. It's good to have autocomplete permission to identities (or subordinates etc.), otherwise identity identifier is shown as request owner on request detail.

==== Certificate and certificate authorities administrator ====

If we want to an identity, which can administer certificates and authorities, we set authorization policies as follows:
  * Permission to all certificates: Certificates (CrtCertificate) | Admin | BasePermissionEvaluator
  * Permission to all certificate requests: Certificate requests (CrtRequest) | Admin | BasePermissionEvaluator
  * Permission to all certificate authorities: Certificate authorities (CrtAuthority) | Admin | BasePermissionEvaluator

==== Cards administrator ====

If we want to an identity, which can administer cards, we set authorization policies as follows:
  * Permission to all card: Cards (CrtCard) | Admin | BasePermissionEvaluator

==== Cards administrator with the possibility to assign certificates to cards ====

If we want to an identity, which can administer cards and also assign certificates to cards, we set authorization policies as follows:
  * Permission to all card: Cards with certificates (CrtCard) | Admin | BasePermissionEvaluator
  * Permission to all card-certificates: Association of Cards and certificates (CrtCardCertificate) | Admin | BasePermissionEvaluator
  * Permission to all certificates: Certificates (CrtCertificate) | Read, autocomplete | BasePermissionEvaluator


Policies can be configured by custom needs. This example enables all operations with certificates, cards, requests and certificate authorities.

<note tip>Private certificate can be downloaded just by certificate owner. Even identity with admin permission for certificates cannot download private certificates for other identities.</note>



===== Long running tasks configuration =====

==== CertificateRequestRefreshTaskExecutor ====

Some certificate authorities can generate certificate asynchronously. This task checks certificate state on the certificate authority. When certificate is generated by the authority, then request is completed and certificate is saved in CzechIdM as attachment.

Default schedule: ''0 0 1 ? * *''

==== CertificateExpiredTaskExecutor ====

Expire certificates - persists certificate state, when certificate expires.

Default schedule: ''0 0 1 ? * *''

<note important>Expiration is controlled (and all notifications are send) even for archived certificates.</note>

==== CertificateExpirationWarningOwnerTaskExecutor ====

Sends warning notifications before certificate expires to certificate owner.

Parameters:
  * ''days before'' - notification is sent number of days before certificate expiration

Not scheduled by default.

==== CertificateExpirationWarningAdminTaskExecutor ====

Sends warning notifications before certificates expire to certificate admin.

Parameters:
  * ''days before'' - notification is sent number of days before certificate expiration
  * ''admin role'' - certificate admins are identities with this role. When no identity is found, then notification isn't sent.
Not scheduled by default.

===== Cards =====
From version 2.0.1 this module is supporting cards. Card can be USB stick, where the certificates are stored or some chip card with certificates.
There is option to store information about these cards in IdM. Cards can be found under new agenda, see picture below.
{{ :devel:documentation:modules_crt:adm:menu.png?nolink |}}

Cards can be created via modal window.
{{ :devel:documentation:modules_crt:adm:add.png?nolink |}}

On card's detail, there is option to manage which certificates are assigned to given card. Each certificate cab only assigned to one card, but card can has multiple certificates.
There is no further logic behind cards. So there are no request, approving, notification.
When some certificate is deleted the association between card and certificate is deleted to. Same behavior is implemented if some card is deleted.