Pular para o conteúdo principal

Create certificate orders

Every certificate that Amplia issues starts with an order: it names the CA that issues the certificate and holds the certificate's validity and the holder's data. An order yields one certificate: once it is issued, the order's status is Issued and its certificateId points at the certificate. See Before you start for the API key, the endpoint and the CA id.

Endpoints by certificate format​

Each certificate format has its own endpoint, POST /api/orders/{format}, whose body takes the common fields below plus a parameters object of that format:

FormatEndpointparameters
ICP-Brasil (e-CPF, e-CNPJ)POST /api/orders/pki-brazilPkiBrazilCertificateParameters
SSL/TLSPOST /api/orders/sslSslCertificateParameters
Brazilian student ID card (CIE), an attribute certificatePOST /api/orders/cieCieCertificateParameters
PrivateID, an attribute certificatePOST /api/orders/private-idPrivateIDCertificateParameters
ParaguayPOST /api/orders/pki-paraguayPkiParaguayCertificateParameters
EcuadorPOST /api/orders/bceEcuadorBceCertificateParameters
Cabo VerdePOST /api/orders/pki-cabo-verdePkiCaboVerdeCertificateParameters
Custom profilePOST /api/orders/customCustomCertificateParameters

The API also has POST /api/orders/latinus and POST /api/orders/br-laboral, and a generic POST /api/v2/orders whose parameters can be of any format. TODO(docs): what the Latinus and BRLaboral formats are for.

The client libraries choose the endpoint from the class of the parameters object. All four create ICP-Brasil, SSL/TLS and CIE orders; the Node.js client also creates Paraguay orders, and the Java client Latinus orders. They also send CNB and ARISP orders (and the Java and PHP clients CNB CA orders) to api/orders/cnb, api/orders/arisp and api/orders/cnb-ca, which the OpenAPI description doesn't list. Amplia 5.0.1 serves these three endpoints, with CnbCertificateParameters, CnbCACertificateParameters and ArispCertificateParameters. TODO(docs): the parameters of CNB, CNB CA and ARISP orders (see Colégio Notarial do Brasil - ASN.1 types and ARISP - ASN.1 types for those certificates).

Common fields​

FieldMeaning
caIdId of the CA that issues the certificate.
templateIdId of the template (certificate profile) to apply.
kindPublicKey or Attribute.
parametersThe holder's data, in the format of the endpoint. Required.
validityEnd, validityStartDates the certificate is valid until and from.
validityValidity as a time span: the recorded demo calls send "365.00:00:00" for a year and "90.00:00:00" for 90 days.
digestAlgorithmSHA1, SHA256, SHA384 or SHA512.
serialNumberA predefined serial number for the certificate.
policyOid, policyStatementUrl, policyUserNotices, policiesCertificate policies to include.
issuePendingApprovalBoolean; the recorded demo calls send false.
  • The Node.js and Python samples send validityEnd as a date in the MM-DD-YYYY pattern, two years from the current date.
  • An order with no validity, on a template that has no default validity, is rejected.
  • The client libraries send only caId, templateId, kind, parameters, validityEnd and a field for copying from a certificate; to set the other fields, call the API directly. The Java client formats validityEnd as MM-dd-yyyy.
  • TODO(docs): what issuePendingApproval and copyFromCertificate do, and how a certificate pending approval is approved (POST /api/certificates/{id}/approval).

ICP-Brasil certificates (e-CPF and e-CNPJ)​

PkiBrazilCertificateParameters requires name and cpf. The other fields include emailAddress, birthDate, phoneNumber, cnpj and companyName for an e-CNPJ, the RG and OAB numbers, nis, cei, organization, organizationalUnits and country.

  • phoneNumber is needed when the holder issues the certificate on Amplia's issue page, which texts them a confirmation code.
  • Amplia takes the certificate's subject from these parameters, never from a CSR: put the identity here, with the CPF and CNPJ without their masks and names without diacritics.
  • normalizeCommonName and appendIdentifierToCommonName normalize the Common Name (CN=) and add the CPF or CNPJ to it.
  • In the recorded demo calls, an order with a CPF comes back with certificateType e-CPF, and one that also has cnpj and companyName comes back as e-CNPJ.
  • The Node.js, PHP and Python clients send the organizational units as organizationUnits, while the API's field is organizationalUnits; the Java client uses the API's name.

The samples create an e-CPF order with the name and CPF only: 

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);

Over HTTP, the e-CPF demo sends this body to POST /api/orders/pki-brazil (personal data masked). Its client serializes enums as numbers ("Format": 1, "Kind": 1), while the response names them ("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
}

SSL/TLS certificates​

SslCertificateParameters holds dnsNames, subjectName, keyUsages, extendedKeyUsages, qualifiedStatements and organizationIdentifier. Amplia's SSL/TLS certificates follow the CA/Browser Forum guidelines and accept wildcard names and IP addresses besides regular DNS names.

The DNS names and the subject come from the order, never from the CSR: the SSL/TLS demo sets the DNS names, the subject, the key usages DigitalSignature and KeyEncipherment and the extended key usage ServerAuth explicitly. It sends this body to POST /api/orders/ssl, then issues the certificate from a 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
}

The demo checks the DNS names before calling Amplia (1 to 10 names, lowercased, * only as the whole leftmost label, no IP addresses), and maps Amplia's BadDnsName and BadCsr error codes to messages of its own. These are the demo's own limits: Amplia itself accepts IP addresses. The Node.js and PHP clients' SslCertificateParameters only set dnsNames.

Read, update and delete orders​

OperationEndpoint
Read an orderGET /api/orders/{id}; GET /api/v2/orders/{id} also returns its parameters
Read an order with its format's parametersGET /api/orders/{format}/{id}, for example GET /api/orders/pki-brazil/{id}
Update an orderPUT /api/orders/{format}/{id}
Delete an orderDELETE /api/orders/{id}
List ordersGET /api/orders, with Q, Limit, Offset, Cursor and Order (Asc, Desc)
  • An order's status is Pending, Locked or Issued, and canEdit and canDelete tell whether it can still be changed or deleted; an issued order cannot be deleted.
  • keyMediaConstraints lists the key media the order can be issued on.
  • Blocked orders can be viewed and unlocked on the dashboard, and PUT /api/orders/{id}/unlock-request exists in the API. TODO(docs): what locks an order and what the unlock request does.

Next steps​

View as Markdown