Package com.android.identity

Class MobileSecurityObjectGenerator

java.lang.Object

com.android.identity.MobileSecurityObjectGenerator

public class MobileSecurityObjectGenerator
extends java.lang.Object

Helper class for building MobileSecurityObject CBOR as specified ISO/IEC 18013-5 section 9.1.2 Issuer data authentication.

Constructor Summary

Constructors

Constructor	Description
MobileSecurityObjectGenerator(java.lang.String digestAlgorithm, java.lang.String docType, java.security.PublicKey deviceKey)	Constructs a new MobileSecurityObjectGenerator.

Method Summary

Modifier and Type	Method	Description
MobileSecurityObjectGenerator	addDigestIdsForNamespace(java.lang.String nameSpace, java.util.Map<java.lang.Long,byte[]> digestIDs)	Populates the ValueDigests mapping.
byte[]	generate()	Builds the MobileSecurityObject CBOR.
MobileSecurityObjectGenerator	setDeviceKeyAuthorizedDataElements(java.util.Map<java.lang.String,java.util.List<java.lang.String>> authorizedDataElements)	Populates the AuthorizedDataElements portion of the keyAuthorizations within DeviceKeyInfo.
MobileSecurityObjectGenerator	setDeviceKeyAuthorizedNameSpaces(java.util.List<java.lang.String> authorizedNameSpaces)	Populates the AuthorizedNameSpaces portion of the keyAuthorizations within DeviceKeyInfo.
MobileSecurityObjectGenerator	setDeviceKeyInfo(java.util.Map<java.lang.Long,byte[]> keyInfo)	Provides extra info for the mdoc authentication public key as part of the KeyInfo portion of the DeviceKeyInfo.
MobileSecurityObjectGenerator	setValidityInfo(Timestamp signed, Timestamp validFrom, Timestamp validUntil, Timestamp expectedUpdate)	Sets the ValidityInfo structure which contains information related to the validity of the MSO and its signature.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MobileSecurityObjectGenerator

public MobileSecurityObjectGenerator(@NonNull
                                     java.lang.String digestAlgorithm,
                                     @NonNull
                                     java.lang.String docType,
                                     @NonNull
                                     java.security.PublicKey deviceKey)

Constructs a new MobileSecurityObjectGenerator.

Parameters:

digestAlgorithm - The digest algorithm identifier. Must be one of {"SHA-256", "SHA-384", "SHA-512"}.

docType - The document type.

deviceKey - The public part of the key pair used for mdoc authentication.

Throws:

java.lang.IllegalArgumentException - if the digestAlgorithm is not one of {"SHA-256", "SHA-384", "SHA-512"}.

Method Detail

addDigestIdsForNamespace

@NonNull
public MobileSecurityObjectGenerator addDigestIdsForNamespace(@NonNull
                                                              java.lang.String nameSpace,
                                                              @NonNull
                                                              java.util.Map<java.lang.Long,byte[]> digestIDs)

Populates the ValueDigests mapping. This must be called at least once before generating since ValueDigests must be non-empty.

Parameters:

nameSpace - The namespace.

digestIDs - A non-empty mapping between a DigestID and a Digest.

Returns:

The MobileSecurityObjectGenerator.

Throws:

java.lang.IllegalArgumentException - if the digestIDs is empty.

setDeviceKeyAuthorizedNameSpaces

@NonNull
public MobileSecurityObjectGenerator setDeviceKeyAuthorizedNameSpaces(@NonNull
                                                                      java.util.List<java.lang.String> authorizedNameSpaces)

Populates the AuthorizedNameSpaces portion of the keyAuthorizations within DeviceKeyInfo. This gives authorizations to full namespaces included in the authorizedNameSpaces array. If authorization is given for a full namespace, that namespace shall not be included in setDeviceKeyAuthorizedDataElements(Map).

Parameters:

authorizedNameSpaces - A list of namespaces which should be given authorization.

Returns:

The MobileSecurityObjectGenerator.

Throws:

java.lang.IllegalArgumentException - if the authorizedNameSpaces does not meet the constraints.

setDeviceKeyAuthorizedDataElements

@NonNull
public MobileSecurityObjectGenerator setDeviceKeyAuthorizedDataElements(@NonNull
                                                                        java.util.Map<java.lang.String,java.util.List<java.lang.String>> authorizedDataElements)

Populates the AuthorizedDataElements portion of the keyAuthorizations within DeviceKeyInfo. This gives authorizations to data elements included in the authorizedDataElements mapping. If a namespace is included here, then it should not be included in setDeviceKeyAuthorizedNameSpaces(List)

Parameters:

authorizedDataElements - A mapping from namespaces to a list of DataElementIdentifier

Returns:

The MobileSecurityObjectGenerator.

Throws:

java.lang.IllegalArgumentException - if authorizedDataElements does not meet the constraints.

setDeviceKeyInfo

@NonNull
public MobileSecurityObjectGenerator setDeviceKeyInfo(@NonNull
                                                      java.util.Map<java.lang.Long,byte[]> keyInfo)

Provides extra info for the mdoc authentication public key as part of the KeyInfo portion of the DeviceKeyInfo.

Parameters:

keyInfo - A mapping to represent additional key information.

Returns:

The MobileSecurityObjectGenerator.

setValidityInfo

@NonNull
public MobileSecurityObjectGenerator setValidityInfo(@NonNull
                                                     Timestamp signed,
                                                     @NonNull
                                                     Timestamp validFrom,
                                                     @NonNull
                                                     Timestamp validUntil,
                                                     @Nullable
                                                     Timestamp expectedUpdate)

Sets the ValidityInfo structure which contains information related to the validity of the MSO and its signature. This must be called before generating since this a required component of the MobileSecurityObject.

Parameters:

signed - The timestamp at which the MSO signature was created.

validFrom - The timestamp before which the MSO is not yet valid. This shall be equal or later than the signed element.

validUntil - The timestamp after which the MSO is no longer valid. This shall be later than the validFrom element.

expectedUpdate - Optional: if provided, represents the timestamp at which the issuing authority infrastructure expects to re-sign the MSO, else, null

Returns:

The MobileSecurityObjectGenerator.

Throws:

java.lang.IllegalArgumentException - if the times are do not meet the constraints.

generate

@NonNull
public byte[] generate()

Builds the MobileSecurityObject CBOR.

It's mandatory to call addDigestIdsForNamespace(String, Map) and setValidityInfo(Timestamp, Timestamp, Timestamp, Timestamp) before this call.

Returns:

the bytes of MobileSecurityObject CBOR.

Throws:

java.lang.IllegalStateException - if required data hasn't been set using the setter methods on this class.