org.cyclos.services.access

Interface TokenService

All Superinterfaces:

CRUDService<TokenDTO,TokenData,TokenDataParams>, Service

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(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(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(TokenBarcodeParams params) Returns a barcode image of the token
void	block(java.lang.Long tokenId) Blocks the given token
void	cancel(java.lang.Long tokenId) Cancels the given token
void	cancelNFCToken(TokenActionDTO dto) Cancels the given NFC token.
SerializableInputStream	exportToCSV(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(TokenPrincipalTypeVO tokenType, UserLocatorVO user) Returns data for listing tokens of a given type and user
PersonalizeNFCTagData	getPersonalizeNFCTagData(TokenPrincipalTypeVO tokenType, 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(NFCTagInitializeDTO dto) Initializes and optionally personalize a NFC tag with the given data.
void	personalizeNFCTag(NFCTagPersonalizeDTO dto) Personalizes a NFC tag for the given user.
ExternalNFCTagAuthenticateData	requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO dto) This method must be invoked to start a mutual authentication process between the server and the NFC tag (e.g.
void	requestNewOTPForPersonalizeNFCTag(UserLocatorVO locator, TokenPrincipalTypeVO tokenTypeVO, 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(TokenQuery query) Searches for tokens.
void	unblock(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
                     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
            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
                                TokenBarcodeParams params)
                         throws FrameworkException

Returns a barcode image of the token

Throws:

FrameworkException

block

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

Blocks the given token

Throws:

FrameworkException

cancel

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

Cancels the given token

Throws:

FrameworkException

cancelNFCToken

void cancelNFCToken(@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
                                    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
                           TokenPrincipalTypeVO tokenType,
                           @NotNull
                           UserLocatorVO user)
                    throws FrameworkException

Returns data for listing tokens of a given type and user

Throws:

FrameworkException

getPersonalizeNFCTagData

PersonalizeNFCTagData getPersonalizeNFCTagData(@NotNull
                                               TokenPrincipalTypeVO tokenType,
                                               @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
                                        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
                       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
                                                              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
                                       UserLocatorVO locator,
                                       @NotNull
                                       TokenPrincipalTypeVO tokenTypeVO,
                                       @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
                     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
             java.lang.Long tokenId)
      throws FrameworkException

Unblocks the given token

Throws:

FrameworkException