e-SiTef

e-SiTef

  • Portal do Desenvolvedor
  • Fale Conosco
  • English

›General Information

REST Payment

  • Overview
  • Quick start
  • Transaction creation service
  • Payment effectuation service
  • Payment confirmation service
  • Transaction status query
  • Multiple transactions status query
  • Card query service
  • Payment with multiple payment methods service
  • Payment with multiple payment methods confirmation service
  • External origin payment confirmation service

REST Store

  • Overview

REST Cancel

  • Flow
  • Quick start
  • Cancel via host
  • Cancel external origin
  • Cancel creation service
  • Cancel service

REST Pre-Authorization

  • Overview
  • Quick start
  • Pre-Authorization Creation Service
  • Pre-Authorization effectuation service
  • Pre-Authorization Status Query
  • Pre-Authorization Editing Service
  • Pre-Authorization Editing External Origin Service
  • Pre-Authorization Increment Service
  • Card Query Service
  • Pre-Authorization Capture Service
  • Pre-Authorization Capture External Origin Service

REST Schedule

  • Overview
  • Quick start
  • Transaction creation service
  • Schedule activation service
  • Execution of the scheduled payments
  • Schedule editing flow
  • Quick start: schedule editing
  • Schedule editing creation service
  • Schedule editing service

REST Recharge

  • Overview
  • Quick start
  • Recharge creation service
  • List dealers service
  • List branch data service
  • Recharge effectuation service
  • Recharge confirmation service
  • Recharge query service

HTML Payment

  • Overview
  • Quick start
  • Initializing a payment transaction
  • Status notification
  • Transaction status query
  • Payment with card storage
  • Pages Customization
  • Payment link
  • Split Payment
  • Payment with multiple payment methods
  • 3DS 2.0 Integration

HTML Pre-Authorization

  • Overview

HTML Recharge

  • Overview
  • Quick start
  • Initializing a Recharge transaction

REST Generic Operations

  • Overview
  • Token creation service
  • Generic operation service

JavaScript Payment

  • Overview
  • Quick start
  • Transaction creation service
  • Virtual store's payment page
  • Transaction query service

JavaScript Store

  • Overview
  • Quick start
  • Transaction creation service
  • Virtual store's page

Merchant Web Page

  • Introduction
  • Access to web page
  • Two-Factor Authentication
  • User Configuration
  • Configure Authorizers
  • Transaction Report
  • Daily Summary Report
  • Store Report
  • Recharge Report
  • Analytical Report
  • Transaction Cancellation
  • Schedule
  • Configure Risk Analysis
  • Configure Order Authorizers
  • Users Administration
  • Generate Payment Link

Retry

  • Overview
  • Flow
  • Retry and Schedule

SiTef Routings

  • Bradescard
  • Cetelem
  • GetnetLac
  • Orbitall
  • Vero
  • Bin
  • Sipag

Non SiTef Routings

  • Banco do Brasil
  • Banrisul Vero
  • Cielo e-Commerce
  • EPX
  • e.Rede Rest
  • Fepas HUB
  • Getnet WS
  • GlobalPayments WS
  • IPG
  • Itaú Shopline
  • Mercado Pago
  • PagSeguro
  • PayPal
  • SafraPay
  • Stone WS

Digital Wallet

  • Overview
  • VEE Digital Wallet via CardSE
  • Pix via CardSE
  • Google Pay
  • Visa Checkout
  • Masterpass
  • Samsung Pay
  • Apple Pay
  • Configuration for Digital Wallets

Anti-Fraud Integration

  • Overview
  • Risk analysis service on the HTML Interface
  • Risk analysis response
  • Manual review flow
  • Fraud notification service
  • ClearSale
  • CyberSource
  • Konduto
  • Fraud Detect

General Information

  • Authorizers
  • Digital Certificates
  • API codes
  • Soft Descriptor
  • Signature authentication

Batch Registrations

  • Batch Store Registration
  • Batch Routing Configuration

REST Merchants Registration

  • Overview
  • Quick start
  • Token creation service
  • Merchant creation service
  • Merchant editing service
  • Merchant query service
  • Merchant status query service
  • List merchants service
  • API codes

3DS Server

  • Overview
  • Quick start
  • Transaction creation service
  • Authentication service
  • Transaction query service
  • Challenge messages
  • Decoupled notification
  • Initiating a 3DS Method
  • API codes

Digital Certificates

Introduction

The purpose of this document is to guide the customer who will integrate their product with e-SiTef 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 e-SiTef 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

Certificate Info

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

Firefox Certificate

Chrome

Chrome Certificate

Internet Explorer

IE Certificate

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 e-SiTef Communication

E-SiTef 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 e-SiTef 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 e-SiTef 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 e-SiTef 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 e-SiTef. This requirement in the e-SiTef 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 1

Certificate Details at Firefox

Certificate Details 2

← AuthorizersAPI codes →
  • Introduction
  • Digital Certificate
    • Self-signed Certificates
  • Client Servers e-SiTef Communication
  • Self-signed Certificate Creation
    • Openssl Setup: openssl.cnf
    • Openssl Commands for Certificate Creation
  • Install of Self-signed Certificate Generated by Apache
  • Generated Certificate Verify
    • Certificate Details at Windows Enviroment
    • Certificate Details at Firefox
e-SiTef
Relacionamento com o cliente
+55 (11) 3170-5300+55 (11) 4766-8000comercial@softwareexpress.com.br
Acessos
Portal do DesenvolvedorPortal e-SiTefVersão para impressão
Copyright © 2021 Software Express Informática Ltda - Todos os direitos reservados