org.cyclos.services.access

Interface TokenService

All Superinterfaces:

CRUDService<TokenDTO,TokenData,TokenDataParams>, Service

All Known Subinterfaces:

TokenServiceLocal

All Known Implementing Classes:

TokenServiceSecurity

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

Service for managing tokens, NFC tokens and NFC devices

Author:

jcomas, ameyer

Method Summary

Modifier and Type	Method and Description
void	activatePending(@NotNull java.lang.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 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 adssigend and is pending by activation) it activates only. This method can be used only by members (i.e.
SerializableInputStream	barcode(@NotNull TokenBarcodeParams params) Returns a barcode image of the token
void	block(@NotNull java.lang.Long tokenId) Blocks the given token
void	cancel(@NotNull java.lang.Long tokenId) Cancels the given token
void	cancelNFCToken(@NotNull TokenActionDTO dto) Cancels the given NFC token.
SerializableInputStream	exportToCSV(@NotNull TokenQuery query) Returns a CSV version of all returned tokens
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.
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	unblock(@NotNull java.lang.Long tokenId) Unblocks the given token

Methods inherited from interface org.cyclos.services.CRUDService

getData, getDataForNew, load, remove, removeAll, save

Method Detail

activatePending

void activatePending(@NotNull
                     @NotNull java.lang.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 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 adssigend 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.

Throws:

FrameworkException

MaxTokenActivationAttemptsException

InvalidTokenException

See Also:

#activatePending(Long)} for admins/brokers.

barcode

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

Returns a barcode image of the token

Throws:

FrameworkException

block

void block(@NotNull
           @NotNull java.lang.Long tokenId)
    throws FrameworkException

Blocks the given token

Throws:

FrameworkException

cancel

void cancel(@NotNull
            @NotNull java.lang.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

exportToCSV

SerializableInputStream exportToCSV(@NotNull
                                    @NotNull TokenQuery query)
                             throws FrameworkException

Returns a CSV version of all returned tokens

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)

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 operation can only be done by admins or brokers over tokens of managed users

Throws:

FrameworkException

QueryParseException

unblock

void unblock(@NotNull
             @NotNull java.lang.Long tokenId)
      throws FrameworkException

Unblocks the given token

Throws:

FrameworkException