1/*
2 * Copyright 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.privacy;
18
19/**
20 * An interface for differential privacy encoder.
21 * Applications can use it to convert privacy sensitive data to privacy protected report.
22 * There is no decoder implemented in Android as it is not possible decode a single report by
23 * design.
24 *
25 * <p>Each type of log should have its own encoder, otherwise it may leak
26 * some information about Permanent Randomized Response(PRR, is used to create a “noisy”
27 * answer which is memoized by the client and permanently reused in place of the real answer).
28 *
29 * <p>Some encoders may not support all encoding methods, and it will throw {@link
30 * UnsupportedOperationException} if you call unsupported encoding method.
31 *
32 * <p><b>WARNING:</b> Privacy protection works only when encoder uses a suitable DP configuration,
33 * and the configuration and algorithm that is suitable is highly dependent on the use case.
34 * If the configuration is not suitable for the use case, it may hurt privacy or utility or both.
35 *
36 * @hide
37 */
38public interface DifferentialPrivacyEncoder {
39
40    /**
41     * Apply differential privacy to encode a string.
42     *
43     * @param original An arbitrary string
44     * @return Differential privacy encoded bytes derived from the string
45     */
46    byte[] encodeString(String original);
47
48    /**
49     * Apply differential privacy to encode a boolean.
50     *
51     * @param original An arbitrary boolean.
52     * @return Differential privacy encoded bytes derived from the boolean
53     */
54    byte[] encodeBoolean(boolean original);
55
56    /**
57     * Apply differential privacy to encode sequence of bytes.
58     *
59     * @param original An arbitrary byte array.
60     * @return Differential privacy encoded bytes derived from the bytes
61     */
62    byte[] encodeBits(byte[] original);
63
64    /**
65     * Returns the configuration that this encoder is using.
66     */
67    DifferentialPrivacyConfig getConfig();
68
69    /**
70     * Return True if the output from encoder is NOT securely randomized, otherwise encoder should
71     * be secure to randomize input.
72     *
73     * <b> A non-secure encoder is intended only for testing only and must not be used to process
74     * real data.
75     * </b>
76     */
77    boolean isInsecureEncoderForTest();
78}
79