Digital Certificates

Introduction

The purpose of this document is to guide the customer who will integrate their product with Carat Portal on the use of Digital Certificates.

The purpose of this is to present in a simplified way small guidelines on the use of these to ensure the communication security between Carat Portal and the customer's product.

In case it is necessary to go deeper into the subjects presented, we suggest consult other literature and sources available on-line.

Digital Certificate

The Digital Certificate or Public Key Certificate ('certificate' hereinafter) is a digital document that has the purpose of certifying the identity of a person, or entity in digital communication. A form of secure digital communication widely used on-line is HTTPS, which is an abbreviation for HTTP over SSL / TLS.

The certificate is usually requested by the person or entity and issued by a CA (Certification Authority, or Certification Authority, in English) such as Verisign, CertSign, etc. A valid certificate is one that, among other requirements, is within its expiration date and signed by a trusted CA.

As an example, when we use a browser (Firefox, Chrome, etc.) to access a website that offers security in communication using HTTPS, in general the certificate used by the website server is presented, usually symbolized by a padlock that is located near the URL. By clicking on this lock icon, it is possible to detail the characteristics of this certificate.

The main characteristic of a certificate is the name to which it is issued, that is, what is the name identified in the certificate. In the image below we can see the information, where the certificate is issued by CA “Network Solutions DV Server” and issued to the name esitef.softwareexpress.com.br

Self-signed Certificates

For testing environments, there are cases where obtaining a valid certificate is not feasible, therefore a self-signed signed certificate is sometimes used.

A self-signed certificate is generated and signed by the person/entity itself and is not accepted as reliable for secure communication. As an example, when accessing a website via a browser via HTTPS, where the server uses a self-signed certificate, a warning similar to the images below is displayed in the browser:

Firefox

Chrome

Internet Explorer

When browsing through these sites that use self-signed certificates, we have the option of trusting the site and accessing them, even knowing that the certificate presented on them is not trusted, taking the risk of accessing and sending information to a site that does not have the certificate trusted or even with a certificate that doesn't have the identity of who he claims to be. This can also be applied to communication between servers.

Client Servers Carat Portal Communication

Carat Portal often communicates with customer servers via HTTPS POST’s, to validate the authenticity of the request, such as in recharge transactions and payment reversals. For this communication, it is necessary that the client's server presents valid certificates to guarantee the security of the transmitted information. In Carat Portal production environment, in general all customers already have a ready infrastructure, with servers and their respective valid certificates signed by well-established CA's.

However, in the testing stage, many systems are still using temporary certificates, and often self-signed ones. In this case, we use an approach similar to that mentioned previously, making exceptions for Carat Portal to trust a server that presents a self-signed certificate. This is accomplished by importing it into a trusted certificates list. Thus we can facilitate the approval process for customer systems.

As the technology used in Carat Portal follows the RFC-2818 HTTPS communication specification, this approach has some restrictions:

• The certificate must be valid, that is, at least it must have its expiration date appropriate for the use period;
• The identification of the client's server must be compatible with the name shown on the certificate. Therefore, the following situations will result in communication failure:
  • A certificate issued to www.dominio.com will not be compatible for a server identified as dominio.com or tests.dominio.com as different identifications are considered;
  • A server with a single IP but with multiple domains and respectively multiple certificates can be identified in different and unexpected ways;
  • The specification does not allow certificates issued for the IP address of a server unless Subject Alternative Names from IP’s or domains are added to the certificate.

Therefore, certificates that are in other conditions than the specified will not be accepted in HTTPS communication even if they are imported into the trusted certificates list in Carat Portal. This requirement in the Carat Portal approval environment ends up preparing the customer in order to guarantee the use of a certificate correctly issued by a CA for the system in the production environment.

Self-signed Certificate Creation

