1 /* 2 * Copyright (C) 2023 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.libraries.entitlement.odsa; 18 19 import androidx.annotation.IntDef; 20 import androidx.annotation.NonNull; 21 import androidx.annotation.Nullable; 22 23 import com.android.libraries.entitlement.EsimOdsaOperation; 24 import com.android.libraries.entitlement.EsimOdsaOperation.CompanionService; 25 import com.android.libraries.entitlement.EsimOdsaOperation.OdsaServiceStatus; 26 import com.android.libraries.entitlement.utils.Ts43Constants; 27 import com.android.libraries.entitlement.utils.Ts43Constants.AppId; 28 import com.android.libraries.entitlement.utils.Ts43Constants.NotificationAction; 29 30 import com.google.auto.value.AutoValue; 31 import com.google.common.collect.ImmutableList; 32 33 import java.lang.annotation.Retention; 34 import java.lang.annotation.RetentionPolicy; 35 36 /** 37 * Acquire configuration operation described in GSMA Service Entitlement Configuration section 6. 38 */ 39 public final class AcquireConfigurationOperation { 40 /** Indicating polling interval not available. */ 41 public static final int POLLING_INTERVAL_NOT_AVAILABLE = -1; 42 43 /** 44 * HTTP request parameters specific to on device service activation (ODSA) acquire configuration 45 * operation. See GSMA spec TS.43 section 6.2. 46 */ 47 @AutoValue 48 public abstract static class AcquireConfigurationRequest { 49 /** 50 * Returns the application id. Can only be {@link Ts43Constants#APP_ODSA_COMPANION}, 51 * {@link Ts43Constants#APP_ODSA_PRIMARY}, or 52 * {@link Ts43Constants#APP_ODSA_SERVER_INITIATED_REQUESTS}. 53 */ 54 @AppId appId()55 public abstract String appId(); 56 57 /** 58 * Returns the unique identifier of the companion device, like IMEI. Used by HTTP parameter 59 * {@code companion_terminal_id}. 60 */ 61 @NonNull companionTerminalId()62 public abstract String companionTerminalId(); 63 64 /** 65 * Returns the ICCID of the companion device. Used by HTTP parameter 66 * {@code companion_terminal_iccid}. 67 */ 68 @NonNull companionTerminalIccid()69 public abstract String companionTerminalIccid(); 70 71 /** 72 * Returns the EID of the companion device. Used by HTTP parameter 73 * {@code companion_terminal_eid}. 74 */ 75 @NonNull companionTerminalEid()76 public abstract String companionTerminalEid(); 77 78 /** 79 * Returns the ICCID of the primary device eSIM. Used by HTTP parameter 80 * {@code terminal_iccid}. 81 */ 82 @NonNull terminalIccid()83 public abstract String terminalIccid(); 84 85 /** 86 * Returns the eUICC identifier (EID) of the primary device eSIM. Used by HTTP parameter 87 * {@code terminal_eid}. 88 */ 89 @NonNull terminalEid()90 public abstract String terminalEid(); 91 92 /** 93 * Returns the unique identifier of the primary device eSIM, like the IMEI associated with 94 * the eSIM. Used by HTTP parameter {@code target_terminal_id}. 95 */ 96 @NonNull targetTerminalId()97 public abstract String targetTerminalId(); 98 99 /** 100 * Returns the ICCID primary device eSIM. Used by HTTP parameter 101 * {@code target_terminal_iccid}. 102 */ 103 @NonNull targetTerminalIccid()104 public abstract String targetTerminalIccid(); 105 106 /** 107 * Returns the eUICC identifier (EID) of the primary device eSIM. Used by HTTP parameter 108 * {@code target_terminal_eid}. 109 */ 110 @NonNull targetTerminalEid()111 public abstract String targetTerminalEid(); 112 113 /** 114 * Returns the notification token used to register for entitlement configuration request 115 * from network. Used by HTTP parameter {@code notif_token}. 116 */ 117 @NonNull notificationToken()118 public abstract String notificationToken(); 119 120 /** 121 * Returns the action associated with the notification token. Used by HTTP parameter 122 * {@code notif_action}. 123 */ 124 @NotificationAction notificationAction()125 public abstract int notificationAction(); 126 127 /** Returns a new {@link Builder} object. */ 128 @NonNull builder()129 public static Builder builder() { 130 return new AutoValue_AcquireConfigurationOperation_AcquireConfigurationRequest 131 .Builder() 132 .setCompanionTerminalId("") 133 .setCompanionTerminalIccid("") 134 .setCompanionTerminalEid("") 135 .setTerminalIccid("") 136 .setTerminalEid("") 137 .setTargetTerminalId("") 138 .setTargetTerminalIccid("") 139 .setTargetTerminalEid("") 140 .setNotificationToken("") 141 .setNotificationAction(Ts43Constants.NOTIFICATION_ACTION_ENABLE_FCM); 142 } 143 144 /** Builder */ 145 @AutoValue.Builder 146 public abstract static class Builder { 147 /** 148 * Sets the application id. 149 * 150 * @param appId The application id. Can only be 151 * {@link Ts43Constants#APP_ODSA_COMPANION}, 152 * {@link Ts43Constants#APP_ODSA_PRIMARY}, or 153 * {@link Ts43Constants#APP_ODSA_SERVER_INITIATED_REQUESTS}. 154 * @return The builder. 155 */ 156 @NonNull setAppId(@onNull @ppId String appId)157 public abstract Builder setAppId(@NonNull @AppId String appId); 158 159 /** 160 * Sets the unique identifier of the companion device, like IMEI. Used by HTTP parameter 161 * {@code companion_terminal_id} if set. 162 * 163 * <p>Used by companion device ODSA operation. 164 * 165 * @param companionTerminalId The unique identifier of the companion device. 166 * @return The builder. 167 */ 168 @NonNull setCompanionTerminalId(@onNull String companionTerminalId)169 public abstract Builder setCompanionTerminalId(@NonNull String companionTerminalId); 170 171 /** 172 * Sets the ICCID of the companion device. Used by HTTP parameter 173 * {@code companion_terminal_iccid} if set. 174 * 175 * <p>Used by companion device ODSA operation. 176 * 177 * @param companionTerminalIccid The ICCID of the companion device. 178 * @return The builder. 179 */ 180 @NonNull setCompanionTerminalIccid( @onNull String companionTerminalIccid)181 public abstract Builder setCompanionTerminalIccid( 182 @NonNull String companionTerminalIccid); 183 184 /** 185 * Sets the eUICC identifier (EID) of the companion device. Used by HTTP parameter 186 * {@code companion_terminal_eid} if set. 187 * 188 * <p>Used by companion device ODSA operation. 189 * 190 * @param companionTerminalEid The eUICC identifier (EID) of the companion device. 191 * @return The builder. 192 */ 193 @NonNull setCompanionTerminalEid(@onNull String companionTerminalEid)194 public abstract Builder setCompanionTerminalEid(@NonNull String companionTerminalEid); 195 196 /** 197 * Sets the ICCID of the primary device eSIM in case of primary SIM not present. Used by 198 * HTTP parameter {@code terminal_eid} if set. 199 * 200 * <p>Used by primary device ODSA operation. 201 * 202 * @param terminalIccid The ICCID of the primary device eSIM in case of primary SIM not 203 * present. 204 * @return The builder. 205 */ 206 @NonNull setTerminalIccid(@onNull String terminalIccid)207 public abstract Builder setTerminalIccid(@NonNull String terminalIccid); 208 209 /** 210 * Sets the eUICC identifier (EID) of the primary device eSIM in case of primary SIM not 211 * present. Used by HTTP parameter {@code terminal_eid} if set. 212 * 213 * <p>Used by primary device ODSA operation. 214 * 215 * @param terminalEid The eUICC identifier (EID) of the primary device eSIM in case of 216 * primary SIM not present. 217 * @return The builder. 218 */ 219 @NonNull setTerminalEid(@onNull String terminalEid)220 public abstract Builder setTerminalEid(@NonNull String terminalEid); 221 222 /** 223 * Sets the unique identifier of the primary device eSIM in case of multiple SIM, like 224 * the IMEI associated with the eSIM. Used by HTTP parameter {@code target_terminal_id} 225 * if set. 226 * 227 * <p>Used by primary device ODSA operation. 228 * 229 * @param targetTerminalId The unique identifier of the primary device eSIM in case of 230 * multiple SIM. 231 * @return The builder. 232 */ 233 @NonNull setTargetTerminalId(@onNull String targetTerminalId)234 public abstract Builder setTargetTerminalId(@NonNull String targetTerminalId); 235 236 /** 237 * Sets the ICCID primary device eSIM in case of multiple SIM. Used by HTTP parameter 238 * {@code target_terminal_iccid} if set. 239 * 240 * <p>Used by primary device ODSA operation. 241 * 242 * @param targetTerminalIccid The ICCID primary device eSIM in case of multiple SIM. 243 * @return The builder. 244 */ 245 @NonNull setTargetTerminalIccid(@onNull String targetTerminalIccid)246 public abstract Builder setTargetTerminalIccid(@NonNull String targetTerminalIccid); 247 248 /** 249 * Sets the eUICC identifier (EID) of the primary device eSIM in case of multiple SIM. 250 * Used by HTTP parameter {@code target_terminal_eid} if set. 251 * 252 * <p>Used by primary device ODSA operation. 253 * 254 * @param targetTerminalEid The eUICC identifier (EID) of the primary device eSIM in 255 * case of multiple SIM. 256 * @return The builder. 257 */ 258 @NonNull setTargetTerminalEid(@onNull String targetTerminalEid)259 public abstract Builder setTargetTerminalEid(@NonNull String targetTerminalEid); 260 261 /** 262 * Sets the notification token used to register for entitlement configuration request 263 * from network. Used by HTTP parameter {@code notif_token} if set. 264 * 265 * <p>Used by primary device ODSA operation. 266 * 267 * @param notificationToken The notification token used to register for entitlement 268 * configuration request from network. 269 * @return The builder. 270 */ 271 @NonNull setNotificationToken(@onNull String notificationToken)272 public abstract Builder setNotificationToken(@NonNull String notificationToken); 273 274 /** 275 * Sets the action associated with the notification token. Used by HTTP parameter 276 * {@code notif_action} if set. 277 * 278 * <p>Used by primary device ODSA operation. 279 * 280 * @param notificationAction The action associated with the notification token. 281 * @return The builder. 282 */ 283 @NonNull setNotificationAction( @otificationAction int notificationAction)284 public abstract Builder setNotificationAction( 285 @NotificationAction int notificationAction); 286 287 /** Returns build the {@link AcquireConfigurationRequest} object. */ 288 @NonNull build()289 public abstract AcquireConfigurationRequest build(); 290 } 291 } 292 293 /** 294 * Acquire configuration response described in GSMA Service Entitlement Configuration section 295 * section 6.5.5 table 40. 296 */ 297 @AutoValue 298 public abstract static class AcquireConfigurationResponse extends OdsaResponse { 299 /** Configuration */ 300 @AutoValue 301 public abstract static class Configuration { 302 /** The configuration type is unknown. */ 303 public static final int CONFIGURATION_TYPE_UNKNOWN = -1; 304 305 /** The configuration is for ODSA primary device. */ 306 public static final int CONFIGURATION_TYPE_PRIMARY = 1; 307 308 /** The configuration is for companion device. */ 309 public static final int CONFIGURATION_TYPE_COMPANION = 2; 310 311 /** The configuration is for server-initiated ODSA. */ 312 public static final int CONFIGURATION_TYPE_ENTERPRISE = 3; 313 314 @Retention(RetentionPolicy.SOURCE) 315 @IntDef({ 316 CONFIGURATION_TYPE_UNKNOWN, 317 CONFIGURATION_TYPE_PRIMARY, 318 CONFIGURATION_TYPE_COMPANION, 319 CONFIGURATION_TYPE_ENTERPRISE 320 }) 321 public @interface ConfigurationType { 322 } 323 324 /** Indicates the configuration type. */ 325 @ConfigurationType type()326 public abstract int type(); 327 328 /** 329 * Integrated Circuit Card Identification - Identifier of the eSIM profile on the 330 * device’s eSIM. {@code null} if an eSIM profile does not exist for the device. 331 */ 332 @Nullable iccid()333 public abstract String iccid(); 334 335 /** 336 * Indicates the applicable companion device service. {@code null} if not for companion 337 * configuration. 338 */ 339 @Nullable 340 @CompanionService companionDeviceService()341 public abstract String companionDeviceService(); 342 343 /** 344 * Service status. 345 * 346 * @see EsimOdsaOperation#SERVICE_STATUS_UNKNOWN 347 * @see EsimOdsaOperation#SERVICE_STATUS_ACTIVATED 348 * @see EsimOdsaOperation#SERVICE_STATUS_ACTIVATING 349 * @see EsimOdsaOperation#SERVICE_STATUS_DEACTIVATED 350 * @see EsimOdsaOperation#SERVICE_STATUS_DEACTIVATED_NO_REUSE 351 */ 352 @OdsaServiceStatus serviceStatus()353 public abstract int serviceStatus(); 354 355 /** 356 * Specifies the minimum interval (in minutes) with which the device application may 357 * poll the ECS to refresh the current {@link #serviceStatus()} using {@link 358 * AcquireConfigurationRequest}. This parameter will be present only when {@link 359 * #serviceStatus()} is {@link EsimOdsaOperation#SERVICE_STATUS_ACTIVATING}. If 360 * parameter is not present or value is 0, this polling procedure is not triggered and 361 * ODSA app will keep waiting for any external action to continue the flow. 362 * 363 * <p>The maximum number of {@link AcquireConfigurationRequest} before sending a {@link 364 * #serviceStatus()} with {@link EsimOdsaOperation#SERVICE_STATUS_DEACTIVATED_NO_REUSE} 365 * will be defined as an ECS configuration variable (MaxRefreshRequest). 366 * 367 * <p>{@link #POLLING_INTERVAL_NOT_AVAILABLE} when polling interval is not available. 368 */ pollingInterval()369 public abstract int pollingInterval(); 370 371 /** 372 * Specifies how and where to download the eSIM profile associated with the device. 373 * Present in case the profile is to be downloaded at this stage. 374 */ 375 @Nullable downloadInfo()376 public abstract DownloadInfo downloadInfo(); 377 378 /** Includes all information collected by the ES of the companion device. */ 379 @Nullable companionDeviceInfo()380 public abstract CompanionDeviceInfo companionDeviceInfo(); 381 382 /** 383 * Specifies how to communicate terms and conditions to the user or query information 384 * from the user without a webview. 385 */ 386 @Nullable messageInfo()387 public abstract MessageInfo messageInfo(); 388 389 /** Returns the builder. */ 390 @NonNull builder()391 public static Builder builder() { 392 return new AutoValue_AcquireConfigurationOperation_AcquireConfigurationResponse_Configuration 393 .Builder() 394 .setType(CONFIGURATION_TYPE_UNKNOWN) 395 .setIccid("") 396 .setServiceStatus(EsimOdsaOperation.SERVICE_STATUS_UNKNOWN) 397 .setPollingInterval(POLLING_INTERVAL_NOT_AVAILABLE); 398 } 399 400 /** The builder of {@link Configuration} */ 401 @AutoValue.Builder 402 public abstract static class Builder { 403 /** 404 * Set the configuration type. 405 * 406 * @param configType The configuration type. 407 * @return The builder. 408 */ 409 @NonNull setType(@onfigurationType int configType)410 public abstract Builder setType(@ConfigurationType int configType); 411 412 /** 413 * Set the iccid. 414 * 415 * @param iccid Integrated Circuit Card Identification - Identifier of the eSIM 416 * profile on the device’s eSIM. 417 * @return The builder. 418 */ 419 @NonNull setIccid(@onNull String iccid)420 public abstract Builder setIccid(@NonNull String iccid); 421 422 /** 423 * Set the applicable companion device service. 424 * 425 * @param companionDeviceService Indicates the applicable companion device service. 426 * @return The builder. 427 */ 428 @NonNull setCompanionDeviceService( @onNull @ompanionService String companionDeviceService)429 public abstract Builder setCompanionDeviceService( 430 @NonNull @CompanionService String companionDeviceService); 431 432 /** 433 * Set the service status. 434 * 435 * @param serviceStatus Service status. 436 * @return The builder. 437 */ 438 @NonNull setServiceStatus(@dsaServiceStatus int serviceStatus)439 public abstract Builder setServiceStatus(@OdsaServiceStatus int serviceStatus); 440 441 /** 442 * Set the polling interval. 443 * 444 * @param pollingInterval The minimum interval (in minutes) with which the device 445 * application may poll the ECS to refresh the current 446 * {@link #serviceStatus()} using 447 * {@link AcquireConfigurationRequest}. 448 * @return The builder. 449 */ 450 @NonNull setPollingInterval(int pollingInterval)451 public abstract Builder setPollingInterval(int pollingInterval); 452 453 /** 454 * Set the download information. 455 * 456 * @param downloadInfo Specifies how and where to download the eSIM profile 457 * associated with the device. 458 * @return The builder. 459 */ 460 @NonNull setDownloadInfo(@onNull DownloadInfo downloadInfo)461 public abstract Builder setDownloadInfo(@NonNull DownloadInfo downloadInfo); 462 463 /** 464 * Set the companion device info. 465 * 466 * @param companionDeviceInfo Includes all information collected by the ES of the 467 * companion device. 468 * @return The builder. 469 */ 470 @NonNull setCompanionDeviceInfo( @onNull CompanionDeviceInfo companionDeviceInfo)471 public abstract Builder setCompanionDeviceInfo( 472 @NonNull CompanionDeviceInfo companionDeviceInfo); 473 474 /** 475 * Set the MSG information. 476 * 477 * @param messageInfo Specifies how to communicate terms and conditions to the user 478 * or query information from the user without a webview. 479 * @return The builder. 480 */ 481 @NonNull setMessageInfo(@onNull MessageInfo messageInfo)482 public abstract Builder setMessageInfo(@NonNull MessageInfo messageInfo); 483 484 /** Returns build the {@link Configuration} object. */ 485 @NonNull build()486 public abstract Configuration build(); 487 } 488 } 489 490 /** 491 * Configurations defined in GSMA Service Entitlement Configuration section 6.5.5. Could be 492 * more than one if multiple companion device(s) associated with the requesting device that 493 * carry a configuration for ODSA. 494 */ 495 @NonNull configurations()496 public abstract ImmutableList<Configuration> configurations(); 497 498 /** Returns the builder. */ 499 @NonNull builder()500 public static Builder builder() { 501 return new AutoValue_AcquireConfigurationOperation_AcquireConfigurationResponse 502 .Builder() 503 .setConfigurations(ImmutableList.of()); 504 } 505 506 /** The builder of {@link AcquireConfigurationResponse} */ 507 @AutoValue.Builder 508 public abstract static class Builder extends OdsaResponse.Builder { 509 /** 510 * Set the configurations 511 * 512 * @param configs Configurations defined in GSMA Service Entitlement Configuration 513 * section 6.5.5. Could be more than one if multiple companion device(s) 514 * associated with the requesting device that carry a configuration for 515 * ODSA. 516 * @return The builder. 517 */ 518 @NonNull setConfigurations( @onNull ImmutableList<Configuration> configs)519 public abstract Builder setConfigurations( 520 @NonNull ImmutableList<Configuration> configs); 521 522 /** Returns build the {@link AcquireConfigurationResponse} object. */ 523 @NonNull build()524 public abstract AcquireConfigurationResponse build(); 525 } 526 } 527 AcquireConfigurationOperation()528 private AcquireConfigurationOperation() { 529 } 530 } 531