1 /*
2  * Copyright (C) 2024 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 
17 package com.android.adservices.service.kanon;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 
23 import com.google.auto.value.AutoValue;
24 import com.google.auto.value.AutoValue.CopyAnnotations;
25 
26 import java.lang.annotation.Retention;
27 import java.lang.annotation.RetentionPolicy;
28 import java.time.Instant;
29 
30 /** Represents the KAnon Message sent by the server and used SIGN/JOIN KAnon calls. */
31 @AutoValue
32 @CopyAnnotations
33 public abstract class KAnonMessageEntity {
34     @IntDef(
35             value = {
36                 KAnonMessageEntity.KanonMessageEntityStatus.NOT_PROCESSED,
37                 KAnonMessageEntity.KanonMessageEntityStatus.SIGNED,
38                 KAnonMessageEntity.KanonMessageEntityStatus.JOINED,
39                 KAnonMessageEntity.KanonMessageEntityStatus.FAILED
40             })
41     @Retention(RetentionPolicy.SOURCE)
42     public @interface KanonMessageEntityStatus {
43         int NOT_PROCESSED = 0;
44         int SIGNED = 1;
45         int JOINED = 2;
46         int FAILED = 3;
47     }
48 
49     /**
50      * @return ad selection id corresponding to this {@link KAnonMessageEntity}
51      */
52     @NonNull
getAdSelectionId()53     public abstract long getAdSelectionId();
54 
55     /**
56      * @return hash set for this {@link KAnonMessageEntity}
57      */
58     @NonNull
getHashSet()59     public abstract String getHashSet();
60 
61     /**
62      * @return the messageId for this {@link KAnonMessageEntity}
63      */
64     @Nullable
getMessageId()65     public abstract Long getMessageId();
66 
67     /**
68      * Corresponding client parameters expiry instant. This field is initially null and once the
69      * message is joined/signed, this field is updated to match the expiry instant of the client
70      * parameters used to make the sign/join calls. We need this field to keep track of expiry
71      * instant of the client parameters used for signing/joining this message.
72      *
73      * @return the Corresponding client parameters expiry instant for this message.
74      */
75     @Nullable
getCorrespondingClientParametersExpiryInstant()76     public abstract Instant getCorrespondingClientParametersExpiryInstant();
77 
78     @NonNull
79     @KanonMessageEntityStatus
getStatus()80     public abstract int getStatus();
81 
82     /** Returns a {@link KAnonMessageEntity.Builder} for {@link KAnonMessageEntity} */
builder()83     public static KAnonMessageEntity.Builder builder() {
84         return new AutoValue_KAnonMessageEntity.Builder();
85     }
86 
87     /** Creates and returns {@link KAnonMessageEntity} object */
create( long adSelectionId, String hashSet, Long messageId, @KanonMessageEntityStatus int status, Instant correspondingClientParametersExpiryInstant)88     public KAnonMessageEntity create(
89             long adSelectionId,
90             String hashSet,
91             Long messageId,
92             @KanonMessageEntityStatus int status,
93             Instant correspondingClientParametersExpiryInstant) {
94         return builder()
95                 .setAdSelectionId(adSelectionId)
96                 .setHashSet(hashSet)
97                 .setMessageId(messageId)
98                 .setCorrespondingClientParametersExpiryInstant(
99                         correspondingClientParametersExpiryInstant)
100                 .setStatus(status)
101                 .build();
102     }
103 
104     /** Builder class for {@link KAnonMessageEntity} */
105     @AutoValue.Builder
106     public abstract static class Builder {
107         /** Sets the hash set to sign/join for this k-anon message entity. */
setHashSet(@onNull String hashSet)108         public abstract Builder setHashSet(@NonNull String hashSet);
109 
110         /** Sets the ad selection id for this k-anon message entity. */
setAdSelectionId(@onNull long adSelectionId)111         public abstract Builder setAdSelectionId(@NonNull long adSelectionId);
112 
113         /** Sets the message id for this k-anon message entity */
setMessageId(@ullable Long messageId)114         public abstract Builder setMessageId(@Nullable Long messageId);
115 
116         /** Sets the message status for this kanon message entity */
setStatus(@anonMessageEntityStatus int status)117         public abstract Builder setStatus(@KanonMessageEntityStatus int status);
118 
119         /** Sets the Corresponding client parameters expiry instant */
setCorrespondingClientParametersExpiryInstant( Instant correspondingClientParametersExpiryInstant)120         public abstract Builder setCorrespondingClientParametersExpiryInstant(
121                 Instant correspondingClientParametersExpiryInstant);
122 
123         /** Builds and returns {@link KAnonMessageEntity} */
build()124         public abstract KAnonMessageEntity build();
125     }
126 }
127