# Configurar o acesso UTL\$1HTTP usando certificados e uma carteira Oracle
O Amazon RDS comporta o acesso à rede de saída nas instâncias de banco de dados Oracle. Para conectar sua instância de banco de dados à rede, você pode usar os seguintes pacotes PL/SQL:
`UTL_HTTP`
Este pacote faz chamadas HTTP do SQL e PL/SQL. Você pode usá-lo para acessar dados na Internet com HTTP. Para obter mais informações, consulte [UTL\$1HTTP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_HTTP.html#GUID-A85D2D1F-90FC-45F1-967F-34368A23C9BB) na documentação da Oracle.
`UTL_TCP`
Este pacote fornece funcionalidade de acesso TCP/IP do lado do cliente em PL/SQL. Esse pacote é útil para aplicações PL/SQL que usam protocolos de Internet e e-mail. Para obter mais informações, consulte [UTL\$1TCP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_TCP.html#GUID-348AFFE8-78B2-4217-AE73-384F46A1D292)na documentação da Oracle.
`UTL_SMTP`
Este pacote fornece interfaces aos comandos SMTP que permitem que um cliente despache e-mails para um servidor SMTP. Para obter mais informações, consulte [UTL\$1SMTP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_SMTP.html#GUID-F0065C52-D618-4F8A-A361-7B742D44C520) na documentação da Oracle.
Ao concluir as tarefas a seguir, você pode configurar o `UTL_HTTP.REQUEST` para trabalhar com sites que exigem certificados de autenticação de cliente durante o handshake SSL. Você também pode configurar a autenticação por senha para acesso `UTL_HTTP` a sites modificando os comandos de geração da carteira Oracle e o procedimento `DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE`. Para obter mais informações, consulte [DBMS\$1NETWORK\$1ACL\$1ADMIN](https://docs.oracle.com/en/database/oracle/oracle-database/21/arpls/DBMS_NETWORK_ACL_ADMIN.html) na documentação do Oracle Database.
**nota**
Você pode adaptar as seguintes tarefas para o `UTL_SMTP`, que permite enviar e-mails por SSL/TLS (incluindo o [Amazon Simple Email Service](https://aws.amazon.com/ses/)).
**Topics**
+ [Considerações ao configurar o acesso UTL\$1HTTP](#utl_http-considerations)
+ [Etapa 1: obter o certificado raiz de um site](#website-root-certificate)
+ [Etapa 2: criar uma carteira Oracle](#create-oracle-wallet)
+ [Etapa 3: baixar a carteira Oracle para sua instância do RDS for Oracle](#upload-wallet-to-instance)
+ [Etapa 4: conceder permissões de usuário para a carteira Oracle](#config-oracle-wallet-user)
+ [Etapa 5: configurar o acesso a um site da sua instância de banco de dados](#config-website-access)
+ [Etapa 6: testar conexões de sua instância de banco de dados para um site](#test_utl_http)
## Considerações ao configurar o acesso UTL\$1HTTP
Antes de configurar o acesso, pense no seguinte:
+ É possível usar SMTP com a opção UTL\$1MAIL. Para obter mais informações, consulte [Oracle UTL\$1MAIL](Oracle.Options.UTLMAIL.md).
+ O nome do servidor de nomes de domínio (DNS) do host remoto pode ser um dos seguintes:
+ Resolvível publicamente.
+ O endpoint de uma instância de banco de dados do Amazon RDS.
+ Resolvível através de um servidor DNS personalizado. Para obter mais informações, consulte [Configuração de um servidor DNS personalizado](Appendix.Oracle.CommonDBATasks.System.md#Appendix.Oracle.CommonDBATasks.CustomDNS).
+ O nome DNS privado de uma instância do Amazon EC2 na mesma VPC ou em uma VPC emparelhada. Nesse caso, certifique-se de que o nome seja resolvível através de um servidor DNS personalizado. Como alternativa, para usar o DNS fornecido pela Amazon, você pode habilitar o atributo `enableDnsSupport` nas configurações da VPC e habilitar o suporte à resolução de DNS para a conexão de emparelhamento de VPC. Para obter mais informações, consulte [Suporte ao DNS na VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support) e [Modificação da conexão de emparelhamento de VPC](https://docs.aws.amazon.com/vpc/latest/peering/working-with-vpc-peering.html#modify-peering-connections).
+ Para se conectar com segurança a recursos remotos de SSL/TLS, você pode criar e carregar carteiras Oracle personalizadas. Usando o recurso de Integração do Amazon S3 com o Amazon RDS for Oracle, você pode baixar uma carteira do Amazon S3 em instâncias de banco de dados Oracle. Para obter informações sobre a integração do Amazon S3 para Oracle, consulte [Integração do Amazon S3](oracle-s3-integration.md).
+ Você poderá estabelecer links de banco de dados entre instâncias de bancos de dados Oracle em um endpoint SSL/TLS se a opção Oracle SSL estiver configurada para cada instância. Nenhuma outra configuração é necessária. Para obter mais informações, consulte [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
## Etapa 1: obter o certificado raiz de um site
Para que a instância de banco de dados do RDS para Oracle faça conexões seguras com um site, adicione o certificado de CA raiz. O Amazon RDS usa o certificado raiz para assinar o certificado do site para a carteira Oracle.
Você pode obter o certificado raiz de várias maneiras. Por exemplo, você pode fazer o seguinte:
1. Use um servidor Web para visitar o site protegido pelo certificado.
1. Baixe o certificado raiz usado para assinatura.
Para serviços da AWS, os certificados geralmente podem ser encontrados no [Repositório de serviços de confiança da Amazon](https://www.amazontrust.com/repository/).
## Etapa 2: criar uma carteira Oracle
Crie uma carteira Oracle que contenha os certificados do servidor Web e os certificados de autenticação do cliente. A instância Oracle do RDS usa o certificado do servidor Web para estabelecer uma conexão segura com o site. O site precisa do certificado do cliente para autenticar o usuário do banco de dados Oracle.
Talvez você queira configurar conexões seguras sem usar certificados de cliente para autenticação. Nesse caso, você pode ignorar as etapas do armazenamento de chaves Java no procedimento a seguir.
**Para criar uma carteira Oracle**
1. Coloque os certificados raiz e do cliente em um único diretório e, em seguida, mude para esse diretório.
1. Converta o certificado do cliente .p12 para o repositório de chaves Java.
**nota**
Se não estiver usando certificados de cliente para autenticação, ignore esta etapa.
O exemplo a seguir converte o certificado do cliente chamado *client\$1certificate.p12* para o repositório de chaves Java chamado *client\$1keystore.jks*. O repositório de chaves é então incluído na carteira Oracle. A senha do repositório de chaves é *P12PASSWORD*.
```
orapki wallet pkcs12_to_jks -wallet ./client_certificate.p12 -jksKeyStoreLoc ./client_keystore.jks -jksKeyStorepwd P12PASSWORD
```
1. Crie um diretório para sua carteira Oracle diferente do diretório de certificados.
O exemplo a seguir cria o diretório `/tmp/wallet`.
```
mkdir -p /tmp/wallet
```
1. Crie uma carteira Oracle no diretório da carteira.
O exemplo a seguir define a senha da carteira Oracle como *P12PASSWORD*, que é a mesma senha usada pelo repositório de chaves Java em uma etapa anterior. Usar a mesma senha é conveniente, mas não é necessário. O parâmetro `-auto_login` ativa o recurso de login automático para que você não precise especificar uma senha toda vez que quiser acessá-la.
**nota**
Especifique uma senha diferente do prompt mostrado aqui como prática recomendada de segurança.
```
orapki wallet create -wallet /tmp/wallet -pwd P12PASSWORD -auto_login
```
1. Adicione o repositório de chaves Java à sua carteira Oracle.
**nota**
Se não estiver usando certificados de cliente para autenticação, ignore esta etapa.
O exemplo a seguir inclui o repositório de chaves *client\$1keystore.jks* para a carteira Oracle chamada */tmp/wallet*. Neste exemplo, você especifica a mesma senha para o repositório de chaves Java e para a carteira Oracle.
```
orapki wallet jks_to_pkcs12 -wallet /tmp/wallet -pwd P12PASSWORD -keystore ./client_keystore.jks -jkspwd P12PASSWORD
```
1. Adicione o certificado raiz do seu site de destino à carteira Oracle.
O exemplo a seguir inclui um certificado chamado *Root\$1CA.cer*.
```
orapki wallet add -wallet /tmp/wallet -trusted_cert -cert ./Root_CA.cer -pwd P12PASSWORD
```
1. Inclua qualquer certificado intermediário.
O exemplo a seguir inclui um certificado chamado *Intermediate.cer*. Repita essa etapa quantas vezes for necessário para carregar todos os certificados intermediários.
```
orapki wallet add -wallet /tmp/wallet -trusted_cert -cert ./Intermediate.cer -pwd P12PASSWORD
```
1. Confirme se sua carteira Oracle recém-criada tem os certificados necessários.
```
orapki wallet display -wallet /tmp/wallet -pwd P12PASSWORD
```
## Etapa 3: baixar a carteira Oracle para sua instância do RDS for Oracle
Nesta etapa, você carrega sua carteira Oracle para o Simple Storage Service (Simple Storage Service (Amazon S3)) e, em seguida, baixa a carteira do Simple Storage Service (Amazon S3) para sua instância do RDS for Oracle.
**Para baixar sua carteira Oracle em sua instância de banco de dados do RDS for Oracle**
1. Conclua os pré-requisitos para a integração do Amazon S3 com o Oracle e adicione a opção `S3_INTEGRATION` à sua instância de banco de dados Oracle. Certifique-se de que a função do IAM para a opção tenha acesso ao bucket do Amazon S3 que você está usando.
Para obter mais informações, consulte [Integração do Amazon S3](oracle-s3-integration.md).
1. Faça login na sua instância de banco de dados como o usuário primário e crie um diretório Oracle para manter a carteira Oracle.
O exemplo a seguir cria um diretório Oracle chamado *WALLET\$1DIR*.
```
EXEC rdsadmin.rdsadmin_util.create_directory('WALLET_DIR');
```
Para obter mais informações, consulte [Criar e eliminar diretórios no espaço de armazenamento de dados principal](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.NewDirectories).
1. Carregue a carteira Oracle para o seu bucket do Simple Storage Service (Amazon S3).
Você pode usar qualquer técnica de carregamento compatível.
1. Se estiver carregando novamente uma carteira Oracle, exclua a carteira existente. Caso contrário, vá para a próxima etapa.
O exemplo a seguir remove a carteira existente chamada *cwallet.sso*.
```
EXEC UTL_FILE.FREMOVE ('WALLET_DIR','cwallet.sso');
```
1. Baixe a carteira Oracle do seu bucket do Simple Storage Service (Simple Storage Service (Amazon S3)) para a instância de banco de dados Oracle.
O exemplo a seguir baixa a carteira chamada *cwallet.sso* do bucket do Amazon S3 chamado *my\$1s3\$1bucket* para o diretório da instância de banco de dados chamado *WALLET\$1DIR*.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'my_s3_bucket',
p_s3_prefix => 'cwallet.sso',
p_directory_name => 'WALLET_DIR')
AS TASK_ID FROM DUAL;
```
1. (Opcional) Baixe uma carteira Oracle protegida por senha.
Baixe esta carteira somente se quiser exigir uma senha para cada uso da carteira. O exemplo a seguir baixa a carteira protegida por senha *ewallet.p12*.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'my_s3_bucket',
p_s3_prefix => 'ewallet.p12',
p_directory_name => 'WALLET_DIR')
AS TASK_ID FROM DUAL;
```
1. Verifique o status da sua tarefa do banco de dados.
Substitua o ID da tarefa retornado das etapas anteriores para *dbtask-1234567890123-4567.log* no exemplo a seguir.
```
SELECT TEXT FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-4567.log'));
```
1. Verifique o conteúdo do diretório que você está usando para armazenar a carteira Oracle.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'WALLET_DIR'));
```
Para obter mais informações, consulte [Listagem de arquivos no diretório de uma instância de banco de dados](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ListDirectories).
## Etapa 4: conceder permissões de usuário para a carteira Oracle
Você pode criar um novo usuário do banco de dados ou configurar um usuário existente. Em ambos os casos, você deve configurar o usuário para acessar a carteira Oracle para conexões seguras e autenticação do cliente usando certificados.
**Para conceder permissões do usuário para a carteira Oracle**
1. Faça login na instância de banco de dados do RDS for Oracle como usuário primário.
1. Se não quiser configurar um usuário do banco de dados existente, crie um novo usuário. Caso contrário, vá para a próxima etapa.
O exemplo a seguir cria um usuário do banco de dados chamado *my-user*.
```
CREATE USER my-user IDENTIFIED BY my-user-pwd;
GRANT CONNECT TO my-user;
```
1. Conceda permissão ao usuário do banco de dados no diretório que contém sua carteira Oracle.
O exemplo a seguir concede acesso de leitura ao usuário *my-user* no diretório *WALLET\$1DIR*.
```
GRANT READ ON DIRECTORY WALLET_DIR TO my-user;
```
1. Conceda permissão ao usuário do banco de dados para usar o pacote `UTL_HTTP`.
O programa PL/SQL a seguir concede acesso `UTL_HTTP` ao usuário *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_HTTP', UPPER('my-user'));
END;
/
```
1. Conceda permissão ao usuário do banco de dados para usar o pacote `UTL_FILE`.
O programa PL/SQL a seguir concede acesso `UTL_FILE` ao usuário *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_FILE', UPPER('my-user'));
END;
/
```
## Etapa 5: configurar o acesso a um site da sua instância de banco de dados
Nesta etapa, você configura o usuário do banco de dados Oracle para que ele possa se conectar ao site de destino usando o `UTL_HTTP`, a carteira Oracle carregada e o certificado do cliente. Para obter mais informações, consulte [Configuring Access Control to an Oracle Wallet](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/managing-fine-grained-access-in-pl-sql-packages-and-types.html#GUID-0BCB5925-A40F-4507-95F9-5DA4A1919EBD) (Configurar o controle de acesso a uma carteira Oracle) na documentação do Oracle Database.
**Para configurar o acesso a um site da instância de banco de dados do RDS for Oracle**
1. Faça login na instância de banco de dados do RDS for Oracle como usuário primário.
1. Crie uma entrada de controle de acesso ao host (ACE) para o usuário e o site de destino em uma porta segura.
O exemplo a seguir configura *my-user* para acessar o *secret.encrypted-website.com* na porta segura 443.
```
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => 'secret.encrypted-website.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(privilege_list => xs$name_list('http'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
-- If the program unit results in PLS-00201, set
-- the principal_type parameter to 2 as follows:
-- principal_type => 2));
END;
/
```
**Importante**
A unidade do programa anterior pode ocasionar o seguinte erro: `PLS-00201: identifier 'XS_ACL' must be declared`. Se esse erro for exibido, substitua a linha que atribui um valor a `principal_type` com a seguinte linha e, depois, execute novamente a unidade do programa:
```
principal_type => 2));
```
Para ter mais informações sobre constantes no pacote PL/SQL `XS_ACL`, consulte o [https://docs.oracle.com/en/database/oracle/oracle-database/19/dbfsg/XS_ACL-package.html#GUID-A157FB28-FE23-4D30-AAEB-8224230517E7](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbfsg/XS_ACL-package.html#GUID-A157FB28-FE23-4D30-AAEB-8224230517E7) na documentação do Oracle Database.
Para obter mais informações, consulte [Configuring Access Control for External Network Services](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/managing-fine-grained-access-in-pl-sql-packages-and-types.html#GUID-3D5B66BC-0277-4887-9CD1-97DB44EB5213) (Configuração do controle de acesso para serviços de rede externos) na documentação do Oracle Database.
1. (Opcional) Crie uma ACE para seu usuário e site de destino na porta padrão.
Talvez seja necessário usar a porta padrão se algumas páginas da Web forem exibidas da porta padrão do servidor Web (80) em vez da porta segura (443).
```
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => 'secret.encrypted-website.com',
lower_port => 80,
upper_port => 80,
ace => xs$ace_type(privilege_list => xs$name_list('http'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
-- If the program unit results in PLS-00201, set
-- the principal_type parameter to 2 as follows:
-- principal_type => 2));
END;
/
```
1. Confirme se as entradas de controle de acesso existem.
```
SET LINESIZE 150
COLUMN HOST FORMAT A40
COLUMN ACL FORMAT A50
SELECT HOST, LOWER_PORT, UPPER_PORT, ACL
FROM DBA_NETWORK_ACLS
ORDER BY HOST;
```
1. Conceda permissão ao usuário do banco de dados para usar o pacote `UTL_HTTP`.
O programa PL/SQL a seguir concede acesso `UTL_HTTP` ao usuário *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_HTTP', UPPER('my-user'));
END;
/
```
1. Confirme se existem listas de controle de acesso relacionadas.
```
SET LINESIZE 150
COLUMN ACL FORMAT A50
COLUMN PRINCIPAL FORMAT A20
COLUMN PRIVILEGE FORMAT A10
SELECT ACL, PRINCIPAL, PRIVILEGE, IS_GRANT,
TO_CHAR(START_DATE, 'DD-MON-YYYY') AS START_DATE,
TO_CHAR(END_DATE, 'DD-MON-YYYY') AS END_DATE
FROM DBA_NETWORK_ACL_PRIVILEGES
ORDER BY ACL, PRINCIPAL, PRIVILEGE;
```
1. Conceda permissão ao usuário do banco de dados para usar certificados para autenticação de cliente e sua carteira Oracle para conexões.
**nota**
Se não estiver usando certificados de cliente para autenticação, ignore esta etapa.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE(
wallet_path => 'file:/' || l_wallet_path,
ace => xs$ace_type(privilege_list => xs$name_list('use_client_certificates'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
END;
/
```
## Etapa 6: testar conexões de sua instância de banco de dados para um site
Nesta etapa, você configura o usuário do banco de dados para que ele possa se conectar ao site usando o `UTL_HTTP`, a carteira Oracle carregada e o certificado do cliente.
**Para configurar o acesso a um site da instância de banco de dados do RDS for Oracle**
1. Faça login na instância de banco de dados do RDS for Oracle como usuário do banco de dados com permissões `UTL_HTTP`.
1. Confirme se uma conexão com o site de destino pode resolver o endereço do host.
O exemplo a seguir obtém o endereço do host de *secret.encrypted-website.com*.
```
SELECT UTL_INADDR.GET_HOST_ADDRESS(host => 'secret.encrypted-website.com')
FROM DUAL;
```
1. Teste uma conexão com falha.
A consulta a seguir falha porque `UTL_HTTP` requer a localização da carteira Oracle com os certificados.
```
SELECT UTL_HTTP.REQUEST('secret.encrypted-website.com') FROM DUAL;
```
1. Teste o acesso ao site usando `UTL_HTTP.SET_WALLET` e selecionando do `DUAL`.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
UTL_HTTP.SET_WALLET('file:/' || l_wallet_path);
END;
/
SELECT UTL_HTTP.REQUEST('secret.encrypted-website.com') FROM DUAL;
```
1. (Opcional) Teste o acesso ao site armazenando sua consulta em uma variável e usando `EXECUTE IMMEDIATE`.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
v_webpage_sql VARCHAR2(1000);
v_results VARCHAR2(32767);
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
v_webpage_sql := 'SELECT UTL_HTTP.REQUEST(''secret.encrypted-website.com'', '''', ''file:/' ||l_wallet_path||''') FROM DUAL';
DBMS_OUTPUT.PUT_LINE(v_webpage_sql);
EXECUTE IMMEDIATE v_webpage_sql INTO v_results;
DBMS_OUTPUT.PUT_LINE(v_results);
END;
/
```
1. (Opcional) Encontre a localização do sistema de arquivos do diretório da carteira Oracle.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'WALLET_DIR'));
```
Use a saída do comando anterior para fazer uma solicitação HTTP. Por exemplo, se o diretório for *rdsdbdata/userdirs/01*, execute a consulta a seguir.
```
SELECT UTL_HTTP.REQUEST('https://secret.encrypted-website.com/', '', 'file://rdsdbdata/userdirs/01')
FROM DUAL;
```