ALTER CERTIFICATE (Transact-SQL)

Artikel
11/19/2024

Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Analytics Platform System (PDW) SQL database in Microsoft Fabric

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 Service Broker.

Transact-SQL syntax conventions

Syntax

-- Syntax for SQL Server and Azure SQL Database  
  
ALTER CERTIFICATE certificate_name   
      REMOVE PRIVATE KEY  
    | WITH PRIVATE KEY ( <private_key_spec> )  
    | WITH ACTIVE FOR BEGIN_DIALOG = { ON | OFF }  
  
<private_key_spec> ::=   
      {   
        { FILE = 'path_to_private_key' | BINARY = private_key_bits }  
         [ , DECRYPTION BY PASSWORD = 'current_password' ]  
         [ , ENCRYPTION BY PASSWORD = 'new_password' ]  
      }  
    |  
      {  
         [ DECRYPTION BY PASSWORD = 'current_password' ]  
         [ [ , ] ENCRYPTION BY PASSWORD = 'new_password' ]  
      }

-- Syntax for Parallel Data Warehouse  
  
ALTER CERTIFICATE certificate_name   
{  
      REMOVE PRIVATE KEY  
    | WITH PRIVATE KEY (   
        FILE = '<path_to_private_key>',  
        DECRYPTION BY PASSWORD = '<key password>' )
}

Arguments

certificate_name
Is the unique name by which the certificate is known in the database.

REMOVE PRIVATE KEY
Specifies that the private key should no longer be maintained inside the database.

WITH PRIVATE KEY Specifies that the private key of the certificate is loaded into SQL Server.

FILE ='path_to_private_key'
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 SQL Server service account. When you use this option, make sure the service account has access to the specified file.

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 SQL Server 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.

BINARY ='private_key_bits'
Applies to: SQL Server 2012 (11.x) and later.

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.

DECRYPTION BY PASSWORD ='current_password'
Specifies the password that is required to decrypt the private key.

ENCRYPTION BY PASSWORD ='new_password'
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 SQL Server. For more information, see Password Policy.

ACTIVE FOR BEGIN_DIALOG = { ON | OFF }
Makes the certificate available to the initiator of a Service Broker dialog conversation.

Remarks

The private key must correspond to the public key specified by certificate_name.

The DECRYPTION BY PASSWORD clause can be omitted if the password in the file is protected with a null password.

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.

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 Service Broker 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.

You do not have to specify a decryption password when the private key is encrypted by using the database master key.

To change the password used for encrypting the private key, do not specify either the FILE or BINARY clauses.

Important

Always make an archival copy of a private key before removing it from a database. For more information, see BACKUP CERTIFICATE (Transact-SQL) and CERTPRIVATEKEY (Transact-SQL).

The WITH PRIVATE KEY option is not available in a contained database.

Permissions

Requires ALTER permission on the certificate.

Examples

A. Removing the private key of a certificate

ALTER CERTIFICATE Shipping04   
    REMOVE PRIVATE KEY;  
GO

B. Changing the password that is used to encrypt the private key

ALTER CERTIFICATE Shipping11   
    WITH PRIVATE KEY (DECRYPTION BY PASSWORD = '95hkjdskghFDGGG4%',  
    ENCRYPTION BY PASSWORD = '34958tosdgfkh##38');  
GO

C. Importing a private key for a certificate that is already present in the database

ALTER CERTIFICATE Shipping13   
    WITH PRIVATE KEY (FILE = 'c:\importedkeys\Shipping13',  
    DECRYPTION BY PASSWORD = 'GDFLKl8^^GGG4000%');  
GO

D. Changing the protection of the private key from a password to the database master key

ALTER CERTIFICATE Shipping15   
    WITH PRIVATE KEY (DECRYPTION BY PASSWORD = '95hk000eEnvjkjy#F%');  
GO

Dela via