Monitorizar e gerir a criação do certificados

Aplica-se a: Azure

Os cenários/operações descritos neste artigo são:

• Pedir um Certificado KV com um emissor suportado
• Obter pedido pendente – o estado do pedido é "inProgress"
• Obter pedido pendente – o estado do pedido está "concluído"
• Obter pedido pendente – o estado do pedido pendente é "cancelado" ou "falhou"
• Obter pedido pendente – o estado do pedido pendente é "eliminado" ou "substituído"
• Criar (ou Importar) quando existe um pedido pendente – o estado é "inProgress"
• Intercalar quando o pedido pendente é criado com um emissor (DigiCert, por exemplo)
• Pedir um cancelamento enquanto o estado do pedido pendente for "inProgress"
• Eliminar um objeto de pedido pendente
• Criar um certificado KV manualmente
• Intercalar quando é criado um pedido pendente – criação manual de certificados

Pedir um Certificado KV com um emissor suportado

Método	URI do pedido
POST	https://mykeyvault.vault.azure.net/certificates/mycert1/create?api-version={api-version}

Os exemplos seguintes requerem que um objeto com o nome "mydigicert" já esteja disponível no cofre de chaves com o fornecedor do emissor como DigiCert. O emissor de certificados é uma entidade representada no Azure Key Vault (KV) como um recurso CertificateIssuer. É utilizado para fornecer informações sobre a origem de um certificado KV; nome do emissor, fornecedor, credenciais e outros detalhes administrativos.

Pedir

{
  "policy": {
    "x509_props": {
      "subject": "CN=MyCertSubject1"
    },
    "issuer": {
      "name": "mydigicert",
      "cty": "OV-SSL",
    }
  }
}

Resposta

StatusCode: 202, ReasonPhrase: 'Accepted'
Location: “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "mydigicert"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": false,
  "status": "InProgress",
  "status_details": "Pending certificate created. Certificate request is in progress. This may take some time based on the issuer provider. Please check again later",
  "request_id": "a76827a18b63421c917da80f28e9913d"
}

Obter pedido pendente – o estado do pedido é "inProgress"

Método	URI do pedido
GET	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

Pedir

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

Nota

Se request_id for especificado na consulta, funciona como um filtro. Se o request_id na consulta e no objeto pendente for diferente, é devolvido um código de estado http de 404.

Resposta

StatusCode: 200, ReasonPhrase: 'OK'
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "{issuer-name}"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": false,
  "status": "inProgress",
  "status_details": "…",
  "request_id": "a76827a18b63421c917da80f28e9913d"
}

Obter pedido pendente – o estado do pedido está "concluído"

Pedir

Método	URI do pedido
GET	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

Resposta

StatusCode: 200, ReasonPhrase: 'OK'
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "{issuer-name}"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": false,
  "status": "completed",
  "request_id": "a76827a18b63421c917da80f28e9913d",
  "target": “https://mykeyvault.vault.azure.net/certificates/mycert1?api-version={api-version}"
}

Obter pedido pendente – o estado do pedido pendente é "cancelado" ou "falhou"

Pedir

Método	URI do pedido
GET	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

Resposta

StatusCode: 200, ReasonPhrase: 'OK'
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "{issuer-name}"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": false,
  "status": "failed",
  "status_details": "",
  "request_id": "a76827a18b63421c917da80f28e9913d",
  "error": {
    "code": "<errorcode>",
    "message": "<message>"
  }
}

Nota

O valor do código de erro pode ser "Erro do emissor de certificados" ou "Pedido rejeitado" com base no emissor ou erro do utilizador, respetivamente.

Obter pedido pendente – o estado do pedido pendente é "eliminado" ou "substituído"

Um objeto pendente pode ser eliminado ou substituído por uma operação de criação/importação quando o respetivo estado não inProgressé .

Método	URI do pedido
GET	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

Pedir

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

GET “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

Resposta

StatusCode: 404, ReasonPhrase: 'Not Found'
{
  "error": {
    "code": "PendingCertificateNotFound",
    "message": "…"
  }
}

Criar (ou Importar) quando existe um pedido pendente – o estado é "inProgress"

Um objeto pendente tem quatro estados possíveis; "inprogress", "canceled", "failed" ou "completed".

Quando o estado de um pedido pendente for "inprogress", as operações de criação (e importação) falharão com um código de estado http de 409 (conflito).

Para corrigir um conflito:

• Se o certificado estiver a ser criado manualmente, pode concluir o certificado KV ao efetuar uma intercalação ou eliminar no objeto pendente.

• Se o certificado estiver a ser criado com um emissor, pode aguardar até que o certificado seja concluído, falhe ou seja cancelado. Em alternativa, pode eliminar o objeto pendente.

Nota

Eliminar um objeto pendente pode ou não cancelar o pedido de certificado x509 com o fornecedor.

Método	URI do pedido
POST	https://mykeyvault.vault.azure.net/certificates/mycert1/create?api-version={api-version}

Pedir

{
  "policy": {
    "x509_props": {
      "subject": "CN=MyCertSubject1"
    },
    "issuer": {
      "name": "mydigicert"
    }
  }
}

Resposta

StatusCode: 409, ReasonPhrase: 'Conflict'
{
  "error": {
    "code": "Forbidden",
    "message": "A new key vault certificate can not be created or imported while a pending key vault certificate's status is inProgress."
  }
}

Intercalar quando o pedido pendente é criado com um emissor

