API do GeCert
A API REST do GeCert é a mesma que a aplicação web e o Gecert Connect usam. A descrição completa das
rotas e dos modelos está no Swagger da sua instância, em https://endereco-do-seu-gecert/swagger.
Autenticação
As requisições levam o header Authorization: Bearer SEU_TOKEN, com um token de acesso emitido pelo GrantID da
instância para a API do GeCert (a configuração Oidc:ApiName do servidor). É o mesmo token que a aplicação web obtém ao entrar e que o
Gecert Connect obtém no login. As rotas da área da organização operam na organização a que o usuário pertence, como a aplicação web.
Só as rotas de configuração do aplicativo são anônimas:
| Rota | Resposta |
|---|---|
GET /api/app-configuration | {"hidePoweredBy": false} |
GET /api/app-configuration/gecert-connect | A versão mínima do Gecert Connect e se o servidor está em manutenção: {"minSupportedVersion": "1.1.0.0", "underMaintenance": false} |
GET /api/app-configuration/gecert-connect/server | O endereço do servidor e os dados do GrantID para o Gecert Connect: serverUrl, grantIdAuthority, grantIdClientAppId, grantIdApiName, grantIdRedirectUri. Erro GecertConnectServerNotConfigured se a seção GecertConnect não estiver preenchida |
GET /api/system/info | O nome e a versão do produto: {"productName":"Gecert","productVersion":"1.x.x"} |
Rotas
As listas (.../list) são paginadas e aceitam os parâmetros q (busca), offset, limit e order. A permissão de cada rota é
verificada na organização do recurso; na área Sys Admin, na raiz.
Chaves
| Rota | O que faz | Permissão |
|---|---|---|
GET /api/keys/list | Lista as chaves da organização | ViewKeys |
GET /api/keys/available/list | Lista as chaves que ainda não têm certificado | ViewKeys |
GET /api/keys/{id}/summary | Resumo da chave: nome, organização, certificado e tipo do repositório | ViewKeys |
GET /api/keys/{id}/details | Detalhes: tipo, tamanho e tipo do repositório. Responde com a falha CannotRetrieveKeyFromKeyStore quando a chave não é encontrada no repositório | ViewKeys |
GET /api/keys/{id}/csr | A CSR guardada para a chave, em PEM, com o nome do titular e o algoritmo de hash | ViewKeys |
POST /api/keys/{id}/custom-csr | Emite uma nova CSR para a chave. Corpo: {"params": "CN=...,O=...", "hashAlgorithm": "SHA256"} | ManageKeys |
GET /api/keys/{id}/parameters | Os parâmetros da chave no repositório, em JSON. Erro KeyStoreParametersNotAccessible se o repositório não permite registro de chaves | ViewKeys |
GET /api/keys/{id}/parameters/accessible | Se os parâmetros podem ser lidos (true ou false) | ViewKeys |
GET /api/keys/{id}/events | Eventos da chave, paginados | ViewKeys |
PUT /api/keys | Registra uma chave que já existe no repositório. Corpo: {"parameters": {"keyStore": "...", "keyName": "...", "keyStoreParameters": {...}}} (veja abaixo) | ManageKeys |
PUT /api/keys/{id} | Renomeia a chave. Corpo: {"name": "..."} | ManageKeys |
DELETE /api/keys/{id} | Exclui a chave (e a apaga do repositório quando a exclusão definitiva está configurada). Erro GecertKeyHasActiveCertificate se ela tem certificado | ManageKeys |
Certificados
| Rota | O que faz | Permissão |
|---|---|---|
GET /api/certificates/list | Lista os certificados da organização, com o número de usuários autorizados | ViewCertificates |
GET /api/certificates/{id} | Detalhes: titular, emissor, tipo, e-mail, validade, thumbprint SHA-1 e o ID da chave | ViewCertificates |
GET /api/certificates/{id}/events | Eventos do certificado, paginados | ViewCertificates |
GET /api/certificates/{id}/usage | Usos da chave do certificado, paginados | ViewCertificates |
GET /api/certificates/{id}/authorized-users | Os usuários com acesso ao certificado, paginados | ViewCertificateAccess |
GET /api/certificates/{id}/public-bytes | O certificado codificado (DER), em Base64 | Acesso ao certificado (UseKey) |
GET /api/certificates/my | Os certificados a que o usuário autenticado tem acesso | Usuário autenticado |
POST /api/certificates | Adiciona um certificado a partir de um PKCS #12 enviado antes como upload. Corpo: {"blobId": "...", "keyStoreName": "...", "password": "..."}. Falhas: CertificatePasswordIsIncorrect, CertificateAlreadyExistsOnSubscription, CertificateIsExpectedToHaveRsaKeys | ManageCertificates |
PUT /api/certificates | Registra um certificado (.cer) para uma chave existente. Corpo: {"blobId": "...", "keyId": "..."}. Falhas: CertificateIsNotExpectedToHavePassword, CertificateAlreadyExistsOnSubscription, KeysAreNotEquivalent | ManageCertificates |
DELETE /api/certificates/{id} | Exclui o certificado, os acessos a ele e a chave | ManageCertificates |
As respostas de POST e PUT /api/certificates seguem o formato {"success": true, "id": "..."} ou
{"success": false, "failure": "CertificatePasswordIsIncorrect", "failureType": "NewCertificateResponseFailures"}.
Acessos a certificados
| Rota | O que faz | Permissão |
|---|---|---|
GET /api/certificate-access | Lista os acessos da organização, paginados | ViewCertificateAccess |
POST /api/certificate-access | Concede acesso. Corpo: {"certificateId": "...", "userId": "..."}. Falhas: CertificateAccessAlreadyExists, UserNeedsSubscriptionAccess, UserHasAccessToThisCertificateInAnotherSubscription | ManageCertificateAccess |
DELETE /api/certificate-access/{id} | Remove um acesso | ManageCertificateAccess |
DELETE /api/certificate-access/certificates/{certificateId} | Remove todos os acessos de um certificado | ManageCertificateAccess |
DELETE /api/certificate-access/users/{userId} | Remove todos os acessos de um usuário na organização | ManageCertificateAccess |
POST /api/certificate-access/certificates/{de}/to/{para} | Copia todos os acessos de um certificado para outro. A resposta traz uma lista com o resultado de cada usuário | ManageCertificateAccess nos dois certificados |
GET /api/users/{userId}/authorized-certificates | Os certificados a que um usuário tem acesso | ViewCertificateAccess |
GET /api/users/{userId}/subscription-access/verification | Se o usuário tem acesso à organização (true ou false) | ViewCertificateAccess |
Repositórios de chaves
| Rota | O que faz | Permissão |
|---|---|---|
GET /api/key-stores | Os repositórios a que a organização tem acesso: nome, tipo, se é o padrão, se aceita registro e inserção de chaves, exclusão definitiva, tamanhos de chave e padrão do nome | ManageKeys |
GET /api/key-stores/{type}/example | Um exemplo dos parâmetros de registro para o tipo (Kryptus, AzureKeyVault ou Pkcs11) | ManageKeys |
GET /api/key-stores/list | Todos os repositórios configurados na instância, paginados | Read na raiz (Sys Admin) |
GET /api/key-stores/details?name=... | Os detalhes de um repositório, conforme o tipo: no Azure Key Vault, o endpoint, o ID do aplicativo e se usa HSM; no Kryptus, o host, a porta e os usuários; no PKCS #11, o módulo e o número de série do token | Read na raiz (Sys Admin) |
GET /api/subscriptions/my/key-stores | Os acessos a repositórios da organização | ManageKeys |
GET /api/subscriptions/{id}/key-stores | Os acessos a repositórios de uma organização, paginados | ViewKeyStoreAccess na raiz |
POST /api/key-store-access | Concede a uma organização acesso a um repositório. Corpo: {"subscriptionId": "...", "keyStoreName": "..."}. Falha: KeyStoreAccessAlreadyExists | ManageKeyStoreAccess na raiz |
DELETE /api/key-store-access/{id} | Remove o acesso. As chaves que já estão no repositório continuam funcionando | ManageKeyStoreAccess na raiz |
Usos de chaves
| Rota | O que faz | Permissão |
|---|---|---|
GET /api/key-usages/list | Os usos das chaves da organização, paginados: data, certificado, usuário, operação (Encrypt, Decrypt, Sign ou Verify), algoritmo, hash, valor e, nas verificações, se a assinatura era válida | ViewCertificates |
Relatórios
| Rota | O que faz | Permissão |
|---|---|---|
POST /api/reports/certificates/expiration-date | Gera o relatório de expiração dos certificados da organização (nome, e-mail e data de expiração). Corpo: {"fileType": "Xlsx"}, "Csv" ou "Pdf" | ManageCertificates |
POST /api/reports/certificates/{id}/events | Gera o relatório dos eventos de um certificado (data, entidade, operação, detalhes, agente e organização) | ManageCertificates |
GET /api/reports/{id}?fileType=... | Baixa o relatório gerado | Ticket de acesso devolvido na geração |
A geração responde com {"success": true, "ticket": {"location": "..."}}, e location é o endereço para baixar o arquivo; ou com a falha
EmptyReport, quando não há nada a incluir.
API usada pelo Gecert Connect
Estas rotas, também em /api/keys, são as que o Gecert Connect chama em nome do Lacuna Key
Storage Provider. Elas só enxergam as chaves dos certificados a que o usuário autenticado tem acesso, e cada operação com a chave privada
exige a permissão UseKey e fica registrada nos usos de chaves.
| Rota | O que faz |
|---|---|
GET /api/keys | As chaves do usuário: [{"id": "...", "attributes": {"enabled": true}}] |
GET /api/keys/{id} | A chave pública: {"id": "...", "keyType": "RSA", "keyOperations": ["Encrypt", "Decrypt", "Sign", "Verify", "WrapKey", "UnwrapKey"], "rsaModulus": "...", "rsaPublicExponent": "...", "managed": true}, com o módulo e o expoente em Base64 |
POST /api/keys | Cria uma chave RSA na organização atual. Corpo: {"keyName": "...", "keyStore": "...", "keySize": 2048, "keyType": "RSA"}. Exige ManageKeys |
POST /api/keys/{id}/signature | Assina um hash. Corpo: {"algorithm": "RS256", "value": "HASH_EM_BASE64"}; algorithm pode ser RS256 (padrão) ou RS512. Resposta: a assinatura, em Base64 |
POST /api/keys/{id}/decryption | Decripta. Corpo: {"algorithm": "RSA1_5", "value": "DADO_EM_BASE64"}; RSA1_5 (PKCS #1 v1.5) é o único padding e o padrão. Resposta: o dado decriptado, em Base64 |
POST /api/keys/{id}/encryption | Encripta com a chave pública do certificado. Mesmo corpo e resposta |
POST /api/keys/{id}/signature-verification | Verifica uma assinatura com a chave pública. Corpo: {"algorithm": "RS256", "value": "ASSINATURA_EM_BASE64", "digest": "HASH_EM_BASE64"}. Resposta: true ou false |
GET /api/keys/stopwatch-info, GET /api/keys/{id}/stopwatch-info | As mesmas respostas de GET /api/keys e GET /api/keys/{id}, com os tempos gastos em cada etapa (banco de dados, conexão ao repositório, leitura dos parâmetros), usados por Checar conexão com o servidor |
Um algoritmo diferente dos aceitos responde com o erro OperationAlgorithmNotSupported.
Parâmetros de registro de chaves
Para registrar uma chave que já existe no repositório (PUT /api/keys ou Registrar chave existente), informe os parâmetros que a
identificam, conforme o tipo do repositório. O campo type é obrigatório, e GET /api/key-stores/{type}/example devolve um modelo.
O GeCert testa os parâmetros antes de salvar: lê a chave pública e assina uma CSR com a chave; se falhar, responde com
KeyStoreParametersFailedValidation.
| Repositório | Parâmetros |
|---|---|
| HSM Kryptus | {"type": "Kryptus", "publicKeyUniqueIdentifier": "...", "privateKeyUniqueIdentifier": "..."}: os identificadores únicos KMIP da chave pública e da chave privada |
| Azure Key Vault | {"type": "AzureKeyVault", "keyName": "..."} ou {"type": "AzureKeyVault", "kid": "https://.../keys/nome/versao"}, com os opcionais kty (RSA, RSA-HSM, EC ou EC-HSM) e curveName |
| Dispositivo PKCS #11 | {"type": "Pkcs11", "id": "...", "label": "..."}: o ID da chave (em Base64; na aplicação web, também em hexadecimal) ou o label dela. Pelo menos um dos dois |
O repositório no banco de dados não aceita registro de chaves, e todo repositório pode ter o registro desabilitado na
configuração (KeyRegistrationDisabled): nesse caso, o erro é KeyStoreDoesNotSupportKeyRegistration.
Códigos de erro
Os erros têm o formato {"code": "...", "message": "..."}, com o código HTTP correspondente. Além dos códigos comuns da plataforma
(SubscriptionNotFound, UserNotFound, UploadNotFound, RoleMissing e outros), o GeCert define:
| Código | Quando acontece |
|---|---|
CertificateNotFound, GecertKeyNotFound, CertificateAccessNotFound, KeyStoreAccessNotFound | O recurso não existe ou não é da organização |
SubscriptionMismatch | A chave informada é de outra organização |
BadKeyStore | O repositório informado não está configurado na instância |
BadKeyStoreParameters | Os parâmetros de registro não puderam ser lidos |
KeyStoreParametersFailedValidation | A chave não pôde ser usada com os parâmetros informados |
KeyParametersIncompatibleWithCertificate | A chave não corresponde ao certificado |
KeyStoreDoesNotSupportKeyRegistration | O repositório não aceita registro de chaves existentes |
KeyStoreDoesNotSupportKeyInsertion | O repositório não aceita a geração nem a importação de chaves (KeyInsertionDisabled) |
KeyStoreParametersNotAccessible | Os parâmetros da chave não podem ser exibidos neste repositório |
PinProtectionNotSupported | O repositório não suporta partições |
GecertKeyHasActiveCertificate | A chave não pode ser excluída porque tem um certificado |
OperationAlgorithmNotSupported | O algoritmo da operação não é RS256, RS512 nem RSA1_5 |
GecertConnectServerNotConfigured | A seção GecertConnect do servidor não está preenchida |