Package org.cyclos.services.access

Interface TokenService

All Superinterfaces:

CRUDService<TokenDTO,TokenData,TokenDataParams>, Service

All Known Subinterfaces:

TokenServiceLocal

All Known Implementing Classes:

TokenServiceImpl, TokenServiceSecurity

public interface TokenService
extends CRUDService<TokenDTO,TokenData,TokenDataParams>

Service for managing tokens, NFC tokens and NFC devices

Method Summary

Modifier and Type	Method	Description
Long	activate(@NotNull TokenActionDTO dto, UserLocatorVO locator)	Searches for a token with the given type and value specified in the TokenActionDTO parameter. The token's status must be TokenStatus.UNASSIGNED orTokenStatus.PENDING_ACTIVATION but assigned to the logged user or one of its operators. If the token is unassigned then this method assigns it to the user specified by the UserLocatorVO parameter and change its status to TokenStatus.ACTIVE. Otherwise (the token is already assigned and is pending by activation) it activates only. This method can be used only by members (i.e.
void	activatePending(@NotNull Long tokenId)	Activates an already assigned token with status TokenStatus.PENDING_ACTIVATION. This operation can only be done by admins/brokers over tokens of managed users or member over tokens of its operators with permission to activate the corresponding TokenPrincipalTypeVO.
void	assign(@NotNull Long tokenId, @NotNull UserLocatorVO user)	Assigns a pending token to a user, leaving it in pending status The token status must be TokenStatus.UNASSIGNED.
SerializableInputStream	barcode(@NotNull TokenBarcodeParams params)	Returns a barcode image of the token
void	block(@NotNull Long tokenId)	Blocks the given token
void	cancel(@NotNull Long tokenId)	Cancels the given token
void	cancelNFCToken(@NotNull TokenActionDTO dto)	Cancels the given NFC token.
DeviceConfirmationVO	createDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO)	Creates a new pending device confirmation for the specified user.
SerializableInputStream	deviceConfirmationBarcodeForPersonalizeNFCTag(UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, DeviceConfirmationBarcodeParams params)	Generates a two-dimensional barcode (QR code), only if the confirmation was not already approved nor rejected for the given payer.
FileInfo	exportTokens(@NotNull ExportFormatVO format, @NotNull TokenQuery query)	Exports the token search results to file
InitializeNFCTagData	getInitializeNFCTagData()	Returns data with the token types available to initialize a blank NFC tag. The available tokens to personalize the tag are returned too to allow initialization and personalization at the same time.
TokensListData	getListData(@NotNull TokenPrincipalTypeVO tokenType, @NotNull UserLocatorVO user)	Returns data for listing tokens of a given type and user
PersonalizeNFCTagData	getPersonalizeNFCTagData(@NotNull TokenPrincipalTypeVO tokenType, @NotNull UserLocatorVO locator)	Returns data needed to personalize a NFC tag for the specified type and user. The PersonalizeNFCTagData.CONFIRMATION_PASSWORD_INPUT will be null if the logged user manages the given user.
TokenSearchData	getSearchData(TokenPrincipalTypeVO tokenType)	Returns data for searching tokens
InitializeNFCTagResult	initializeNFCTag(@NotNull NFCTagInitializeDTO dto)	Initializes and optionally personalize a NFC tag with the given data.
void	personalizeNFCTag(@NotNull NFCTagPersonalizeDTO dto)	Personalizes a NFC tag for the given user.
void	removeDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, String deviceConfirmationId)	Removes a device confirmation for the given user.
ExternalNFCTagAuthenticateData	requestForExternalAuthenticate(@NotNull ExternalNFCTagAuthenticateDTO dto)	This method must be invoked to start a mutual authentication process between the server and the NFC tag (e.g.
void	requestNewOTPForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, @NotNull SendMedium medium)	Generates a new OTP (removing any previous password, if any) and sends it to the user by the specified medium using the confirmation password type set for the BuiltInChannel.POS channel for the specified user. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.
Page<TokenVO>	search(@NotNull TokenQuery query)	Searches for tokens.
void	setActivationDeadline(@NotNull Long tokenId, DateTime date)	Changes the token activation deadline date.
void	setExpiryDate(@NotNull Long tokenId, DateTime date)	Changes the token expiry date.
void	unblock(@NotNull Long tokenId)	Unblocks the given token
DeviceConfirmationVO	viewDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, String deviceConfirmationId)	Loads the details of a confirmation belonging to the given user.

Methods inherited from interface org.cyclos.services.CRUDService

getData, getDataForNew, load, remove, removeAll, save

Method Detail

activate

Long activate(@NotNull
              @NotNull TokenActionDTO dto,
              UserLocatorVO locator)
       throws FrameworkException,
              MaxTokenActivationAttemptsException,
              InvalidTokenException

