Criar pedidos de certificado

Todo certificado que o Amplia emite começa com um pedido: ele indica a AC que emite o certificado e guarda a validade do certificado e os dados do titular. Um pedido gera um certificado: depois da emissão, o status do pedido é Issued e o certificateId dele aponta para o certificado. Veja Antes de começar para a chave de API, o endpoint e o id da AC.

Endpoints por formato de certificado

Cada formato de certificado tem o próprio endpoint, POST /api/orders/{format}, cujo corpo recebe os campos comuns abaixo mais um objeto parameters daquele formato:

Formato	Endpoint	parameters
ICP-Brasil (e-CPF, e-CNPJ)	POST /api/orders/pki-brazil	PkiBrazilCertificateParameters
SSL/TLS	POST /api/orders/ssl	SslCertificateParameters
Carteira de Identificação Estudantil (CIE), um certificado de atributo	POST /api/orders/cie	CieCertificateParameters
PrivateID, um certificado de atributo	POST /api/orders/private-id	PrivateIDCertificateParameters
Paraguai	POST /api/orders/pki-paraguay	PkiParaguayCertificateParameters
Equador	POST /api/orders/bce	EcuadorBceCertificateParameters
Cabo Verde	POST /api/orders/pki-cabo-verde	PkiCaboVerdeCertificateParameters
Perfil personalizado	POST /api/orders/custom	CustomCertificateParameters

A API também tem POST /api/orders/latinus e POST /api/orders/br-laboral, e um POST /api/v2/orders genérico, cujo parameters pode ser de qualquer formato. TODO(docs): para que servem os formatos Latinus e BRLaboral.

As bibliotecas cliente escolhem o endpoint pela classe do objeto parameters. As quatro criam pedidos ICP-Brasil, SSL/TLS e CIE; o cliente Node.js também cria pedidos do Paraguai, e o cliente Java, pedidos Latinus. Elas também enviam pedidos CNB e ARISP (e os clientes Java e PHP, pedidos CNB CA) para api/orders/cnb, api/orders/arisp e api/orders/cnb-ca, que a descrição OpenAPI não lista. O Amplia 5.0.1 atende esses três endpoints, com CnbCertificateParameters, CnbCACertificateParameters e ArispCertificateParameters. TODO(docs): os parâmetros dos pedidos CNB, CNB CA e ARISP (veja Colégio Notarial do Brasil - Atribuição de OIDs e ARISP - Estruturas ASN.1 para esses certificados).

Campos comuns

Campo	Significado
caId	Id da AC que emite o certificado.
templateId	Id do modelo (perfil de certificado) a aplicar.
kind	PublicKey ou Attribute.
parameters	Os dados do titular, no formato do endpoint. Obrigatório.
validityEnd, validityStart	Datas até e a partir das quais o certificado é válido.
validity	Validade como intervalo de tempo: as chamadas gravadas das demos enviam "365.00:00:00" para um ano e "90.00:00:00" para 90 dias.
digestAlgorithm	SHA1, SHA256, SHA384 ou SHA512.
serialNumber	Um número de série predefinido para o certificado.
policyOid, policyStatementUrl, policyUserNotices, policies	Políticas de certificado a incluir.
issuePendingApproval	Booleano; as chamadas gravadas das demos enviam false.

• Os samples em Node.js e Python enviam validityEnd como data no padrão MM-DD-YYYY, dois anos depois da data atual.
• Um pedido sem validade, em um modelo que não tem validade padrão, é recusado.
• As bibliotecas cliente só enviam caId, templateId, kind, parameters, validityEnd e um campo para copiar de um certificado; para definir os demais campos, chame a API diretamente. O cliente Java formata validityEnd como MM-dd-yyyy.
• TODO(docs): o que fazem issuePendingApproval e copyFromCertificate, e como um certificado pendente de aprovação é aprovado (POST /api/certificates/{id}/approval).

Certificados ICP-Brasil (e-CPF e e-CNPJ)

PkiBrazilCertificateParameters exige name e cpf. Os demais campos incluem emailAddress, birthDate, phoneNumber, cnpj e companyName para um e-CNPJ, os números de RG e OAB, nis, cei, organization, organizationalUnits e country.

• phoneNumber é necessário quando o titular emite o certificado na página de emissão do Amplia, que envia a ele um código de confirmação por SMS.
• O Amplia tira o subject do certificado desses parâmetros, nunca de um CSR: coloque a identidade aqui, com o CPF e o CNPJ sem máscara e os nomes sem acentos.
• normalizeCommonName e appendIdentifierToCommonName normalizam o Common Name (CN=) e acrescentam a ele o CPF ou o CNPJ.
• Nas chamadas gravadas das demos, um pedido com CPF volta com certificateType e-CPF, e um que também tem cnpj e companyName volta como e-CNPJ.
• Os clientes Node.js, PHP e Python enviam as unidades organizacionais como organizationUnits, enquanto o campo da API é organizationalUnits; o cliente Java usa o nome da API.

Os samples criam um pedido de e-CPF só com o nome e o CPF:

Node.js

const {PkiBrazilCertificateParameters, CreateOrderRequest, CertificateKinds} = require('amplia-client');

const CONFIG = Config.getInstance().get('amplia');
const client = Util.getAmpliaClient();
const request = new CreateOrderRequest({
	caId: CONFIG['caId'],
	validityEnd: Util.getTwoYearsFromNowDate(),
	kind: CertificateKinds.PUBLIC_KEY,
	parameters: new PkiBrazilCertificateParameters({
		name: req.body.subjectName,
		cpf: req.body.cpf
	})
});
let order = await client.createOrder(request);

Java

