alter encryption key

Description

Changes the current password for an encryption key.

For more information about encrypted columns, see the Encrypted Column Users Guide.

Syntax

alter encryption key [[database.][owner].] keyname
	{ [ as | not default ]
		| [ with passwd 
			'password' | system_encr_passwd | login_passwd ]
			modify encryption 
			 [ with passwd 
			'passwd' | system_encr_passwd | login_passwd ]
		| with passwd 'password'
			add encryption [ with passwd 'password' ] 
			for user user_name
			[ for login_association | for recovery ]
		| drop encryption for
			{ user user_name | key recovery } 
		| [ with passwd 'password ']
			recover encryption with passwd 'password'
		| modify owner user_name
}

Syntax for working with a recovery key copy:

alter encryption key keyname with passwd
		base_key_passwd | old_recovery_passwd
	{ [add encryption with passwd recovery_passwd
		for user key_recovery_user for recovery ] 
	| [modify encryption with passwd new_recovery_passwd 
		for recovery]
	| [recover encryption with passwd new_base_key_passwd]
	}

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.

with passwd ['password' | system_encr_passwd | login_password ]: specifies the current password Adaptive 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. The key owner can add key copies for individual users that are accessible through a private password or a login password.

Encrypt a newly-added key copy

Recover the encryption key after losing a password

Adaptive Server supports the following of passwords for keys:

password – a character string up to 255 bytes long.

login_passwd – tells Adaptive Server to use the session’s login password.

system_encr_passwd – is the system encryption password for the current database.

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.

add encryption: adds encrypted key copy for a designated user.

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 is encrypted by the assigned user’s login password during his or her first access to this key.

for recovery: indicates this key copy is for recovery purposes.

drop encryption: indicates that you are dropping the key copy for the specified user.

recover encryption: makes the base key accessible to a new password.

When you create a key using create encryption key, Adaptive 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.

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, Adaptive 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 to 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 re-encrypts the base key
The user assigned a key copy – the command re-encrypts that key copy.

Example 3

Changes the password on a key copy to the current session’s login password:

alter encryption key important_key
     modify encryption
     with passwd login_passwd

This command can be executed only by a user who has been assigned a key copy:

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. It 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 does not need to 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. Adaptive Server uses the password “TopSecret” to decrypt the base key, making a copy of the raw key and encrypting it for user “ted” using the password “just4now.”

Example 7

Modifies the encryption for user “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

Sets up the recovery key copy and use it for key recovery after losing a password:

The key custodian originally creates a new encryption key protected by a password.
```
create encryption key key1 for AES passwd 'loseitl8ter'
```

The key custodian adds a special encryption key recovery copy for key1 for user “charlie.”

alter encryption key key1 with passwd 'loseitl8ter'
     add encryption
     with passwd 'temppasswd'
     for user charlie
     for recovery

“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

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.

Keys are owned and managed by users with keycustodian_role or by users 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 Adaptive Server protects keys affects how they are accessed:

The key owner creates the key for encryption by the system encryption password – When users access the encrypted data, Adaptive Server decrypts the base key using the system encryption password. The key owner does not create individual key copies for users.

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 to access data. See set encryption passwd.
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.
If you do not include the with passwd parameter with alter encryption, Adaptive 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 implicitly modify only their own key-copies.
If you specify for login_association, Adaptive Server temporarily encrypts the key copy with the system encryption password.
You cannot specify for recovery and login_association for the same key copy.

Permissions

You must be:

The system security officer or a user with the keycustodian_role to execute alter encryption key as default or not default. This permission cannot be granted to other users
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.
The system security officer or the key owner to execute alter encryption key to modify the password of the base key. 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.

Auditing

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