Searches for a token with the given type and value specified in the TokenActionDTO parameter.
The token's status must be TokenStatus.UNASSIGNED orTokenStatus.PENDING_ACTIVATION but assigned to the logged user or one of its operators.
If the token is unassigned then this method assigns it to the user specified by the UserLocatorVO parameter and change its status to TokenStatus.ACTIVE.
Otherwise (the token is already assigned and is pending by activation) it activates only.
This method can be used only by members (i.e. not administrators) with permission to activate the corresponding TokenPrincipalTypeVO. For administrators / brokers, see activatePending(Long)

Throws:

FrameworkException

MaxTokenActivationAttemptsException

InvalidTokenException

activatePending

void activatePending(@NotNull
                     @NotNull Long tokenId)
              throws FrameworkException

Activates an already assigned token with status TokenStatus.PENDING_ACTIVATION.
This operation can only be done by admins/brokers over tokens of managed users or member over tokens of its operators with permission to activate the corresponding TokenPrincipalTypeVO.

Throws:

FrameworkException

assign

void assign(@NotNull
            @NotNull Long tokenId,
            @NotNull
            @NotNull UserLocatorVO user)
     throws FrameworkException

Assigns a pending token to a user, leaving it in pending status The token status must be TokenStatus.UNASSIGNED.

Throws:

FrameworkException

barcode

SerializableInputStream barcode(@NotNull
                                @NotNull TokenBarcodeParams params)
                         throws FrameworkException

Returns a barcode image of the token

Throws:

FrameworkException

block

void block(@NotNull
           @NotNull Long tokenId)
    throws FrameworkException

Blocks the given token

Throws:

FrameworkException

cancel

void cancel(@NotNull
            @NotNull Long tokenId)
     throws FrameworkException

Cancels the given token

Throws:

FrameworkException

cancelNFCToken

void cancelNFCToken(@NotNull
                    @NotNull TokenActionDTO dto)
             throws FrameworkException

Cancels the given NFC token. Admins and brokers with permissions can cancel a NFC token of type TokenType.NFC_TAG.
In case of a NFC token of type TokenType.NFC_DEVICE only the logged user can cancel its own token.

Throws:

FrameworkException

createDeviceConfirmationForPersonalizeNFCTag

DeviceConfirmationVO createDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                                  @NotNull UserLocatorVO locator,
                                                                  @NotNull
                                                                  @NotNull TokenPrincipalTypeVO tokenTypeVO)
                                                           throws FrameworkException

Creates a new pending device confirmation for the specified user. The logged user will be notified after the confirmation was processed. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

deviceConfirmationBarcodeForPersonalizeNFCTag

SerializableInputStream deviceConfirmationBarcodeForPersonalizeNFCTag(UserLocatorVO locator,
                                                                      @NotNull
                                                                      @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                                      DeviceConfirmationBarcodeParams params)
                                                               throws FrameworkException

Generates a two-dimensional barcode (QR code), only if the confirmation was not already approved nor rejected for the given payer. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

exportTokens

FileInfo exportTokens(@NotNull
                      @NotNull ExportFormatVO format,
                      @NotNull
                      @NotNull TokenQuery query)
               throws FrameworkException

Exports the token search results to file

Throws:

FrameworkException

getInitializeNFCTagData

InitializeNFCTagData getInitializeNFCTagData()
                                      throws FrameworkException

Returns data with the token types available to initialize a blank NFC tag.
The available tokens to personalize the tag are returned too to allow initialization and personalization at the same time. Only allowed for managers (Brokers & Administrators).

Throws:

FrameworkException

See Also:

initializeNFCTag(NFCTagInitializeDTO)

getListData

TokensListData getListData(@NotNull
                           @NotNull TokenPrincipalTypeVO tokenType,
                           @NotNull
                           @NotNull UserLocatorVO user)
                    throws FrameworkException

Returns data for listing tokens of a given type and user

Throws:

FrameworkException

getPersonalizeNFCTagData

PersonalizeNFCTagData getPersonalizeNFCTagData(@NotNull
                                               @NotNull TokenPrincipalTypeVO tokenType,
                                               @NotNull
                                               @NotNull UserLocatorVO locator)
                                        throws FrameworkException

Returns data needed to personalize a NFC tag for the specified type and user.
The PersonalizeNFCTagData.CONFIRMATION_PASSWORD_INPUT will be null if the logged user manages the given user. The PersonalizeNFCTagData.TOKEN_TYPE is the token principal type the tag was initialized for.

Throws:

FrameworkException

getSearchData

TokenSearchData getSearchData(TokenPrincipalTypeVO tokenType)
                       throws FrameworkException

Returns data for searching tokens

Throws:

FrameworkException

initializeNFCTag

