def example_ckks_basics():
print("Example: CKKS Basics");
#In this example we demonstrate evaluating a polynomial function
#
# PI*x^3 + 0.4*x + 1
#
#on encrypted floating-point input data x for a set of 4096 equidistant points
#in the interval [0, 1]. This example demonstrates many of the main features
#of the CKKS scheme, but also the challenges in using it.
#
# We start by setting up the CKKS scheme.
parms = EncryptionParameters(scheme_type.CKKS)
#We saw in `2_encoders.cpp' that multiplication in CKKS causes scales
#in ciphertexts to grow. The scale of any ciphertext must not get too close
#to the total size of coeff_modulus, or else the ciphertext simply runs out of
#room to store the scaled-up plaintext. The CKKS scheme provides a `rescale'
#functionality that can reduce the scale, and stabilize the scale expansion.
#
#Rescaling is a kind of modulus switch operation (recall `3_levels.cpp').
#As modulus switching, it removes the last of the primes from coeff_modulus,
#but as a side-effect it scales down the ciphertext by the removed prime.
#Usually we want to have perfect control over how the scales are changed,
#which is why for the CKKS scheme it is more common to use carefully selected
#primes for the coeff_modulus.
#
#More precisely, suppose that the scale in a CKKS ciphertext is S, and the
#last prime in the current coeff_modulus (for the ciphertext) is P. Rescaling
#to the next level changes the scale to S/P, and removes the prime P from the
#coeff_modulus, as usual in modulus switching. The number of primes limits
#how many rescalings can be done, and thus limits the multiplicative depth of
#the computation.
#
#It is possible to choose the initial scale freely. One good strategy can be
#to is to set the initial scale S and primes P_i in the coeff_modulus to be
#very close to each other. If ciphertexts have scale S before multiplication,
#they have scale S^2 after multiplication, and S^2/P_i after rescaling. If all
#P_i are close to S, then S^2/P_i is close to S again. This way we stabilize the
#scales to be close to S throughout the computation. Generally, for a circuit
#of depth D, we need to rescale D times, i.e., we need to be able to remove D
#primes from the coefficient modulus. Once we have only one prime left in the
#coeff_modulus, the remaining prime must be larger than S by a few bits to
#preserve the pre-decimal-point value of the plaintext.
#
#Therefore, a generally good strategy is to choose parameters for the CKKS
#scheme as follows:
#
# (1) Choose a 60-bit prime as the first prime in coeff_modulus. This will
# give the highest precision when decrypting;
# (2) Choose another 60-bit prime as the last element of coeff_modulus, as
# this will be used as the special prime and should be as large as the
# largest of the other primes;
# (3) Choose the intermediate primes to be close to each other.
#
#We use CoeffModulus::Create to generate primes of the appropriate size. Note
#that our coeff_modulus is 200 bits total, which is below the bound for our
#poly_modulus_degree: CoeffModulus::MaxBitCount(8192) returns 218.
poly_modulus_degree = 8192
parms.set_poly_modulus_degree(poly_modulus_degree)
parms.set_coeff_modulus(CoeffModulus.Create(
poly_modulus_degree, IntVector([60, 40, 40, 60])))
#We choose the initial scale to be 2^40. At the last level, this leaves us
#60-40=20 bits of precision before the decimal point, and enough (roughly
#10-20 bits) of precision after the decimal point. Since our intermediate
#primes are 40 bits (in fact, they are very close to 2^40), we can achieve
#scale stabilization as described above.
scale = 2.0**40
context = SEALContext.Create(parms)
print_parameters(context)
keygen = KeyGenerator(context)
public_key = keygen.public_key()
secret_key = keygen.secret_key()
relin_keys = keygen.relin_keys()
encryptor = Encryptor(context, public_key)
evaluator = Evaluator(context)
decryptor = Decryptor(context, secret_key)
encoder = CKKSEncoder(context)
slot_count = encoder.slot_count()
print("Number of slots: {}".format(slot_count))
step_size = 1.0 / (slot_count - 1)
input = DoubleVector(list(map(lambda x: x*step_size, range(0, slot_count))))
print("Input vector: ")
print_vector(input)
print("Evaluating polynomial PI*x^3 + 0.4x + 1 ...")
#We create plaintexts for PI, 0.4, and 1 using an overload of CKKSEncoder::encode
#that encodes the given floating-point value to every slot in the vector.
plain_coeff3 = Plaintext()
plain_coeff1 = Plaintext()
plain_coeff0 = Plaintext()
encoder.encode(3.14159265, scale, plain_coeff3)
encoder.encode(0.4, scale, plain_coeff1)
encoder.encode(1.0, scale, plain_coeff0)
x_plain = Plaintext()
print("Encode input vectors.")
encoder.encode(input, scale, x_plain)
x1_encrypted = Ciphertext()
encryptor.encrypt(x_plain, x1_encrypted)
#To compute x^3 we first compute x^2 and relinearize. However, the scale has
#now grown to 2^80.
x3_encrypted = Ciphertext()
print("Compute x^2 and relinearize:")
evaluator.square(x1_encrypted, x3_encrypted)
evaluator.relinearize_inplace(x3_encrypted, relin_keys)
print(" + Scale of x^2 before rescale: {} bits".format(log2(x3_encrypted.scale())))
#Now rescale; in addition to a modulus switch, the scale is reduced down by
#a factor equal to the prime that was switched away (40-bit prime). Hence, the
#new scale should be close to 2^40. Note, however, that the scale is not equal
#to 2^40: this is because the 40-bit prime is only close to 2^40.
print("Rescale x^2.")
evaluator.rescale_to_next_inplace(x3_encrypted)
print(" + Scale of x^2 after rescale: {} bits".format(log2(x3_encrypted.scale())))
#Now x3_encrypted is at a different level than x1_encrypted, which prevents us
#from multiplying them to compute x^3. We could simply switch x1_encrypted to
#the next parameters in the modulus switching chain. However, since we still
#need to multiply the x^3 term with PI (plain_coeff3), we instead compute PI*x
#first and multiply that with x^2 to obtain PI*x^3. To this end, we compute
#PI*x and rescale it back from scale 2^80 to something close to 2^40.
print("Compute and rescale PI*x.")
x1_encrypted_coeff3 = Ciphertext()
evaluator.multiply_plain(x1_encrypted, plain_coeff3, x1_encrypted_coeff3)
print(" + Scale of PI*x before rescale: {} bits".format(log2(x1_encrypted_coeff3.scale())))
evaluator.rescale_to_next_inplace(x1_encrypted_coeff3)
print(" + Scale of PI*x after rescale: {} bits".format(log2(x1_encrypted_coeff3.scale())))
#Since x3_encrypted and x1_encrypted_coeff3 have the same exact scale and use
#the same encryption parameters, we can multiply them together. We write the
#result to x3_encrypted, relinearize, and rescale. Note that again the scale
#is something close to 2^40, but not exactly 2^40 due to yet another scaling
#by a prime. We are down to the last level in the modulus switching chain.
print("Compute, relinearize, and rescale (PI*x)*x^2.")
evaluator.multiply_inplace(x3_encrypted, x1_encrypted_coeff3)
evaluator.relinearize_inplace(x3_encrypted, relin_keys)
print(" + Scale of PI*x^3 before rescale: {} bits".format(log2(x3_encrypted.scale())))
evaluator.rescale_to_next_inplace(x3_encrypted)
print(" + Scale of PI*x^3 after rescale: {} bits".format(log2(x3_encrypted.scale())))
#Next we compute the degree one term. All this requires is one multiply_plain
#with plain_coeff1. We overwrite x1_encrypted with the result.
print("Compute and rescale 0.4*x.")
evaluator.multiply_plain_inplace(x1_encrypted, plain_coeff1)
print(" + Scale of 0.4*x before rescale: {} bits".format(log2(x1_encrypted.scale())))
evaluator.rescale_to_next_inplace(x1_encrypted)
print(" + Scale of 0.4*x after rescale: {} bits".format(log2(x1_encrypted.scale())))
#Now we would hope to compute the sum of all three terms. However, there is
#a serious problem: the encryption parameters used by all three terms are
#different due to modulus switching from rescaling.
#
#Encrypted addition and subtraction require that the scales of the inputs are
#the same, and also that the encryption parameters (parms_id) match. If there
#is a mismatch, Evaluator will throw an exception.
print("Parameters used by all three terms are different.")
print(" + Modulus chain index for x3_encrypted: {}".format(
context.get_context_data(x3_encrypted.parms_id()).chain_index()))
print(" + Modulus chain index for x1_encrypted: {}".format(
context.get_context_data(x1_encrypted.parms_id()).chain_index()))
print(" + Modulus chain index for plain_coeff0: {}".format(
context.get_context_data(plain_coeff0.parms_id()).chain_index()))
#Let us carefully consider what the scales are at this point. We denote the
#primes in coeff_modulus as P_0, P_1, P_2, P_3, in this order. P_3 is used as
#the special modulus and is not involved in rescalings. After the computations
#above the scales in ciphertexts are:
#
# - Product x^2 has scale 2^80 and is at level 2;
# - Product PI*x has scale 2^80 and is at level 2;
# - We rescaled both down to scale 2^80/P_2 and level 1;
# - Product PI*x^3 has scale (2^80/P_2)^2;
# - We rescaled it down to scale (2^80/P_2)^2/P_1 and level 0;
# - Product 0.4*x has scale 2^80;
# - We rescaled it down to scale 2^80/P_2 and level 1;
# - The contant term 1 has scale 2^40 and is at level 2.
#
#Although the scales of all three terms are approximately 2^40, their exact
#values are different, hence they cannot be added together.
print("The exact scales of all three terms are different:")
print(" + Exact scale in PI*x^3: {0:0.10f}".format(x3_encrypted.scale()))
print(" + Exact scale in 0.4*x: {0:0.10f}".format(x1_encrypted.scale()))
print(" + Exact scale in 1: {0:0.10f}".format(plain_coeff0.scale()))
#There are many ways to fix this problem. Since P_2 and P_1 are really close
#to 2^40, we can simply "lie" to Microsoft SEAL and set the scales to be the
#same. For example, changing the scale of PI*x^3 to 2^40 simply means that we
#scale the value of PI*x^3 by 2^120/(P_2^2*P_1), which is very close to 1.
#This should not result in any noticeable error.
#
#Another option would be to encode 1 with scale 2^80/P_2, do a multiply_plain
#with 0.4*x, and finally rescale. In this case we would need to additionally
#make sure to encode 1 with appropriate encryption parameters (parms_id).
#
#In this example we will use the first (simplest) approach and simply change
#the scale of PI*x^3 and 0.4*x to 2^40.
print("Normalize scales to 2^40.")
x3_encrypted.set_scale(2.0**40)
x1_encrypted.set_scale(2.0**40)
#We still have a problem with mismatching encryption parameters. This is easy
#to fix by using traditional modulus switching (no rescaling). CKKS supports
#modulus switching just like the BFV scheme, allowing us to switch away parts
#of the coefficient modulus when it is simply not needed.
print("Normalize encryption parameters to the lowest level.")
last_parms_id = x3_encrypted.parms_id()
evaluator.mod_switch_to_inplace(x1_encrypted, last_parms_id)
evaluator.mod_switch_to_inplace(plain_coeff0, last_parms_id)
#All three ciphertexts are now compatible and can be added.
print("Compute PI*x^3 + 0.4*x + 1.")
encrypted_result = Ciphertext()
evaluator.add(x3_encrypted, x1_encrypted, encrypted_result)
evaluator.add_plain_inplace(encrypted_result, plain_coeff0)
#First print the true result.
plain_result = Plaintext()
print("Decrypt and decode PI*x^3 + 0.4x + 1.")
print(" + Expected result:")
true_result = DoubleVector(list(map(lambda x: (3.14159265 * x * x + 0.4)* x + 1, input)))
print_vector(true_result)
#Decrypt, decode, and print the result.
decryptor.decrypt(encrypted_result, plain_result)
result = DoubleVector()
encoder.decode(plain_result, result)
print(" + Computed result ...... Correct.")
print_vector(result)
def example_levels():
print("Example: Levels")
#In this examples we describe the concept of `levels' in BFV and CKKS and the
#related objects that represent them in Microsoft SEAL.
#
#In Microsoft SEAL a set of encryption parameters (excluding the random number
#generator) is identified uniquely by a 256-bit hash of the parameters. This
#hash is called the `parms_id' and can be easily accessed and printed at any
#time. The hash will change as soon as any of the parameters is changed.
#
#When a SEALContext is created from a given EncryptionParameters instance,
#Microsoft SEAL automatically creates a so-called `modulus switching chain',
#which is a chain of other encryption parameters derived from the original set.
#The parameters in the modulus switching chain are the same as the original
#parameters with the exception that size of the coefficient modulus is
#decreasing going down the chain. More precisely, each parameter set in the
#chain attempts to remove the last coefficient modulus prime from the
#previous set; this continues until the parameter set is no longer valid
#(e.g., plain_modulus is larger than the remaining coeff_modulus). It is easy
#to walk through the chain and access all the parameter sets. Additionally,
#each parameter set in the chain has a `chain index' that indicates its
#position in the chain so that the last set has index 0. We say that a set
#of encryption parameters, or an object carrying those encryption parameters,
#is at a higher level in the chain than another set of parameters if its the
#chain index is bigger, i.e., it is earlier in the chain.
#
#Each set of parameters in the chain involves unique pre-computations performed
#when the SEALContext is created, and stored in a SEALContext::ContextData
#object. The chain is basically a linked list of SEALContext::ContextData
#objects, and can easily be accessed through the SEALContext at any time. Each
#node can be identified by the parms_id of its specific encryption parameters
#(poly_modulus_degree remains the same but coeff_modulus varies).
parms = EncryptionParameters(scheme_type.BFV)
poly_modulus_degree = 8192
parms.set_poly_modulus_degree(poly_modulus_degree)
#In this example we use a custom coeff_modulus, consisting of 5 primes of
#sizes 50, 30, 30, 50, and 50 bits. Note that this is still OK according to
#the explanation in `1_bfv_basics.cpp'. Indeed,
#
# CoeffModulus::MaxBitCount(poly_modulus_degree)
#
#returns 218 (greater than 50+30+30+50+50=210).
#
#Due to the modulus switching chain, the order of the 5 primes is significant.
#The last prime has a special meaning and we call it the `special prime'. Thus,
#the first parameter set in the modulus switching chain is the only one that
#involves the special prime. All key objects, such as SecretKey, are created
#at this highest level. All data objects, such as Ciphertext, can be only at
#lower levels. The special prime should be as large as the largest of the
#other primes in the coeff_modulus, although this is not a strict requirement.
#
# special prime +---------+
# |
# v
#coeff_modulus: { 50, 30, 30, 50, 50 } +---+ Level 4 (all keys; `key level')
# |
# |
# coeff_modulus: { 50, 30, 30, 50 } +---+ Level 3 (highest `data level')
# |
# |
# coeff_modulus: { 50, 30, 30 } +---+ Level 2
# |
# |
# coeff_modulus: { 50, 30 } +---+ Level 1
# |
# |
# coeff_modulus: { 50 } +---+ Level 0 (lowest level)
parms.set_coeff_modulus(
CoeffModulus.Create(poly_modulus_degree,
IntVector([50, 30, 30, 50, 50])))
#In this example the plain_modulus does not play much of a role; we choose
#some reasonable value.
parms.set_plain_modulus(PlainModulus.Batching(poly_modulus_degree, 20))
context = SEALContext.Create(parms)
print_parameters(context)
#There are convenience method for accessing the SEALContext::ContextData for
#some of the most important levels:
#
# SEALContext::key_context_data(): access to key level ContextData
# SEALContext::first_context_data(): access to highest data level ContextData
# SEALContext::last_context_data(): access to lowest level ContextData
#
#We iterate over the chain and print the parms_id for each set of parameters.
print("Print the modulus switching chain.")
#First print the key level parameter information.
context_data = context.key_context_data()
print("----> Level (chain index): {} ...... key_context_data()".format(
context_data.chain_index()))
print(" parms_id: {}".format(list2hex(context_data.parms_id())))
print("coeff_modulus primes:", end=' ')
for prime in context_data.parms().coeff_modulus():
print(hex(prime.value()), end=' ')
print("")
print("\\")
print(" \\-->")
#Next iterate over the remaining (data) levels.
context_data = context.first_context_data()
while (context_data):
print(" Level (chain index): {} ".format(context_data.chain_index()),
end='')
if context_data.parms_id() == context.first_parms_id():
print(" ...... first_context_data()")
elif context_data.parms_id() == context.last_parms_id():
print(" ...... last_context_data()")
else:
print("")
print(" parms_id: {}".format(list2hex(context_data.parms_id())))
print("coeff_modulus primes:", end=' ')
for prime in context_data.parms().coeff_modulus():
print(hex(prime.value()), end=' ')
print("")
print("\\")
print(" \\-->")
#Step forward in the chain.
context_data = context_data.next_context_data()
print(" End of chain reached")
#We create some keys and check that indeed they appear at the highest level.
keygen = KeyGenerator(context)
public_key = keygen.public_key()
secret_key = keygen.secret_key()
relin_keys = keygen.relin_keys()
galois_keys = keygen.galois_keys()
print("Print the parameter IDs of generated elements.")
print(" + public_key: {}".format(list2hex(public_key.parms_id())))
print(" + secret_key: {}".format(list2hex(secret_key.parms_id())))
print(" + relin_keys: {}".format(list2hex(relin_keys.parms_id())))
print(" + galois_keys: {}".format(list2hex(galois_keys.parms_id())))
encryptor = Encryptor(context, public_key)
evaluator = Evaluator(context)
decryptor = Decryptor(context, secret_key)
#In the BFV scheme plaintexts do not carry a parms_id, but ciphertexts do. Note
#how the freshly encrypted ciphertext is at the highest data level.
plain = Plaintext("1x^3 + 2x^2 + 3x^1 + 4")
encrypted = Ciphertext()
encryptor.encrypt(plain, encrypted)
print(" + plain: {} (not set in BFV)".format(
list2hex(plain.parms_id())))
print(" + encrypted: {}".format(list2hex(encrypted.parms_id())))
#`Modulus switching' is a technique of changing the ciphertext parameters down
#in the chain. The function Evaluator::mod_switch_to_next always switches to
#the next level down the chain, whereas Evaluator::mod_switch_to switches to
#a parameter set down the chain corresponding to a given parms_id. However, it
#is impossible to switch up in the chain.
print("Perform modulus switching on encrypted and print.")
context_data = context.first_context_data()
print("---->")
while (context_data.next_context_data()):
print(" Level (chain index): {} ".format(context_data.chain_index()))
print(" parms_id of encrypted: {}".format(
list2hex(encrypted.parms_id())))
print(" Noise budget at this level: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
print("\\")
print(" \\-->")
evaluator.mod_switch_to_next_inplace(encrypted)
context_data = context_data.next_context_data()
print(" Level (chain index): {}".format(context_data.chain_index()))
print(" parms_id of encrypted: {}".format(encrypted.parms_id()))
print(" Noise budget at this level: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
print("\\")
print(" \\-->")
print(" End of chain reached")
#At this point it is hard to see any benefit in doing this: we lost a huge
#amount of noise budget (i.e., computational power) at each switch and seemed
#to get nothing in return. Decryption still works.
print("Decrypt still works after modulus switching.")
decryptor.decrypt(encrypted, plain)
print(" + Decryption of encrypted: {} ...... Correct.".format(
plain.to_string()))
#However, there is a hidden benefit: the size of the ciphertext depends
#linearly on the number of primes in the coefficient modulus. Thus, if there
#is no need or intention to perform any further computations on a given
#ciphertext, we might as well switch it down to the smallest (last) set of
#parameters in the chain before sending it back to the secret key holder for
#decryption.
#
#Also the lost noise budget is actually not an issue at all, if we do things
#right, as we will see below.
#
#First we recreate the original ciphertext and perform some computations.
print("Computation is more efficient with modulus switching.")
print("Compute the 8th power.")
encryptor.encrypt(plain, encrypted)
print(" + Noise budget fresh: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
evaluator.square_inplace(encrypted)
evaluator.relinearize_inplace(encrypted, relin_keys)
print(" + Noise budget of the 2nd power: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
evaluator.square_inplace(encrypted)
evaluator.relinearize_inplace(encrypted, relin_keys)
print(" + Noise budget of the 4th power: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
#Surprisingly, in this case modulus switching has no effect at all on the
#noise budget.
evaluator.mod_switch_to_next_inplace(encrypted)
print(" + Noise budget after modulus switching: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
#This means that there is no harm at all in dropping some of the coefficient
#modulus after doing enough computations. In some cases one might want to
#switch to a lower level slightly earlier, actually sacrificing some of the
#noise budget in the process, to gain computational performance from having
#smaller parameters. We see from the print-out that the next modulus switch
#should be done ideally when the noise budget is down to around 25 bits.
evaluator.square_inplace(encrypted)
evaluator.relinearize_inplace(encrypted, relin_keys)
print(" + Noise budget of the 8th power: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
evaluator.mod_switch_to_next_inplace(encrypted)
print(" + Noise budget after modulus switching: {} bits".format(
decryptor.invariant_noise_budget(encrypted)))
#At this point the ciphertext still decrypts correctly, has very small size,
#and the computation was as efficient as possible. Note that the decryptor
#can be used to decrypt a ciphertext at any level in the modulus switching
#chain.
decryptor.decrypt(encrypted, plain)
print(" + Decryption of the 8th power (hexadecimal) ...... Correct.")
print(" {}".format(plain.to_string()))
#In BFV modulus switching is not necessary and in some cases the user might
#not want to create the modulus switching chain, except for the highest two
#levels. This can be done by passing a bool `false' to SEALContext::Create.
context = SEALContext.Create(parms, False)
#We can check that indeed the modulus switching chain has been created only
#for the highest two levels (key level and highest data level). The following
#loop should execute only once.
print("Optionally disable modulus switching chain expansion.")
print("Print the modulus switching chain.")
print("---->")
context_data = context.key_context_data()
while (context_data):
print(" Level (chain index): {}".format(context_data.chain_index()))
print(" parms_id: {}".format(list2hex(context_data.parms_id())))
print("coeff_modulus primes:", end=' ')
for prime in context_data.parms().coeff_modulus():
print(hex(prime.value()), end=' ')
print("")
print("\\")
print(" \\-->")
context_data = context_data.next_context_data()
print(" End of chain reached")