A intercalação não é permitida quando um objeto pendente é criado com um emissor, mas é permitido quando o respetivo estado é inProgress.

Se o pedido de criação do certificado x509 falhar ou cancelar por algum motivo e se um certificado x509 puder ser obtido por meios fora de banda, pode ser efetuada uma operação de intercalação para concluir o certificado KV.

Método	URI do pedido
POST	https://mykeyvault.vault.azure.net/certificates/mycert1/pending/merge?api-version={api-version}

Pedir

{
  "x5c": [ "MIICxTCCAbi………………………trimmed for brevitiy……………………………………………EPAQj8=" ]
}

Resposta

StatusCode: 403, ReasonPhrase: 'Forbidden'
{
  "error": {
    "code": "Forbidden",
    "message": "Merge is forbidden on pending object created with issuer : <issuer-name> while it is in progess."
  }
}

Pedir um cancelamento enquanto o estado do pedido pendente for "inProgress"

Só é possível pedir um cancelamento. Um pedido pode ou não ser cancelado. Se um pedido não for "inProgress", é devolvido um estado http de 400 (Pedido Incorreto).

Método	URI do pedido
PATCH	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

Pedir

PATCH “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

PATCH “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

{
  "cancellation_requested": true
}

Resposta

StatusCode: 200, ReasonPhrase: 'OK'
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "{issuer-name}"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": true,
  "status": "inProgress",
  "status_details": "…",
  "request_id": "a76827a18b63421c917da80f28e9913d"
}

Eliminar um objeto de pedido pendente

Nota

A eliminação do objeto pendente pode ou não cancelar o pedido de certificado x509 junto do fornecedor.

Método	URI do pedido
DELETE	https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}

Pedir

ELIMINAR “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"

OU

ELIMINAR “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}"

Resposta

StatusCode: 200, ReasonPhrase: 'OK'
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "{issuer-name}"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "cancellation_requested": false,
  "status": "inProgress",
  "request_id": "a76827a18b63421c917da80f28e9913d",
}

Criar um certificado KV manualmente

Pode criar um certificado emitido com uma AC à sua escolha através de um processo de criação manual. Defina o nome do emissor como "Desconhecido" ou não especifique o campo emissor.

Método	URI do pedido
POST	https://mykeyvault.vault.azure.net/certificates/mycert1/create?api-version={api-version}

Pedir

{
  "policy": {
    "x509_props": {
      "subject": "CN=MyCertSubject1"
    },
    "issuer": {
      "name": "Unknown"
    }
  }
}

Resposta

StatusCode: 202, ReasonPhrase: 'Accepted'
Location: “https://mykeyvault.vault.azure.net/certificates/mycert1/pending?api-version={api-version}&request_id=a76827a18b63421c917da80f28e9913d"
{
  "id": “https://mykeyvault.vault.azure.net/certificates/mycert1/pending",
  "issuer": {
    "name": "Unknown"
  },
  "csr": "MIICq......DD5Lp5cqXg==",
  "status": "inProgress",
  "status_details": "Pending certificate created. Please Perform Merge to complete the request.",
  "request_id": "a76827a18b63421c917da80f28e9913d"
}

Intercalar quando é criado um pedido pendente – criação manual de certificados

Método	URI do pedido
POST	https://mykeyvault.vault.azure.net/certificates/mycert1/pending/merge?api-version={api-version}

Pedir

{
  "x5c": [ "MIICxTCCAbi………………………trimmed for brevitiy……………………………………………EPAQj8=" ]
}

Nome do elemento	Necessário	Tipo	Versão	Descrição
x5c	Yes	matriz	<apresentação da versão>	Cadeia de certificados X509 como matriz de cadeia de carateres base 64.

Resposta

StatusCode: 201, ReasonPhrase: 'Created'
Location: “https://mykeyvault.vault.azure.net/certificates/mycert1?api-version={api-version}"
{
	"id": "https mykeyvault.vault.azure.net/certificates/mycert1/f366e1a9dd774288ad84a45a5f620352",
	"kid": "https:// mykeyvault.vault.azure.net/keys/mycert1/f366e1a9dd774288ad84a45a5f620352",
	"sid": " mykeyvault.vault.azure.net/secrets/mycert1/f366e1a9dd774288ad84a45a5f620352",
	"cer": "……de34534……",
	"x5t": "n14q2wbvyXr71Pcb58NivuiwJKk",
	"attributes": {
		"enabled": true,
		"exp": 1530394215,
		"nbf": 1435699215,
		"created": 1435699919,
		"updated": 1435699919
	},
	"pending": {
		"id": "https:// mykeyvault.vault.azure.net/certificates/mycert1/pending"
	},
	"policy": {
		"id": "https:// mykeyvault.vault.azure.net/certificates/mycert1/policy",
		"key_props": {
			"exportable": false,
			"kty": "RSA",
			"key_size": 2048,
			"reuse_key": false
		},
		"secret_props": {
			"contentType": "application/x-pkcs12"
		},
		"x509_props": {
			"subject": "CN=Mycert1",
			"ekus": ["1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2"],
			"validity_months": 12
		},
		"lifetime_actions": [{
			"trigger": {
				"lifetime_percentage": 80
			},
			"action": {
				"action_type": "EmailContacts"
			}
		}],
		"issuer": {
			"name": "Unknown"
		},
		"attributes": {
			"enabled": true,
			"created": 1435699811,
			"updated": 1435699811
		}
	}
}