InitializeNFCTagResult initializeNFCTag(@NotNull
                                        @NotNull NFCTagInitializeDTO dto)
                                 throws FrameworkException,
                                        TokenAlreadyInUseException

Initializes and optionally personalize a NFC tag with the given data. If the TokenActionWithUserDTO.getUser() is not null then the token will be personalized for that user too. Returns the private keys (PICC Master Key (i.e. PMK), Application Master Key (i.e. AMK) and Operational key) to be stored into the tag.
Only allowed for managers (Brokers & Administrators).

Throws:

FrameworkException

TokenAlreadyInUseException

personalizeNFCTag

void personalizeNFCTag(@NotNull
                       @NotNull NFCTagPersonalizeDTO dto)
                throws FrameworkException,
                       TokenAlreadyInUseException

Personalizes a NFC tag for the given user. If the logged user doesn't manages the user then the confirmation password of that user is required. This method requires a successful previous external authentication ( requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO))
The required NFCTagPersonalizeDTO.CYCLOS_CHALLENGE is the encrypted (hexadecimal string) challenge generated by the server (returned in the previous external authenticate) used to ensure the tag presence (internal authenticate)

Throws:

FrameworkException

TokenAlreadyInUseException

See Also:

requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO)

removeDeviceConfirmationForPersonalizeNFCTag

void removeDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                  @NotNull UserLocatorVO locator,
                                                  @NotNull
                                                  @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                  String deviceConfirmationId)
                                           throws FrameworkException

Removes a device confirmation for the given user. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

requestForExternalAuthenticate

ExternalNFCTagAuthenticateData requestForExternalAuthenticate(@NotNull
                                                              @NotNull ExternalNFCTagAuthenticateDTO dto)
                                                       throws FrameworkException

This method must be invoked to start a mutual authentication process between the server and the NFC tag (e.g. a card) to prove that both share the same secret key.
The authentication process is carried out in the following order:

• Validate the identity of the server: external authenticate
• Validate the identity of the NFc tag: internal authenticate

Parameters:

dto - contains the token type id (required), the token value (optional) and an encrypted challenge (required) generated by the tag in hexadecimal notation. If the token value is null then means the authentication process will be using the PICC Master Key (PMK).

Returns:

data containing the following:

• ExternalNFCTagAuthenticateData.CYCLOS_CHALLENGE: encrypted data (hexadecimal string) containing both: a new challenge generated by the server (used to validate the identity of the NFC tag, internal authenticate) and the original challenge generated by the tag processed according to the tag's authentication process. The (processed) original tag challenge will be used by the NFC tag to complete the server identity validation (external authenticate).
• ExternalNFCTagAuthenticateData.SESSION_KEY: A session key needed by the tag to allow send enciphered data to be written into the NFC tag

Throws:

FrameworkException

requestNewOTPForPersonalizeNFCTag

void requestNewOTPForPersonalizeNFCTag(@NotNull
                                       @NotNull UserLocatorVO locator,
                                       @NotNull
                                       @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                       @NotNull
                                       @NotNull SendMedium medium)
                                throws FrameworkException,
                                       SmsSendingException

Generates a new OTP (removing any previous password, if any) and sends it to the user by the specified medium using the confirmation password type set for the BuiltInChannel.POS channel for the specified user.
It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

medium - the medium used to send the OTP.

Throws:

SmsSendingException - only if medium is SendMedium.SMS and the OTP could not be sent to any enabled for sms phone.

FrameworkException

search

Page<TokenVO> search(@NotNull
                     @NotNull TokenQuery query)
              throws FrameworkException,
                     QueryParseException

Searches for tokens. This method can only be user by administrators or brokers.

Throws:

FrameworkException

QueryParseException

setActivationDeadline

void setActivationDeadline(@NotNull
                           @NotNull Long tokenId,
                           DateTime date)
                    throws FrameworkException

Changes the token activation deadline date. The token status must be either TokenStatus.PENDING_ACTIVATION or TokenStatus.ACTIVATION_EXPIRED.

Throws:

FrameworkException

setExpiryDate

void setExpiryDate(@NotNull
                   @NotNull Long tokenId,
                   DateTime date)
            throws FrameworkException

Changes the token expiry date. The token status must be either TokenStatus.ACTIVE, TokenStatus.BLOCKED or TokenStatus.EXPIRED.

Throws:

FrameworkException

unblock

void unblock(@NotNull
             @NotNull Long tokenId)
      throws FrameworkException

Unblocks the given token

Throws:

FrameworkException

viewDeviceConfirmationForPersonalizeNFCTag

DeviceConfirmationVO viewDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                                @NotNull UserLocatorVO locator,
                                                                @NotNull
                                                                @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                                String deviceConfirmationId)
                                                         throws FrameworkException

Loads the details of a confirmation belonging to the given user. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException