alter encryption key

Description

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

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

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

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), 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 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. Adaptive 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. Adaptive 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

Re-encrypt 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 12

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 Adaptive 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, Adaptive 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, 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, or use alter encryption key to add key copies for individual users.

• 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 assigned key copies modify only their own key copies.

• If you specify for login_association, Adaptive 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.

Auditing

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

See also