AmpliaClient client = Util.getAmpliaClient();
CreateOrderRequest<PkiBrazilCertificateParameters> createOrderRequest = new CreateOrderRequest<>();
createOrderRequest.setCAId(ApplicationProperties.getInstance().getAmplia().getCaId());
createOrderRequest.setValidityEnd(Util.getDateYearsFromNow(2));
createOrderRequest.setKind(CertificateKinds.PUBLIC_KEY);
PkiBrazilCertificateParameters parameters = new PkiBrazilCertificateParameters();
parameters.setName(request.getSubjectName());
parameters.setCpf(request.getCpf());
createOrderRequest.setParameters(parameters);
Order order = client.createOrder(createOrderRequest);

PHP

use Lacuna\Amplia\CreateOrderRequest;
use Lacuna\Amplia\CertificateKinds;
use Lacuna\Amplia\PkiBrazilCertificateParameters;

$client = Util::getAmpliaClient();
$createOrderRequest = new CreateOrderRequest();
$createOrderRequest->caId = getConfig()['amplia']['caId'];
$createOrderRequest->validityEnd = Util::getDateYearsFromNow(2);
$createOrderRequest->kind = CertificateKinds::PUBLIC_KEY;
$parameters = new PkiBrazilCertificateParameters();
$parameters->name = $subjectName;
$parameters->cpf = $cpf;
$createOrderRequest->parameters = $parameters;
$order = $client->createOrder($createOrderRequest);

Python

from amplia_client import CreateOrderRequest, CertificateKinds, PkiBrazilCertificateParameters

client = get_amplia_client()
req = CreateOrderRequest()
req.ca_id = current_app.config['AMPLIA_CA_ID']
req.validity_end = get_two_years_from_now_date()
req.kind = CertificateKinds.PUBLIC_KEY
parameters = PkiBrazilCertificateParameters()
parameters.name = request.form['subjectName']
parameters.cpf = request.form['cpf']
req.parameters = parameters
order = client.create_order(req)

Por HTTP, a demo de e-CPF envia este corpo para POST /api/orders/pki-brazil (dados pessoais mascarados). O cliente dela serializa os enums como números ("Format": 1, "Kind": 1), enquanto a resposta os traz pelo nome ("format": "PkiBrazil", "kind": "PublicKey"):

{
  "Parameters": {
    "Format": 1,
    "Name": "(DEMO) Diego Rocha Gomes",
    "EmailAddress": "someone@example.com",
    "Cpf": "***.***.***-**",
    "BirthDate": "1988-12-06T00:00:00",
    "OrganizationalUnits": [
      "Lab"
    ],
    "Organization": "Lacuna Software Demo",
    "Country": "BR",
    "PhoneNumber": "+55 ** *****-****"
  },
  "CAId": "00000000-0000-0000-0000-000000000000",
  "Kind": 1,
  "Validity": "365.00:00:00",
  "IssuePendingApproval": false
}

Certificados SSL/TLS

SslCertificateParameters traz dnsNames, subjectName, keyUsages, extendedKeyUsages, qualifiedStatements e organizationIdentifier. Os certificados SSL/TLS do Amplia seguem as diretrizes do CA/Browser Forum e aceitam nomes curinga (wildcard) e endereços IP além de nomes DNS comuns.

Os nomes DNS e o subject vêm do pedido, nunca do CSR: a demo de SSL/TLS define explicitamente os nomes DNS, o subject, os usos de chave DigitalSignature e KeyEncipherment e o uso estendido ServerAuth. Ela envia este corpo para POST /api/orders/ssl e depois emite o certificado a partir de um CSR:

{
  "Parameters": {
    "Format": 2,
    "DnsNames": [
      "www.example.com"
    ],
    "SubjectName": {
      "Organization": "Lacuna Software Demo",
      "CommonName": "www.example.com",
      "OrganizationalUnits": [
        "Lab"
      ]
    },
    "KeyUsages": [
      3,
      7
    ],
    "ExtendedKeyUsages": [
      1
    ]
  },
  "CAId": "00000000-0000-0000-0000-000000000000",
  "Kind": 1,
  "Validity": "90.00:00:00",
  "IssuePendingApproval": false
}

A demo verifica os nomes DNS antes de chamar o Amplia (de 1 a 10 nomes, em minúsculas, * só como o rótulo inteiro mais à esquerda, sem endereços IP) e traduz os códigos de erro BadDnsName e BadCsr do Amplia em mensagens próprias. Esses limites são da demo: o próprio Amplia aceita endereços IP. O SslCertificateParameters dos clientes Node.js e PHP só define dnsNames.

Ler, alterar e excluir pedidos

Operação	Endpoint
Ler um pedido	GET /api/orders/{id}; GET /api/v2/orders/{id} também devolve o parameters dele
Ler um pedido com os parâmetros do formato	GET /api/orders/{format}/{id}, por exemplo GET /api/orders/pki-brazil/{id}
Alterar um pedido	PUT /api/orders/{format}/{id}
Excluir um pedido	DELETE /api/orders/{id}
Listar pedidos	GET /api/orders, com Q, Limit, Offset, Cursor e Order (Asc, Desc)

• O status de um pedido é Pending, Locked ou Issued, e canEdit e canDelete dizem se ele ainda pode ser alterado ou excluído; um pedido já emitido não pode ser excluído.
• keyMediaConstraints lista as mídias da chave em que o pedido pode ser emitido.
• Pedidos bloqueados podem ser vistos e desbloqueados no dashboard, e a API tem PUT /api/orders/{id}/unlock-request. TODO(docs): o que bloqueia um pedido e o que a requisição de desbloqueio faz.

Próximos passos

• Emitir na máquina do titular
• Emitir a partir de um CSR
• Emitir um arquivo PKCS #12
• Certificados de atributo