Skip to content

Commit e2f2307

Browse files
megvanhuygenmegvanhuygen
authored
Merge pull request #111796 from msmbaldwin/akv-restore-about
Restored about keys secrets certs article
2 parents 4cdf9fc + dc2ddc7 commit e2f2307

File tree

8 files changed

+131
-174
lines changed

8 files changed

+131
-174
lines changed

‎.openpublishing.redirection.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3639,7 +3639,7 @@
36393639
},
36403640
{
36413641
"source_path": "articles/key-vault/about-keys-secrets-and-certificates.md",
3642-
"redirect_url": "/azure/key-vault",
3642+
"redirect_url": "/azure/key-vault/general/about-keys-secrets-certificates",
36433643
"redirect_document_id": false
36443644
},
36453645
{

‎articles/key-vault/certificates/about-certificates.md

Lines changed: 16 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -15,49 +15,6 @@ ms.author: mbaldwin
1515

1616
# About Azure Key Vault certificates
1717

18-
Azure Key Vault enables Microsoft Azure applications and users to store and use certificates, which are built on top of keys and secrets and add an automated renewal feature.
19-
20-
For more general information about Key Vault, see [What is Azure Key Vault?](/azure/key-vault/key-vault-overview)
21-
22-
## Azure Key Vault
23-
24-
The following sections offer general information applicable across the implementation of the Key Vault service.
25-
26-
### Supporting standards
27-
28-
The JavaScript Object Notation (JSON) and JavaScript Object Signing and Encryption (JOSE) specifications are important background information.
29-
30-
- [JSON Web Key (JWK)](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41)
31-
- [JSON Web Encryption (JWE)](https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-40)
32-
- [JSON Web Algorithms (JWA)](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40)
33-
- [JSON Web Signature (JWS)](https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-41)
34-
35-
### Objects, identifiers, and versioning
36-
37-
Objects stored in Key Vault are versioned whenever a new instance of an object is created. Each version is assigned a unique identifier and URL. When an object is first created, it's given a unique version identifier and marked as the current version of the object. Creation of a new instance with the same object name gives the new object a unique version identifier, causing it to become the current version.
38-
39-
Objects in Key Vault can be addressed using the current identifier or a version-specific identifier. For example, given a Key with the name `MasterKey`, performing operations with the current identifier causes the system to use the latest available version. Performing operations with the version-specific identifier causes the system to use that specific version of the object.
40-
41-
Objects are uniquely identified within Key Vault using a URL. No two objects in the system have the same URL, regardless of geo-location. The complete URL to an object is called the Object Identifier. The URL consists of a prefix that identifies the Key Vault, object type, user provided Object Name, and an Object Version. The Object Name is case-insensitive and immutable. Identifiers that don't include the Object Version are referred to as Base Identifiers.
42-
43-
For more information, see [Authentication, requests, and responses](../general/authentication-requests-and-responses.md)
44-
45-
An object identifier has the following general format:
46-
47-
`https://{keyvault-name}.vault.azure.net/{object-type}/{object-name}/{object-version}`
48-
49-
Where:
50-
51-
|||
52-
|-|-|
53-
|`keyvault-name`|The name for a key vault in the Microsoft Azure Key Vault service.<br /><br /> Key Vault names are selected by the user and are globally unique.<br /><br /> Key Vault name must be a 3-24 character string, containing only 0-9, a-z, A-Z, and -.|
54-
|`object-type`|The type of the object, either "keys" or "secrets".|
55-
|`object-name`|An `object-name` is a user provided name for and must be unique within a Key Vault. The name must be a 1-127 character string, containing only 0-9, a-z, A-Z, and -.|
56-
|`object-version`|An `object-version` is a system-generated, 32 character string identifier that is optionally used to address a unique version of an object.|
57-
58-
59-
## Key Vault Certificates
60-
6118
Key Vault certificates support provides for management of your x509 certificates and the following behaviors:
6219

6320
- Allows a certificate owner to create a certificate through a Key Vault creation process or through the import of an existing certificate. Includes both self-signed and Certificate Authority generated certificates.
@@ -69,27 +26,27 @@ Key Vault certificates support provides for management of your x509 certificates
6926
>[!Note]
7027
>Non-partnered providers/authorities are also allowed but, will not support the auto renewal feature.
7128
72-
### Composition of a Certificate
29+
## Composition of a Certificate
7330

7431
When a Key Vault certificate is created, an addressable key and secret are also created with the same name. The Key Vault key allows key operations and the Key Vault secret allows retrieval of the certificate value as a secret. A Key Vault certificate also contains public x509 certificate metadata.
7532

7633
The identifier and version of certificates is similar to that of keys and secrets. A specific version of an addressable key and secret created with the Key Vault certificate version is available in the Key Vault certificate response.
7734

7835
![Certificates are complex objects](../media/azure-key-vault.png)
7936

80-
### Exportable or Non-exportable key
37+
## Exportable or Non-exportable key
8138

8239
When a Key Vault certificate is created, it can be retrieved from the addressable secret with the private key in either PFX or PEM format. The policy used to create the certificate must indicate that the key is exportable. If the policy indicates non-exportable, then the private key isn't a part of the value when retrieved as a secret.
8340

8441
The addressable key becomes more relevant with non-exportable KV certificates. The addressable KV key's operations are mapped from *keyusage* field of the KV certificate policy used to create the KV Certificate.
8542

8643
Two types of key are supported – *RSA* or *RSA HSM* with certificates. Exportable is only allowed with RSA, not supported by RSA HSM.
8744

88-
### Certificate Attributes and Tags
45+
## Certificate Attributes and Tags
8946

9047
In addition to certificate metadata, an addressable key and addressable secret, a Key Vault certificate also contains attributes and tags.
9148

92-
#### Attributes
49+
### Attributes
9350

9451
The certificate attributes are mirrored to attributes of the addressable key and secret created when KV certificate is created.
9552

@@ -107,14 +64,14 @@ There are additional read-only attributes that are included in response:
10764
> [!Note]
10865
> If a Key Vault certificate expires, it's addressable key and secret become inoperable.
10966
110-
#### Tags
67+
### Tags
11168

11269
Client specified dictionary of key value pairs, similar to tags in keys and secrets.
11370

11471
> [!Note]
11572
> Tags are readable by a caller if they have the *list* or *get* permission to that object type (keys, secrets, or certificates).
11673
117-
### Certificate policy
74+
## Certificate policy
11875

11976
A certificate policy contains information on how to create and manage lifecycle of a Key Vault certificate. When a certificate with private key is imported into the key vault, a default policy is created by reading the x509 certificate.
12077

@@ -134,7 +91,7 @@ At a high level, a certificate policy contains the following information:
13491
- Issuer: Parameters about the certificate issuer to use to issue x509 certificates.
13592
- Policy Attributes: contains attributes associated with the policy
13693

137-
#### X509 to Key Vault usage mapping
94+
### X509 to Key Vault usage mapping
13895

13996
The following table represents the mapping of x509 key usage policy to effective key operations of a key created as part of a Key Vault certificate creation.
14097

@@ -149,7 +106,7 @@ The following table represents the mapping of x509 key usage policy to effective
149106
|NonRepudiation|sign, verify| N/A |
150107
|crlsign|sign, verify| N/A |
151108

152-
### Certificate Issuer
109+
## Certificate Issuer
153110

154111
A Key Vault certificate object holds a configuration used to communicate with a selected certificate issuer provider to order x509 certificates.
155112

@@ -176,7 +133,7 @@ Key Vault allows for creation of multiple issuer objects with different issuer p
176133

177134
Issuer objects are created in the vault and can only be used with KV certificates in the same vault.
178135

179-
### Certificate contacts
136+
## Certificate contacts
180137

181138
Certificate contacts contain contact information to send notifications triggered by certificate lifetime events. The contacts information is shared by all the certificates in the key vault. A notification is sent to all the specified contacts for an event for any certificate in the key vault.
182139

@@ -187,7 +144,7 @@ If a certificate's policy is set to auto renewal, then a notification is sent on
187144

188145
When a certificate policy that is set to be manually renewed (email only), a notification is sent when it's time to renew the certificate.
189146

190-
### Certificate Access Control
147+
## Certificate Access Control
191148

192149
Access control for certificates is managed by Key Vault, and is provided by the Key Vault that contains those certificates. The access control policy for certificates is distinct from the access control policies for keys and secrets in the same Key Vault. Users may create one or more vaults to hold certificates, to maintain scenario appropriate segmentation and management of certificates.
193150

@@ -215,7 +172,11 @@ If a certificate's policy is set to auto renewal, then a notification is sent on
215172

216173
For more information, see the [Certificate operations in the Key Vault REST API reference](/rest/api/keyvault). For information on establishing permissions, see [Vaults - Create or Update](/rest/api/keyvault/vaults/createorupdate) and [Vaults - Update Access Policy](/rest/api/keyvault/vaults/updateaccesspolicy).
217174

218-
## See Also
175+
## Next steps
219176

177+
- [About Key Vault](../general/overview.md)
178+
- [About keys, secrets, and certificates](../general/about-keys-secrets-certificates.md)
179+
- [About keys](../keys/about-keys.md)
180+
- [About secrets](../secrets/about-secrets.md)
220181
- [Authentication, requests, and responses](../general/authentication-requests-and-responses.md)
221-
- [Key Vault Developer's Guide](../general/developers-guide.md)
182+
- [Key Vault Developer's Guide](../general/developers-guide.md)

‎articles/key-vault/general/about-keys-secrets-certificates.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: About Azure Key Vault keys, secrets and certificates - Azure Key Vault
3+
description: Overview of Azure Key Vault REST interface and developer details for keys, secrets and certificates.
4+
services: key-vault
5+
author: msmbaldwin
6+
manager: rkarlin
7+
tags: azure-resource-manager
8+
9+
ms.service: key-vault
10+
ms.topic: overview
11+
ms.date: 04/17/2020
12+
ms.author: mbaldwin
13+
---
14+
15+
# About keys, secrets, and certificates
16+
17+
Azure Key Vault enables Microsoft Azure applications and users to store and use several types of secret/key data:
18+
19+
- Cryptographic keys: Supports multiple key types and algorithms, and enables the use of Hardware Security Modules (HSM) for high value keys. For more information, see [About keys](../keys/about-keys.md).
20+
- Secrets: Provides secure storage of secrets, such as passwords and database connection strings. For more information, see [About secrets](../secrets/about-secrets.md).
21+
- Certificates: Supports certificates, which are built on top of keys and secrets and add an automated renewal feature. For more information, see [About certificates](../certificates/about-certificates.md).
22+
- Azure Storage: Can manage keys of an Azure Storage account for you. Internally, Key Vault can list (sync) keys with an Azure Storage Account, and regenerate (rotate) the keys periodically. For more information, see [Manage storage account keys with Key Vault](../secrets/overview-storage-keys.md).
23+
24+
For more general information about Key Vault, see [About Azure Key Vault](overview.md).
25+
26+
## Data types
27+
28+
Refer to the JOSE specifications for relevant data types for keys, encryption, and signing.
29+
30+
- **algorithm** - a supported algorithm for a key operation, for example, RSA1_5
31+
- **ciphertext-value** - cipher text octets, encoded using Base64URL
32+
- **digest-value** - the output of a hash algorithm, encoded using Base64URL
33+
- **key-type** - one of the supported key types, for example RSA (Rivest-Shamir-Adleman).
34+
- **plaintext-value** - plaintext octets, encoded using Base64URL
35+
- **signature-value** - output of a signature algorithm, encoded using Base64URL
36+
- **base64URL** - a Base64URL [RFC4648] encoded binary value
37+
- **boolean** - either true or false
38+
- **Identity** - an identity from Azure Active Directory (AAD).
39+
- **IntDate** - a JSON decimal value representing the number of seconds from 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC3339 for details regarding date/times, in general and UTC in particular.
40+
41+
## Objects, identifiers, and versioning
42+
43+
Objects stored in Key Vault are versioned whenever a new instance of an object is created. Each version is assigned a unique identifier and URL. When an object is first created, it's given a unique version identifier and marked as the current version of the object. Creation of a new instance with the same object name gives the new object a unique version identifier, causing it to become the current version.
44+
45+
Objects in Key Vault can be addressed using the current identifier or a version-specific identifier. For example, given a Key with the name `MasterKey`, performing operations with the current identifier causes the system to use the latest available version. Performing operations with the version-specific identifier causes the system to use that specific version of the object.
46+
47+
Objects are uniquely identified within Key Vault using a URL. No two objects in the system have the same URL, regardless of geo-location. The complete URL to an object is called the Object Identifier. The URL consists of a prefix that identifies the Key Vault, object type, user provided Object Name, and an Object Version. The Object Name is case-insensitive and immutable. Identifiers that don't include the Object Version are referred to as Base Identifiers.
48+
49+
For more information, see [Authentication, requests, and responses](authentication-requests-and-responses.md)
50+
51+
An object identifier has the following general format:
52+
53+
`https://{keyvault-name}.vault.azure.net/{object-type}/{object-name}/{object-version}`
54+
55+
Where:
56+
57+
|||
58+
|-|-|
59+
|`keyvault-name`|The name for a key vault in the Microsoft Azure Key Vault service.<br /><br /> Key Vault names are selected by the user and are globally unique.<br /><br /> Key Vault name must be a 3-24 character string, containing only 0-9, a-z, A-Z, and -.|
60+
|`object-type`|The type of the object, "keys", "secrets", or 'certificates'.|
61+
|`object-name`|An `object-name` is a user provided name for and must be unique within a Key Vault. The name must be a 1-127 character string, containing only 0-9, a-z, A-Z, and -.|
62+
|`object-version`|An `object-version` is a system-generated, 32 character string identifier that is optionally used to address a unique version of an object.|
63+
64+
## Next steps
65+
66+
- [About keys](../keys/about-keys.md)
67+
- [About secrets](../secrets/about-secrets.md)
68+
- [About certificates](../certificates/about-certificates.md)
69+
- [Authentication, requests, and responses](../general/authentication-requests-and-responses.md)
70+
- [Key Vault Developer's Guide](../general/developers-guide.md)

‎articles/key-vault/general/overview.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.author: mbaldwin
1515
#Customer intent: As an IT Pro, Decision maker or developer I am trying to learn what Key Vault is and if it offers anything that could be used in my organization.
1616

1717
---
18-
# What is Azure Key Vault?
18+
# About Azure Key Vault
1919

2020
Azure Key Vault helps solve the following problems:
2121

@@ -77,4 +77,7 @@ Key Vault itself can integrate with storage accounts, event hubs, and log analyt
7777

7878
## Next steps
7979

80+
- Learn more about [keys, secrets, and certificates](about-keys-secrets-certificates.md)
8081
- [Quickstart: Create an Azure Key Vault using the CLI](../secrets/quick-create-cli.md)
82+
- [Authentication, requests, and responses](../general/authentication-requests-and-responses.md)
83+
- [Key Vault Developer's Guide](../general/developers-guide.md)

‎articles/key-vault/general/toc.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@
22
href: index.yml
33
- name: Overview
44
items:
5-
- name: What is Azure Key Vault?
5+
- name: About Azure Key Vault
66
href: overview.md
7+
- name: About keys, secrets, and certificates
8+
href: about-keys-secrets-certificates.md
79

810
- name: Tutorials
911
items:

0 commit comments

Comments
 (0)