Integração S3

O CESS possui integração com bucket S3 para leitura dos arquivos originais e escrita dos assinados.

Configuração AWS S3

Para utilizar as funcionalidades de integração com S3 é necessário configurar uma variável de ambiente chamada "awsCredentials". Essa variável deverá conter o seguinte json encodado em base64.

Por exemplo, se tivermos o seguinte json: {"region":"REGIAO","aws_access_key_id":"ACESS_ID","aws_secret_access_key":"SECRET_KEY","read_bucket":"BUCKET_LEITURA","write_bucket":"BUCKET_ESCRITA","base_path":"PREFIXO_NOME_OBJETO","use_path_style_endpoint'': "PADRAO_DIFERENTE_DA_AWS", "endpoint": ''ENDPOINT_PERSONALIZADO"}

Obs.: Para utilização de um ambiente próprio, fora da AWS (Nutanix, por exemplo), devem ser informados os parâmetros "use_path_style_endpoint":true e "endpoint":"https://my.custom.endpoint" .

Deveremos configurar a variável de ambiente como : 'awsCredentials=e3JlZ2lvbjpSRUdJQU8sYXdzX2FjY2Vzc19rZXlfaWQ6QUNFU1NfSUQsYXdzX3NlY3JldF9hY2Nlc3Nfa2V5OlNFQ1JFVF9LRVkscmVhZF9idWNrZXQ6QlVDS0VUX0xFSVRVUkEsd3JpdGVfYnVja2V0OkJVQ0tFVF9FU0NSSVRBLGJhc2VfcGF0aDpQUkVGSVhPX05PTUVfT0JKRVRPfQ=='

Observações:

• Há duas configurações de bucket: um para leitura do objeto e outra para escrita. Ou seja, se você deseja que o CESS apenas leia o arquivo armazenado na AWS, deverá preencher a chave "read_bucket"; Caso você deseja que o CESS escreva no bucket, deverá preencher a chave "write_bucket". E, consequentemente, se deseja ler/escrever no S3, deverá configurar ambas chaves.

• A chave "base_path" do json é utilizado apenas para escrita dos objetos. Ou seja, se você deseja que no momento de escrita do objeto no bucket seja adicionado o prefixo "integracao_cess/", precisa configurá-la. Então, se pedir para salvar o arquivo com o nome "cliente1.p7s", o objeto terá o seguinte nome: "integracao_cess/cliente1.p7s". Caso não deseja o prefixo, basta deixá-lo em branco.

CESS lendo do bucket

Para o CESS ler o arquivo original da AWS é necessário, além das configuração anterior, especificar duas chaves na criação da transação: "documents_source" : "AWS_S3" e no documents[] {"data": "nome_do_objeto_no_bucket".

Por exemplo, se deseja que seja assinado o arquivo chamado "meu_arquivo.txt", então poderá utilizar o seguinte json como chamada:

{
	"certificate_alias": "",
	"type": "CAdEs-detached",
	"hash_algorithm": "SHA256",
	"documents_source": "AWS_S3", //OBRIGATÓRIO
	"policy": "AD_RB",
	"checksum_algorithm": "SHA256",
	"mode": "sync",
	"documents": [
		{
			"id": "0",
			"data": "meu_arquivo.txt", //OBRIGATÓRIO
		}
	]
}

CESS escrevendo no bucket

Para o CESS escrever o arquivo assinado na AWS é necessário, além das configuração anterior, especificar duas chaves na criação da transação: "documents_destination" : "AWS_S3" e no documents[] {"destination_file_name": "nome_do_objeto_no_bucket" (opcional).

Por exemplo, se deseja que o arquivo assinado seja armazenado com o nome "minha_assinatura.p7s", então poderá utilizar o seguinte json como chamada:

{
	"certificate_alias": "",
	"type": "CAdEs-detached",
	"hash_algorithm": "SHA256",
	"documents_source": "DATA_URL",
	"documents_destination": "AWS_S3", //OBRIGATÓRIO
	"policy": "AD_RB",
	"checksum_algorithm": "SHA256",
	"mode": "sync",
	"documents": [
		{
			"id": "0",
			"data": "data:text/plain;base64,Y2xldWJlcl90ZXN0ZQ==",
			"destination_file_name": "minha_assinatura.p7s" //OPCIONAL
		}
	]
}

E teremos como resposta, por exemplo:

...
"documents": [
        {
            "id": "0",
            "original_file_name": null,
            "mediatype": "data:text/plain",
            "status": "SIGNED",
            "lifetime": 4000,
            "result": "https://s3.sa-east-1.amazonaws.com/example_bucket/minha_assinatura.p7s",
            "destination_file_name": "minha_assinatura.p7s",
            "checksum": "efb08591eb9abf576f8f1e6cf4fb610b248e5ef5179ae6d6590c27eddc6d5cda"
        }
    ]

Observação:

• Caso não seja definido um valor para variável "destination_file_name", será gerado um aleatório com a seguinte lei de formação: <ano>/<mês>/<dia>/<timestamp>_<numeroAleatório8Dígitos>. Por exemplo: 2020/07/10/1594398391_dc80d9b0.

• Quando cliente optar pelo documents_source DATA_URL, FILE_PATH ou AWS_S3, deverá passar, caso queira especificar um nome para o objeto, o "destination_file_name" no mesmo nível do "id" e "data". Quando optar pelo UPLOAD_REFERENCE, ele tem a opção de criar a chave "documents[]" e passar o "id" e o "destination_file_name" no mesmo nível; pois quando realizar o upload via rota /file-transferer/<tcn> ocorrerá o match entre o document[id] e o id definido na chave "documents[]' na criação da transação.