alter encryption key

Changes the current password, adds and drops a key copy, regenerates an encryption key.

Syntax

Altering the master key:

alter encryption key [dual] master
	with char_string { add encryption 
		{with passwd char_string for user user_name [for recovery]
		| for automatic_startup	}
	| modify encryption { with passwd char_string [for recovery]
		| for automatic_startup }
	| drop encryption
		{ for user user_name | for recovery | for automatic_startup }
	| regenerate key
		[ with passwd char_string] | recovery encryption
		with passwd char_string | modify owner user_name }

Altering the syb_extpasswdkey service key:

alter encryption key syb_extpasswdkey
	[ with { static key | master key}] 
		{ regenerate key [ with { static key | master key }]
		| modify encryption [ with { static key | master key }] }

Altering the column encryption key:

alter encryption key [[database.][owner].] keyname
	{ [ as | not default ]
	[dual] master
		[ with { static key | master key} ]
		regenerate key
		[ with { static key | master key [no] dual_control} ] | [with passwd 
		'password' | system_encr_passwd | login_passwd  |
			 'base_key_password']
	modify encryption
		[ with {passwd {'password' |  system_encr_passwd | 
				login_passwd } | master key }]
		[[no] dual_control] for automatic startup
	add encryption [ with passwd 'password' | 'key_copy_password’] 
		for user user_name
		[for [login_association | recovery | automatic_startup]]
	drop encryption for { user user_name | recovery 
		[ for recovery ] | [ for automatic_startup ]} 
		| [ with passwd 'password ']
	recover encryption with passwd 'password'
			| modify owner user_name }

Parameters

keyname – is the name for a column encryption key.
as [not] default – indicates that the database default property should be assigned to, or unassigned from, this key.
[dual] master – database level keys used to encrypt other keys within the database in which they are defined. These keys are not used to encrypt data.
static key | master key – The first instance of the with {static key | master key} clause is merely an assertion of how the syb_extpasswdkey is currently encrypted. Because the SAP ASE server knows how syb_extpasswdkey is currently encrypted, this clause is optional.
The second instance of with {static key | master key} clause following the regenerate key action allows the administrator to change the encryption on the regenerated key from static to dynamic, or vice versa. If the clause is omitted, the regenerated key is encrypted as it was prior to this command being issued.

The third instance of with {static key | master key} clause following the modify encryption action changes the protection on the existing key to use the static key or the master key as specified. If the clause is omitted, the static key is used by default.
[no] dual_control – indicates whether dual control is used to create the master key.
regenerate key – indicates you are regenerating the key
with passwd ['password' | system_encr_passwd | login_password 'base_key_password'] – specifies the current password the SAP ASE server uses to decrypt the column encryption key, and a new password for one of the following purposes:
- Modify the encryption of a key or a key copy.
- Encrypt a newly-added key copy. The key owner can add key copies for individual users that are accessible through a private password or a login password.
- Recover the encryption key after losing a password.
The SAP ASE server supports the following passwords for keys:
- password – a character string up to 255 bytes long.
- login_passwd – tells the SAP ASE server to use the session’s login password.
- system_encr_passwd – system encryption password for the current database.
- 'base_key_password' – the password used to encrypt the base key, and may be known only by the key custodian. The password can be upto 255 bytes in length. The SAP ASE server uses the first password to decrypt the base column-encryption key.
If you do not specify with passwd, the default is system_encr_passwd.
modify encryption – indicates you are modifying the encryption key or key copy.
for automatic startup – indicates that the key copy is to be used to access the master or dual master key after the server is restarted with automatic master key access enabled.
add encryption – adds an encrypted key copy for a designated user.
key_copy_password – the password used to encrypt the key copy. The password cannot be longer than 255 bytes. The SAP ASE server makes a copy of the decrypted base key, encrypts it with a key encryption key derived from the key_copy_password, and saves the encrypted base key copy as a new row in sysencryptkeys.
for user user_name – specifies the user for whom you are adding or dropping a key copy.
for login_association – indicates that the key copy being added later becomes encrypted by the assigned user’s login password during his or her first access to this key.
for recovery – indicates that the key copy is to be used to recover the master key in case the password is lost.
drop encryption – indicates that you are dropping the key copy for the specified user.
recover encryption – makes the base key accessible through a new password. Does not apply to key copies.
modify owner – changes the key’s owner to the specified user.

Examples

Example 1 – Changes my_key to the default encryption key:
```
alter encryption key my_key as default
```
You must have the sso_role or keycustodian_role to change the default property of a key. If the command above is executed by:
- The system security officer (SSO), the SAP ASE server removes the default property unconditionally from the previous default key, if one exists.
- The key custodian, he or she must own my_key. The key custodian must own the previous default key, if one exists.
To remove the default property from my_key, the SSO or the key custodian, as owner of the key, executes:
```
alter encryption key my_key as not default
```
If my_key is not the default key, this command returns an error.
Example 2 – Changes the password on the important_key encryption key:
```
alter encryption key important_key 
     with passwd 'oldpassword'
     modify encryption 
     with passwd 'newpassword'
```
If this command is executed by:
- The key owner – the command reencrypts the base key
- The user assigned a key copy – the command reencrypts that key copy.
Example 3 – Changes the password on a key copy to the current session’s login password (can be executed only by a user who has been assigned a key copy):
```
alter encryption key important_key
     modify encryption
     with passwd login_passwd
```
You can encrypt only key copies with a login password. the SAP ASE server returns an error if you attempt to encrypt the base key with a login password.
Example 4 – Changes the password for the important_key encryption key to the system password:
```
alter encryption key important_key
     with passwd 'ReallyBigSecret'
     modify encryption with passwd system_encr_passwd
```
This command can be executed only by the key owner or a user with sso_role, and is allowed only if a key has no key copies. (Base keys with copies must be encrypted by a user-specified password.) This example modifies the encryption of the base key.
Example 5 – Changes the password for the important_key encryption key from the system encryption password to a new password. Because the system encryption password is the default password, it need not be specified in the statement:
```
alter encryption key important_key
     modify encryption
     with passwd 'ReallyNewPassword'
```
Example 6 – Adds encryption for user “ted” for the important_key encryption key with the password “just4now”:
```
alter encryption key important_key
     with passwd 'TopSecret' 
     add encryption with passwd 'just4now'
     for user 'ted'
```
You must be a key owner or a user with the sso_role to execute this command. the SAP ASE server uses “TopSecret” to decrypt the base key, making a copy of the raw key and encrypting it for Ted using the password “just4now.”

Example 7 – Modifies the encryption for Ted to use a new password. Only Ted can execute this command:

alter encryption key important_key
     with passwd 'just4now'
     modify encryption
     with passwd 'TedsOwnPassword'

Example 8 – Drops encryption for user “ted” for the important_key encryption key (you must have the sso_role or be the key owner to execute this command):
```
alter encryption key important_key
     drop encryption for user 'ted'
```
Example 9 – Modifies the owner of important_key to new owner, “tinnap” (you must have the sso_role or be the key owner to execute this command):
```
alter encryption key important_key modify owner tinnap
```

Example 10 – Uses the master key to encrypt an existing CEK “k2”:

alter encryption key k2
        with passwd 'goodbye'
        modify encryption
        with master key

Example 11 – Reencrypt an existing CEK “k3” that is currently encrypted by the master key, to use dual control:
```
alter encryption key k3
        modify encryption
        with master key
        dual_control
```
Example 13 – Sets up the recovery key copy and uses it for key recovery after losing a password.
1. The key custodian originally creates a new encryption key protected by a password:
```
create encryption key key1 for AES passwd 'loseitl8ter'
```
2. The key custodian adds a special encryption key recovery copy for key1 for Charlie:
```
alter encryption key key1 with passwd 'loseitl8ter'
     add encryption
     with passwd 'temppasswd'
     for user charlie
     for recovery 
```
3. Charlie assigns a different password to the recovery copy and saves this password in a locked drawer:
```
alter encryption key key1
     with passwd 'temppasswd'
     modify encryption
     with passwd 'finditl8ter'
     for recovery
```
4. If the key custodian loses the password for base key, he can obtain the password from Charlie and recover the base key from the recovery copy of the key using:
```
alter encryption key key1
     with passwd 'finditl8ter'
     recover encryption
     with passwd 'newpasswd'
```

Usage

If the SSO issues alter encryption key to set the key as the database default, the specified key replaces any existing key as the default.
If the key custodian issues alter encryption key to set a key as the database default, the specified key and the current default key (if it exists) must be owned by the key custodian.
Keys are owned and managed by users with keycustodian_role, the sso_role, or by users who are explicitly granted permission for the create encryption key command. Keys are used by all users who have permissions to process and see the data from encrypted columns. How the SAP ASE server protects keys affects how they are accessed:
1. The key owner creates the key for encryption by the system encryption password– when users access the encrypted data, the SAP ASE server decrypts the base key using the system encryption password. The key owner does not create individual key copies for users.
2. The key custodian encrypts the base key with an explicit password – rather than create key copies, the key custodian shares this password with all users who process encrypted data. Users or applications must supply this password with the set encryption passwd command to access data. See set encryption passwrd.
3. The key custodian adds key copies for end users so that users do not have to share passwords. Users must enter their key copy’s password using set encryption passwd to access encrypted columns. Alternatively, the key custodian can set up key copies for encryption by the key assignee's login password. This password does not have to be entered through set encryption passwd.
When you create a key using create encryption key, the SAP ASE server saves the key in encrypted form, along with the key’s properties, as a row in sysencryptkeys. This row represents the base key. The key owner can choose to allow access to encrypted data exclusively through the base key, or use alter encryption key to add key copies for individual users.
If you do not include the with passwd parameter with alter encryption, the SAP ASE server uses the system encryption password.
You cannot use the system encryption password to alter the base key of a key that has copies, and you cannot encrypt copies of keys with the system encryption password.
Users assigned key copies modify only their own key copies.
If you specify for login_association, the SAP ASE server temporarily encrypts the key copy with the system encryption password. The key copy is reencrypted by the copy owner’s login password when he or she encrypts or decrypts data with that key.
You cannot specify for recovery and login_association for the same key copy.

Permissions

The permission checks for alter encryption key differ based on your granular permissions settings.

Setting	Description
Enabled	With granular permissions enabled, you must be a user with `manage column encryption key` privilege to execute `alter encryption key` as default or not default. You must be the key owner or have the following privilege depending the key type: column encryption key – `manage column encryption key` master key – `manage master key` service key – `manage service key` to: Use alter encryption key to add or drop key copies, recover the key, and modify the key owner. Execute alter encryption key to modify the password of the base key. Note: You must be the user assigned the key copy to modify the key copy password. You implicitly have permission to modify your own key copy’s password.
Disabled	With granular permissions disabled, you must be a user with sso_role, or keycustodian_role to execute alter encryption key as default or not default. You must be the system security officer or the key owner to: Use alter encryption key to add or drop key copies, recover the key, and modify the key owner. Execute alter encryption key to modify the password of the base key. Note: You must be the user assigned the key copy to modify the key copy password. You implicitly have permission to modify your own key copy’s password.

Setting

Description

Enabled

With granular permissions enabled, you must be a user with manage column encryption key privilege to execute alter encryption key as default or not default.

You must be the key owner or have the following privilege depending the key type:

column encryption key – manage column encryption key
master key – manage master key
service key – manage service key

to:

Use alter encryption key to add or drop key copies, recover the key, and modify the key owner.
Execute alter encryption key to modify the password of the base key.

Note: You must be the user assigned the key copy to modify the key copy password. You implicitly have permission to modify your own key copy’s password.

Disabled

With granular permissions disabled, you must be a user with sso_role, or keycustodian_role to execute alter encryption key as default or not default.

You must be the system security officer or the key owner to:

Use alter encryption key to add or drop key copies, recover the key, and modify the key owner.
Execute alter encryption key to modify the password of the base key.

Note: You must be the user assigned the key copy to modify the key copy password. You implicitly have permission to modify your own key copy’s password.

Auditing

For information about auditing encrypted columns, see Auditing Encrypted Columns in the Encrypted Columns Users Guide.