You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Changes the private key used to encrypt a certificate, or adds one if none is present. Changes the availability of a certificate to [!INCLUDE[ssSB](../../includes/sssb-md.md)].
31
+
Changes the password used to encrypt the private key of a certificate, removes the private key, or imports the private key if none is present. Changes the availability of a certificate to [!INCLUDE[ssSB](../../includes/sssb-md.md)].
32
32
33
33
![Topic link icon](../../database-engine/configure-windows/media/topic-link.gif"Topic link icon")[Transact-SQL Syntax Conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
@@ -62,24 +69,29 @@ ALTER CERTIFICATE certificate_name
62
69
63
70
## Arguments
64
71
*certificate_name*
65
-
Is the unique name by which the certificate is known in database.
72
+
Is the unique name by which the certificate is known in the database.
66
73
67
-
FILE **='**_path\_to\_private\_key_**'**
68
-
Specifies the complete path, including file name, to the private key. This parameter can be a local path or a UNC path to a network location. This file will be accessed within the security context of the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] service account. When you use this option, you must make sure that the service account has access to the specified file.
74
+
REMOVE PRIVATE KEY
75
+
Specifies that the private key should no longer be maintained inside the database.
76
+
77
+
WITH PRIVATE KEY
78
+
Specifies that the private key of the certificate is loaded into SQL Server.
79
+
80
+
FILE ='*path_to_private_key*'
81
+
Specifies the complete path, including file name, to the private key. This parameter can be a local path or a UNC path to a network location. This file will be accessed within the security context of the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] service account. When you use this option, make sure the service account has access to the specified file.
82
+
83
+
If only a file name is specified, the file is saved in the default user data folder for the instance. This folder might (or might not) be the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] DATA folder. For SQL Server Express LocalDB, the default user data folder for the instance is the path specified by the `%USERPROFILE%` environment variable for the account that created the instance.
69
84
70
-
BINARY **='**_private\_key\_bits_**'**
85
+
BINARY ='*private_key_bits*'
71
86
**Applies to**: [!INCLUDE[ssSQL11](../../includes/sssql11-md.md)] through [!INCLUDE[ssCurrent](../../includes/sscurrent-md.md)].
72
87
73
88
Private key bits specified as binary constant. These bits can be in encrypted form. If encrypted, the user must provide a decryption password. Password policy checks are not performed on this password. The private key bits should be in a PVK file format.
74
89
75
-
DECRYPTION BY PASSWORD **='**_key\_password_**'**
90
+
DECRYPTION BY PASSWORD ='*current_password*'
76
91
Specifies the password that is required to decrypt the private key.
77
92
78
-
ENCRYPTION BY PASSWORD **='**_password_**'**
79
-
Specifies the password used to encrypt the private key of the certificate in the database. *password* must meet the Windows password policy requirements of the computer that is running the instance of [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. For more information, see [Password Policy](../../relational-databases/security/password-policy.md).
80
-
81
-
REMOVE PRIVATE KEY
82
-
Specifies that the private key should no longer be maintained inside the database.
93
+
ENCRYPTION BY PASSWORD ='*new_password*'
94
+
Specifies the password used to encrypt the private key of the certificate in the database. *new_password* must meet the Windows password policy requirements of the computer that is running the instance of [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. For more information, see [Password Policy](../../relational-databases/security/password-policy.md).
83
95
84
96
ACTIVE FOR BEGIN_DIALOG **=** { ON | OFF }
85
97
Makes the certificate available to the initiator of a [!INCLUDE[ssSB](../../includes/sssb-md.md)] dialog conversation.
@@ -89,14 +101,16 @@ ALTER CERTIFICATE certificate_name
89
101
90
102
The DECRYPTION BY PASSWORD clause can be omitted if the password in the file is protected with a null password.
91
103
92
-
When the private key of a certificate that already exists in the database is imported from a file, the private key will be automatically protected by the database master key. To protect the private key with a password, use the ENCRYPTION BY PASSWORD phrase.
104
+
When the private key of a certificate that already exists in the database is imported, the private key will be automatically protected by the database master key. To protect the private key with a password, use the ENCRYPTION BY PASSWORD clause.
93
105
94
-
The REMOVE PRIVATE KEY option will delete the private key of the certificate from the database. You can remove the private key when the certificate will be used to verify signatures or in [!INCLUDE[ssSB](../../includes/sssb-md.md)] scenarios that do not require a private key. Do not remove the private key of a certificate that protects a symmetric key.
106
+
The REMOVE PRIVATE KEY option will delete the private key of the certificate from the database. You can remove the private key when the certificate will be used to verify signatures or in [!INCLUDE[ssSB](../../includes/sssb-md.md)] scenarios that do not require a private key. Do not remove the private key of a certificate that protects a symmetric key. The private key will need to be restored in order to sign any additional modules or strings that should be verified with the certificate, or to decrypt a value that has been encrypted with the certificate.
95
107
96
108
You do not have to specify a decryption password when the private key is encrypted by using the database master key.
109
+
110
+
To change the password used for encrypting the private key, do not specify either the FILE or BINARY clauses.
97
111
98
112
> [!IMPORTANT]
99
-
> Always make an archival copy of a private key before removing it from a database. For more information, see [BACKUP CERTIFICATE (Transact-SQL)](../../t-sql/statements/backup-certificate-transact-sql.md).
113
+
> Always make an archival copy of a private key before removing it from a database. For more information, see [BACKUP CERTIFICATE (Transact-SQL)](../../t-sql/statements/backup-certificate-transact-sql.md) and [CERTPRIVATEKEY (Transact-SQL)](../../t-sql/functions/certprivatekey-transact-sql.md).
100
114
101
115
The WITH PRIVATE KEY option is not available in a contained database.
102
116
@@ -105,29 +119,28 @@ ALTER CERTIFICATE certificate_name
105
119
106
120
## Examples
107
121
108
-
### A. Changing the password of a certificate
122
+
### A. Removing the private key of a certificate
109
123
110
124
```
111
125
ALTER CERTIFICATE Shipping04
112
-
WITH PRIVATE KEY (DECRYPTION BY PASSWORD = 'pGF$5DGvbd2439587y',
113
-
ENCRYPTION BY PASSWORD = '4-329578thlkajdshglXCSgf');
126
+
REMOVE PRIVATE KEY;
114
127
GO
115
128
```
116
129
117
130
### B. Changing the password that is used to encrypt the private key
118
131
119
132
```
120
133
ALTER CERTIFICATE Shipping11
121
-
WITH PRIVATE KEY (ENCRYPTION BY PASSWORD = '34958tosdgfkh##38',
122
-
DECRYPTION BY PASSWORD = '95hkjdskghFDGGG4%');
134
+
WITH PRIVATE KEY (DECRYPTION BY PASSWORD = '95hkjdskghFDGGG4%',
135
+
ENCRYPTION BY PASSWORD = '34958tosdgfkh##38');
123
136
GO
124
137
```
125
138
126
139
### C. Importing a private key for a certificate that is already present in the database
127
140
128
141
```
129
142
ALTER CERTIFICATE Shipping13
130
-
WITH PRIVATE KEY (FILE = 'c:\\importedkeys\Shipping13',
143
+
WITH PRIVATE KEY (FILE = 'c:\importedkeys\Shipping13',
> Azure SQL Database does not support creating a certificate from a file or using private key files.
122
122
123
+
BINARY =*asn_encoded_certificate*
124
+
ASN encoded certificate bytes specified as a binary constant.
125
+
**Applies to**: [!INCLUDE[ssSQL11](../../includes/sssql11-md.md)] through [!INCLUDE[ssCurrent](../../includes/sscurrent-md.md)].
126
+
123
127
WITH PRIVATE KEY
124
-
Specifies that the private key of the certificate is loaded into [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. This clause is only valid when the certificate is being created from a file. To load the private key of an assembly, use [ALTER CERTIFICATE](../../t-sql/statements/alter-certificate-transact-sql.md).
128
+
Specifies that the private key of the certificate is loaded into [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. This clause is invalid when the certificate is being created from an assembly. To load the private key of a certificate created from an assembly, use [ALTER CERTIFICATE](../../t-sql/statements/alter-certificate-transact-sql.md).
125
129
126
130
FILE ='*path_to_private_key*'
127
131
Specifies the complete path, including file name, to the private key. *path_to_private_key* can be a local path or a UNC path to a network location. The file is accessed in the security context of the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] service account. This account must have the necessary file-system permissions.
128
132
129
133
> [!IMPORTANT]
130
134
> This option is not available in a contained database or in Azure SQL Database.
131
135
132
-
asn_encoded_certificate
133
-
ASN encoded certificate bits specified as a binary constant.
134
-
135
136
BINARY =*private_key_bits*
136
137
**Applies to**: [!INCLUDE[ssSQL11](../../includes/sssql11-md.md)] through [!INCLUDE[ssCurrent](../../includes/sscurrent-md.md)].
Makes the certificate available to the initiator of a [!INCLUDE[ssSB](../../includes/sssb-md.md)] dialog conversation. The default value is ON.
157
158
158
159
## Remarks
159
-
A certificate is a database-level securable that follows the X.509 standard and supports X.509 V1 fields. CREATE CERTIFICATE can load a certificate from a file or assembly. This statement can also generate a key pair and create a self-signed certificate.
160
+
A certificate is a database-level securable that follows the X.509 standard and supports X.509 V1 fields. CREATE CERTIFICATE can load a certificate from a file, a binary constant, or an assembly. This statement can also generate a key pair and create a self-signed certificate.
160
161
161
162
The Private Key must be \<= 2500 bytes in encrypted format. Private keys generated by [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] are 1024 bits long through [!INCLUDE[ssSQL14](../../includes/sssql14-md.md)] and are 2048 bits long beginning with [!INCLUDE[ssSQL15](../../includes/sssql15-md.md)]. Private keys imported from an external source have a minimum length of 384 bits and a maximum length of 4,096 bits. The length of an imported private key must be an integer multiple of 64 bits. Certificates used for TDE are limited to a private key size of 3456 bits.
162
163
@@ -227,7 +228,10 @@ GO
227
228
```
228
229
> [!IMPORTANT]
229
230
> Azure SQL Database does not support creating a certificate from a file.
230
-
231
+
232
+
> [!IMPORTANT]
233
+
> Starting in [!INCLUDE[ssSQL17](../../includes/sssql17-md.md)], the ['CLR strict security'](../../database-engine/configure-windows/clr-strict-security.md) server configuration option prevents loading assemblies without first setting up the security for them. Load the certificate, create a login from it, grant `UNSAFE ASSEMBLY` to that login, and then load the assembly.
234
+
231
235
### D. Creating a self-signed certificate
232
236
The following example creates a certificate called `Shipping04` without specifying an encryption password. This example can be used with [!INCLUDE[ssPDW](../../includes/sspdw-md.md)].
0 commit comments