There are several ways to generate self-signed certificates. Here we will present one of them, using the openssl tool, which can be found in Apache web server packages. All references and commands presented below are based on Apache HTTP 2.2 and openssl 0.9.8 versions in Windows environment. If it is the customer's preference, a similar procedure can be performed in a Linux environment, with the appropriate tools and adaptations.

As enviroment setup, we suggest the following:

• create a separate folder named openssl (or whichever suits better);
• copy the following three files available at %APACHE_HOME%/bin: libeay32.dll, ssleay.dll e zlib1.dll;
• paste those three files at Windows\System32;
• copy the file openssl.exe available at %APACHE_HOME%/bin and paste it at the recently created openssl directory;
• copy the file openssl.cnf available at %APACHE_HOME%/conf and paste it at the recently created openssl directory;

Openssl Setup: openssl.cnf

The openssl.cnf file contains the settings for generating certificates. Initially, create a copy of this with another name, something like openssl_edit.cnf or a name that suits better.

We suggest editing the following fields in the openssl_editado.cnf file to facilitate its future use:

• uncomment (remove the # char) at the beginning of the following line:

  `req_extensions` = v3_req # The extensions to add to a certificate request

• below, add or change default values for the following fields:

  • countryName_default = BR (or another country)
  • stateOrProvinceName_default = \<state/prvince name>
  • localityName_default = \<city name>
  • 0.organizationName_default = \<company name>
  • organizationalUnitName_default = \<sector name, team>
  • commonName_default = \<common name to be registered>
  • emailAddress_default = \<e-mail>

• after the following passage:

  [ v3_req ]

  # Extensions to add to a certificate request

  basicConstraints = CA:FALSE

  keyUsage = nonRepudiation, digitalSignature, keyEncipherment

• add

  subjectAltName=@alt_names

  [alt_names]

• then, just below add alternative names to the commonName, in the form of DNS or IP as in the examples below, according to the server's identification needs:

  DNS.1 = www.dominio.com

  DNS.2 = *.dominio.com

  ...

  IP.1 = 192.168.4.34

  IP.2 = 200.122.10.66

  ...

This concludes the customization of the openssl setup file.

Openssl Commands for Certificate Creation

Let's assume we're trying to create a certificate named dominio.

• create a 2048-bit RSA private key by running the following command at the openssl directory:

  openssl genrsa -out dominio.pem 2048

• execute the following command to request certificate creation:

  openssl req -config openssl_editado.cnf -extensions v3_req -new -out dominio.cer -keyout dominio.pem

• Then run the command below to create the private key that is not password protected (the associated password with the private key will be removed). That way, the key will be readable only by the Apache server and the administrator:

  openssl rsa –in dominio.pem –out dominio.key

After this command execution, the private key password will be asked.

It is highly recommended the removal of .rnd file, as it contains sensitive information regarding the creation of the key. Removing it avoids cryptographic attacks against the private key.

• Finally, execute the command below to create the signed certificate that will last for one year:

  openssl x509 -in dominio.cer -out dominio.cer -req -signkey dominio.key -days 365 -extensions v3_req extfile openssl_editado.cnf

The dominio.cer and dominio.key files will be used on the server.

Install of Self-signed Certificate Generated by Apache

Here we will present an example of installing the certificate on the Apache 2.2 HTTP server.

• in the Apache folder, access conf folder and open httpd-ssl.conf configuration file and edit the following itens:

  ServerName <name/domain or server IP>

  Ex: www.dominio.com.br or IP 200.###.###.###

  SSLCertificateFile <path+certificate name>

  Ex: `%APACHE_HOME%/conf/dominio.cer`

  SSLCertificateKeyFile <path+certificate key file name>

  Ex: %APACHE_HOME%/conf/dominio.key

• Restart Apache.

Generated Certificate Verify

In order to verify that the certificate was generated and installed correctly, open a browser of your choice and enter the URL which Apache responds to, and click the lock icon to open the certificate. The figures below illustrate the certificate visualization in different environments:

Certificate Details at Windows Enviroment

Certificate Details at Firefox