API documentation

MoppLib / SkSigningLib API calls and types

MoppLib

SkSigningLib

Mobile-ID

Mobile-ID service
- RequestSignature
  - getCertificate
- Session
  - getSession
  - getSessionStatus
- Validate signature (MoppLib)
  - isSignatureValid

Smart-ID

Smart-ID service
- getCertificate * getSignature * getSessionStatus
- Validate signature (MoppLib)
  - isSignatureValid
Constants and types
- Block type definitions
Request objects
Response objects

MoppLib Manager

First-time setup and version info

setup

MoppLibManager.h, @interface MoppLibManager

Syntax

- (void)setupWithSuccess:(VoidBlock)success andFailure:(FailureBlock)failure usingTestDigiDocService:(BOOL)useTestDDS andTSUrl:(NSString *)tsUrl withMoppConfiguration:(MoppLibConfiguration *)moppConfiguration;

Parameters

Parameter	Type	Description
success	`EmptySuccessBlock`	Called by the `setupWithSuccess` when setup is completed successfully
failure	`FailureBlock`	Called when something goes wrong with the setup
useTestDDS	`BOOL`	Set to `YES` when need to use Digidoc Test Service
andTSUrl	`NSString`	TS URL to use with Digidoc Service
moppConfiguration	`MoppLibConfiguration`	Central configuration to get data from

Return value

None

Remarks

Preliminary setup for MoppLib. Digidocpp is configured and initialized. TLS certificates cache is updated.

This method should be called before any other API call

moppLibVersion

MoppLibManager.h, @interface MoppLibManager

Syntax

- (NSString *)moppLibVersion;

Parameters

None

Return value

Type	Description
`NSString*`	Textual representation of MoppLib version

Remarks

This method returns textual representation of MoppLib version

libdigidocppVersion

MoppLibManager.h, @interface MoppLibManager

Syntax

- (NSString *)libdigidocppVersion;

Parameters

None

Return value

Type	Description
`NSString*`	Textual representation of libdigidocpp version

Remarks

This method returns textual representation of libdigidocpp version

Container Actions

Signed container actions:

creating container
validating container
removing and adding signature to and from container
adding and removing data files to and from container
extracting data files from container

openContainer

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)openContainerWithPath:(NSString *)containerPath success:(ContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	File path to existing container file
success	`ContainerBlock`	Called when container is successfully validated; has `MoppLibContainer` object as a parameter
failure	`FailureBlock`	Called when invalidating container fails; has `NSError*` object as parameter for additional information

Return value

None

Remarks

This method is used to validate container. If container is successfully validated then MoppLibContainer object is returned as ContainerBlock parameter

createContainer

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)createContainerWithPath:(NSString *)containerPath withDataFilePaths:(NSArray *)dataFilePaths success:(ContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	File path for new container
dataFilePaths	`NSArray*`	Array of strings containing file paths to data files for including to created container
success	`ContainerBlock`	Called when container is successfully created; has `MoppLibContainer` object as a parameter
failure	`FailureBlock`	Called when creating new container fails; has `NSError*` object as parameter for additional information

Return value

None

Remarks

This method creates a new container and validates it. MoppLibContainer object is returned from ContainerBlock if operations is successful

addDataFilesToContainer

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)addDataFilesToContainerWithPath:(NSString *)containerPath withDataFilePaths:(NSArray *)dataFilePaths success:(ContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	Existing file path to container
dataFilePaths	`NSArray*`	Array of data file paths to add to container
success	`ContainerBlock`	Called when data files are successfully added to container; has `MoppLibContainer` object as a parameter
failure	`FailureBlock`	Called when adding data files to container fails; has `NSError*` object as parameter for additional error information

Return value

None

Remarks

This method adds files to container

removeDataFileFromContainer

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)removeDataFileFromContainerWithPath:(NSString *)containerPath atIndex:(NSUInteger)dataFileIndex success:(ContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	Path to existing container file
dataFileIndex	`NSUInteger`	Index to data file to remove from container
success	`ContainerBlock`	Called when data file is successfully removed from container; has `MoppLibContainer` object as a parameter
failure	`FailureBlock`	Called when removing data file from container fails; has `NSError*` object as parameter for additional error information

Return value

None

Remarks

This method removes data file from container

getContainers

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)getContainersWithSuccess:(void(^)(NSArray *containers))success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`void(^)(NSArray *containers)`	Called when data file is successfully removed from container; has array of `MoppLibContainer` type objects as a parameter
failure	`FailureBlock`	Called when receiving available containers fail; has `NSError*` object as parameter for additional error information

Return value

None

Remarks

This method receives all available containers

removeSignature

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)removeSignature:(MoppLibSignature *)moppSignature fromContainerWithPath:(NSString *)containerPath success:(ContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
moppSignature	`MoppLibSignature`	Signature to remove from container
containerPath	`NSString*`	Path to existing container file
success	`ContainerBlock`	Called when signature is successfully removed from container; has `MoppLibContainer` object as a parameter
failure	`FailureBlock`	Called when removing signature from container fails; has `NSError*` object as parameter for additional error information

Return value

None

Remarks

This method removes signature from container

saveDataFile

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)container:(NSString *)containerPath saveDataFile:(NSString *)fileName to:(NSString *)path success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	Path to existing container file
filename	`NSString*`	File name to save data file as
path	`NSString*`	Folder path to save data file to
success	`VoidBlock`	Called when data file is successfully extracted from container and saved to specified location
failure	`FailureBlock`	Called when extracting data file from container fails to saving data file to specified location fails; has `NSError*` object as parameter for additional error information

Return value

None

Remarks

This method extracts data file from the container and saves it to the specified location

addSignature

MoppLibContainerActions.h, @interface MoppLibContainerActions

Syntax

- (void)addSignature:(NSString *)containerPath withPin2:(NSString*)pin2 success:(void(^)(MoppLibContainer *container, BOOL signatureWasAdded))success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
containerPath	`NSString*`	File path to existing container
pin2	`NSString*`	PIN2 code
success	`void(^)(MoppLibContainer *container, BOOL signatureWasAdded)`	Returns `MoppLibContainer` as a parameter; signatureWasAdded indicates whether signature was added
failure	`FailureBlock`	Called when adding signature to container fails;

Return value

None

Remarks

This method adds a signature to the container

Card Actions

ID-card actions

minimalCardPersonalData

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)minimalCardPersonalDataWithSuccess:(PersonalDataBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`PersonalDataBlock`	Called when minimal card personal data is received successfully
failure	`FailureBlock`	Called when receiving minimal card personal data fails

Return value

None

Remarks

This method receives minimal card personal data

cardPersonalData

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)cardPersonalDataWithSuccess:(PersonalDataBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`PersonalDataBlock`	Called when receiving card personal data succeeds
failure	`FailureBlock`	Called when receiving card personal data fails

Return value

None

Remarks

This method receives card personal data

isReaderConnected

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (BOOL)isReaderConnected;

Parameters

None

Return value

Type	Description
`BOOL`	`YES` if reader connected, `NO` otherwise

Remarks

This method checks if reader is connected

isCardInserted

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)isCardInserted:(BoolBlock) completion;

Parameters

Parameter	Type	Description
completion	`BoolBlock`	`YES` if card is inserted, `NO` otherwise

Return value

None

Remarks

This method checks if card is inserted into the reader

signingCertificate

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)signingCertificateWithSuccess:(CertDataBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`CertDataBlock`	Called when information about signing certificate is successfully received
failure	`FailureBlock`	Called when receiving information about signing certificate fails

Return value

None

Remarks

This method provides information about signing certificate

authenticationCertificate

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)authenticationCertificateWithSuccess:(CertDataBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`CertDataBlock`	Called when information about authentication certificate is successfully received
failure	`FailureBlock`	Called when receiving information about authentication certificate fails

Return value

None

Remarks

This method provides information about authentication certificate

pin1RetryCount

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)pin1RetryCountWithSuccess:(NumberBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`NumberBlock`	Success block returning PIN1 retry count as NSNumber
failure	`FailureBlock`	Called when something went wrong requesting PIN1 retry count

Return value

None

Remarks

This method provides number of PIN1 attempts left before PIN1 is blocked.

pin2RetryCount

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)pin1RetryCountWithSuccess:(NumberBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`NumberBlock`	Success block returning PIN2 retry count as NSNumber
failure	`FailureBlock`	Called when something went wrong requesting PIN2 retry count

Return value

None

Remarks

This method provides number of PIN2 attempts left before PIN2 is blocked.

pukRetryCount

MoppLibCardActions.h, @interface MoppLibCardActions

Syntax

+ (void)pukRetryCountWithSuccess:(NumberBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
success	`NumberBlock`	Success block returning PUK retry count as NSNumber
failure	`FailureBlock`	Called when something went wrong requesting PUK retry count

Return value

None

Remarks

This method provides number of PUK attempts left before PUK is blocked.

Pin Actions

changePuk

MoppLinPinActions.h, @interface MoppLinPinActions

Syntax

+ (void)changePukTo:(NSString *)newPuk withOldPuk:(NSString *)oldPuk success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
newPuk	`NSString*`	New PUK code
oldPuk	`NSString*`	Current PUK code
success	`VoidBlock`	Called when PUK is successfully changed to a new one
failure	`FailureBlock`	Called when something went wrong changing PUK code

Return value

None

Remarks

This method changes PUK code from old to new one

changePin1WithPin1

MoppLinPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)changePin1To:(NSString *)newPin1 withOldPin1:(NSString *)oldPin1 success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
newPin1	`NSString*`	New PIN1 code
oldPin1	`NSString*`	Old PIN1 code
success	`VoidBlock`	Called when PIN1 is changed successfully using PIN1
failure	`FailureBlock`	Called when something went wrong changing PIN1 code

Return value

None

Remarks

This method changes PIN1 code using old PIN1

changePin1WithPuk

MoppLibPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)changePin1To:(NSString *)newPin1 withPuk:(NSString *)puk success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
newPin1	`NSString*`	New PIN1 code
puk	`NSString*`	PUK code
success	`SuccessBlock`	Called when PIN1 is successfully changed with PUK code
failure	`FailureBlock`	Called something went wrong changing PIN1 with PUK code

Return value

None

Remarks

This method changes PIN1 code using PUK code

changePin2WithPin2

MoppLibPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)changePin2To:(NSString *)newPin2 withOldPin2:(NSString *)oldPin2 success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
newPin2	`NSString*`	New PIN2 code
oldPin2	`NSString*`	Old PIN2 code
success	`SuccessBlock`	Called when PIN2 is successfully changed with PIN2 code
failure	`FailureBlock`	Called when something went wrong changing PIN2 code

Return value

None

Remarks

This method changes PIN2 code using old PIN2

changePin2WithPuk

MoppLibPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)changePin2To:(NSString *)newPin2 withPuk:(NSString *)puk success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
newPin2	`NSString*`	New PIN2 code
puk	`NSString*`	PUK code
success	`SuccessBlock`	Called when PIN2 is successfully changed
failure	`FailureBlock`	Called when PIN2 changing failed

Return value

None

Remarks

This method changes PIN2 code using PUK code

unblockPin1

MoppLibPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)unblockPin1WithPuk:(NSString *)puk newPin1:(NSString *)newPin1 success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
puk	`NSString*`	PUK code
newPin1	`NSString*`	new PIN1 code
success	`SuccessBlock`	Called when PIN1 code successfully unblocked
failure	`FailureBlock`	Called when PIN1 code unblocking fails

Return value

None

Remarks

This method unblocks PIN1 using PUK code

unblockPin2

MoppLibPinActions.h, @interface MoppLibPinActions

Syntax

+ (void)unblockPin2WithPuk:(NSString *)puk newPin2:(NSString *)newPin2 success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
puk	`NSString*`	PUK code
newPin2	`NSString*`	New PIN2 code
success	`SuccessBlock`	Called when PIN2 code successfully unblocked
failure	`FailureBlock`	Called when PIN2 code unblocking fails

Return value

None

Remarks

This method unblocks PIN2 code using PUK

Crypto Actions

searchLdapData

MoppLibCryptoActions.h, @interface MoppLibCryptoActions

Syntax

- (void)searchLdapData:(NSString *)identifier success:(LdapBlock)success failure:(FailureBlock)failure configuration:(MoppLdapConfiguration *)moppLdapConfiguration;

Parameters

Parameter	Type	Description
identifier	`NSString*`	LDAP search request identifier
success	`LdapBlock`	Called on successful completion of action.
failure	`FailureBlock`	Block to be called when action fails. Includes error
moppLdapConfiguration	`MoppLdapConfiguration`	LDAP configuration from central configuration

Return value

None

Remarks

This method is used to search ldap data

encryptData

MoppLibCryptoActions.h, @interface MoppLibCryptoActions

Syntax

- (void)encryptData:(NSString *)fullPath withDataFiles:(NSArray*)dataFiles withAddressees:(NSArray*)addressees success:(VoidBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
fullPath	`NSString*`	Full path of encrypted file
dataFiles	`NSArray*`	Array of `CryptoDataFile` associated with data files to be encrypted
addressees	`NSArray*`	Array of `Addressee` associated with addressees of the encrypted file
success	`VoidBlock`	Called when file is encrypted successfully
failure	`FailureBlock`	Called when something went wrong with encryption

Return value

None

Remarks

This method is used to encrypt data

decryptData

MoppLibCryptoActions.h, @interface MoppLibCryptoActions

Syntax

- (void)decryptData:(NSString *)fullPath withPin1:(NSString*)pin1 success:(DecryptedDataBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
fullPath	`NSString*`	Full path of encrypted file
pin1	`NSString*`	PIN1 code
success	`DecryptedDataBlock`	Called when file is decrypted successfully
failure	`FailureBlock`	Called when something went wrong with decryption

Return value

None

Remarks

This method is used to decrypt CDOC

parseCdocInfo

MoppLibCryptoActions.h, @interface MoppLibCryptoActions

Syntax

- (void)parseCdocInfo:(NSString *)fullPath success:(CdocContainerBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
fullPath	`NSString*`	Full path of CDOC container
success	`CdocContainerBlock`	Called when file is parsed successfully
failure	`FailureBlock`	Called when something went wrong with parsing

Return value

None

Remarks

This method is used to parse and get info of CDOC container

Smart-card readers manager

startDiscoveringReaders

MoppLibCardReaderManager.h, @interface MoppLibCardReaderManager

Syntax

- (void)startDiscoveringReaders;

Parameters

None

Return value

None

Remarks

Starts supported smart-card readers discovery. MoppLibCardReaderManagerDelegate can be used for discovered reader status change

stopDiscoveringReaders

MoppLibCardReaderManager.h, @interface MoppLibCardReaderManager

Syntax

- (void)stopDiscoveringReaders;

Parameters

None

Return value

None

Remarks

Prevents supported smart-card readers discovery when called

setDelegate

MoppLibCardReaderManager.h, @interface MoppLibCardReaderManager

Syntax

- (void)setDelegate:id<MoppLibCardReaderManagerDelegate> delegate;

Parameters

Parameter	Type	Description
delegate	`MoppLibCardReaderManagerDelegate`	Protocol to propagate card reader status change events

Return value

None

Remarks

Set's status change delegate for MoppLibCardReaderManager

MopplibCardReaderManagerDelegate protocol

MoppLibCardReaderManager.h, @interface MoppLibCardReaderManager

Syntax

@protocol MoppLibCardReaderManagerDelegate

Methods

(void)moppLibCardReaderStatusDidChange:(MoppLibCardReaderStatus)status;

Remarks

Used to delegate card reader status to the protocol implementation.

MoppLibCardReaderStatus enum

MoppLibCardReaderManager.h, @interface MoppLibCardReaderManager

Syntax

@protocol MoppLibCardReaderManagerDelegate

Values

Name	Value	Description
ReaderNotConnected	0	Supported reader is discovered
ReaderConnected	1	Reader is discovered and connection to it has been made
CardConnected	2	Card is inserted into the reader and powered on

Remarks

Smart-card reader status returned from MopplibCardReaderManagerDelegate's moppLibCardReaderStatusDidChange

Constants and types

enum MoppLibSignatureStatus

MoppLibConstants.h

Syntax

typedef NS_ENUM(int, MoppLibSignatureStatus)

Parameters

Name	Value	Description
Valid	0	Signature is valid and equal to a handwritten signature
Warning	1	Signature is valid but has warnings. Container has a specific feature that usually has arisen accidentally when containers were created.
NonQSCD	2	The signature is not created by a QSCD
Invalid	3	Digital signature has been declared invalid
UnknownStatus	4	Program was unable to check the validity of the signature at the given moment.

enum MoppLibErrorCode

MoppLibConstants.h

Syntax

typedef NS_ENUM(NSUInteger, MoppLibErrorCode)

Entries

Name	Value	Description
moppLibErrorReaderNotFound	10001	Reader is not connected to phone
moppLibErrorCardNotFound	10002	Reader is connected, but card is not detected
moppLibErrorCardVersionUnknown	10003	Unknown card version
moppLibErrorWrongPin	10004	Provided pin is wrong
moppLibErrorGeneral	10005	General error
moppLibErrorInvalidPin	10006	New pin does not apply to rules
moppLibErrorPinMatchesVerificationCode	10007	New pin must be different from old pin or puk
moppLibErrorIncorrectPinLength	10008	New pin is too short or too long
moppLibErrorPinTooEasy	10009	New pin is too easy
moppLibErrorPinContainsInvalidCharacters	10010	Pin contains invalid characters. Only numbers are allowed
moppLibErrorUrlSessionCanceled	10012	NSURLErrorCanceled occurred when connecting to external service.
moppLibErrorXmlParsingError	10013	AEXMLDocument loadXml failed to parse data to XML.
MoppLibErrorDDSError	10014	DigiDoc Service error
moppLibErrorPinNotProvided	10015	User did not provide pin for action that required authentication
moppLibErrorPinBlocked	10016	User did not provide pin for action that required authentication
moppLibErrorFileNameTooLong	10017	File name too long
moppLibErrorNoInternetConnection	10018	No internet connection
moppLibErrorPinMatchesOldCode	10019	New pin must be different from old pin or puk
moppLibErrorReaderSelectionCanceled	10020	User canceled card reader selection
moppLibErrorRestrictedApi	10021	Restricted API. Some functionality is not available for third-party apps
moppLibErrorLdapResponseNotFound	10022	Empty Ldap response
moppLibErrorDuplicatedFilename	10023	Filename already exists in container

Notifications

MoppLibConstants.h

Notifications names

Name	Description
kMoppLibNotificationReaderStatusChanged	Notification to indicate reader status change
kMoppLibNotificationRetryCounterChanged	Notification to indicate retry counter change

Block type definitions

MoppLibConstants.h

Name	Type	Description
DataSuccessBlock	`void (^)(NSData *responseData);`	NSData* type object returned on successful operation
ObjectSuccessBlock	`void (^)(NSObject *responseObject);`	NSObject* type object returned on successful operation
FailureBlock	`void (^)(NSError *error);`	NSError* type object return upon operation failure
CertDataBlock	`void (^)(MoppLibCertificateData *certData);`	MoppLibCertificateData* type object returned on successful operation
PersonalDataBlock	`void (^)(MoppLibPersonalData *personalData);`	MoppLibPersonalData* type object returned on successful operation
SignatureStatusBlock	`void (^) (MoppLibContainer container, NSError error, NSString *status);`	Block used for signature status information
ContainerBlock	`void (^)(MoppLibContainer *container);`	MoppLibContainer* type object returned on successful container operation
LdapBlock	`void (^)(NSMutableArray *ldapResponse);`	NSMutableArray* of `Addressee` objects returned on successful operation
CdocContainerBlock	`void (^)(CdocInfo *cdocInfo);`	CdocInfo* type object returned on successful operation
DecryptedDataBlock	`void (^)(NSMutableDictionary *decryptedData);`	NSMutableDictionary* type object returned on successful operation
MobileCreateSignatureResponseBlock	`void (^)(MoppLibMobileCreateSignatureResponse);`	Mobile-ID signature response object return on successful Mobile-ID sign operation
BoolBlock	`void (^)(BOOL);`	Block type with `BOOL` as a parameter
NumberBlock	`void (^)(NSNumber*)`	Block type with `NSNumber*` as a parameter
VoidBlock	`void (^)(void);`	Empty callback block

Response objects

Objects returned from various MoppLib operations

MoppLibCertificateData

MoppLibCertificateData.h, @interface MoppLibCertificateData

Properties

Name	Type	Description
isValid	`BOOL`	`YES` if certificate is valid, `NO` otherwise
expiryDate	`NSDate*`	Expiry date of certificate
organization	`MoppLibCertOrganization`	Organization of certificate

MoppLibCertOrganization enum

Name	Value	Description
IDCard	0	ID-card
MobileID	1	Mobile-ID
SmartID	2	Smart-ID
DigiID	3	Digi-ID
EResident	4	E-resident
Unknown	5	Unknown

MoppLibPersonalData

MoppLibPersonalData.h, @interface MoppLibPersonalData

Properties

Name	Type	Description
firstNameLine1	`NSString*`	Person's given name
firstNameLine2	`NSString*`	Person's given name
surname	`NSString*`	Person's surname
sex	`NSString*`	Person's sex
nationality	`NSString*`	Person's nationality
birthDate	`NSString*`	Person's birth date
personalIdentificationCode	`NSString*`	Personal identification code
documentNumber	`NSString*`	Document number
expiryDate	`NSString*`	Expiration date
dateIssued	`NSString*`	Date issued
residentPermitType	`NSString*`	Type of residence permit

MoppLibContainer

MoppLibContainer.h, @interface MoppLibContainer

Properties

Name	Type	Description
fileName	`NSString*`	Name of the container
filePath	`NSString*`	File path of the container
fileAttributes	`NSDictionary*`	File attributes of the container
dataFiles	`NSArray*`	Array of `MoppLibDataFile` objects associated with the container
signatures	`NSArray*`	Array of `MoppLibSignature` objects associated with the container

Member methods

Name	Return value	Description
isSigned	`BOOL`	Returns `YES` if container is signed, `NO` otherwise
isEmpty	`BOOL`	Returns `YES` if container has no signatures of data files, `NO` otherwise
isDDocType	`BOOL`	Returns `YES` container is DDOC type, `NO` otherwise
isAsiceType	`BOOL`	Returns `YES` if container is ASiC-E type, `NO` otherwise
isLegacyType	`BOOL`	Return `YES` if container is legacy type (ADOC, EDOC, DDOC, ASICS, PDF), `NO` otherwise
fileNameWithoutExtension	`NSString*`	Container name without the extension
getNextSignatureId	`NSString*`	Returns next signature ID

MoppLibDataFile

MoppLibDataFile.h, @interface MoppLibDataFile

Properties

Name	Type	Description
mediaType	`NSString*`	Media type of the data file
fieldId	`NSString*`	File ID of the data file
fileName	`NSString*`	Filename of data file
fileSize	`long`	File size of data file

MoppLibSignature

MoppLibSignature.h, @interface MoppLibSignature

Properties

Name	Type	Description
subjectName	`NSString*`	Contains signer's full name and personal identification code
timestamp	`NSDate*`	Signature timestamp
status	`MoppLibSignatureStatus`	Signature status

MoppLibMobileCreateSignatureResponse

MoppLibMobileCreateSignatureResponse.h, @interface MoppLibMobileCreateSignatureResponse

Properties

Name	Type	Description
challengeId	`NSString*`	Mobile-ID challenge ID
sessCode	`NSInteger`	Session code
status	`NSString*`	Signature response status

CdocInfo

CdocInfo.h, @interface CdocInfo

Properties

Name	Type	Description
addressees	`NSMutableArray<Addressee *>`	Cdoc container addressees
dataFiles	`NSMutableArray<CryptoDataFile *>`	Cdoc container data files

Addressee

Addressee.h, @interface Addressee

Properties

Name	Type	Description
givenName	`NSString*`	Given name of addressee
surname	`NSString*`	Surname of addressee
identifier	`NSString*`	Identifier of addressee
type	`NSString*`	Type of addressee certificate
cert	`NSData*`	Auth certificate of addressee
validTo	`NSDate*`	Expiration date of addressee auth certificate

CryptoDataFile

CryptoDataFile.h, @interface CryptoDataFile

Properties

Name	Type	Description
filename	`NSString*`	Filename of data file
filePath	`NSString*`	File path of data file

MoppLdapConfiguration

MoppLdapConfiguration.h, @interface MoppLdapConfiguration

Properties

Name	Type	Description
LDAPPERSONURL	`NSString*`	LDAP URL to search persons
LDAPCORPURL	`NSString*`	LDAP URL to search corporations

MoppLibConfiguration

MoppLibConfiguration.h, @interface MoppLibConfiguration

Properties

Name	Type	Description
SIVAURL	`NSString*`	SiVa (Signature Verification) URL
TSLURL	`NSString*`	TSL (Trust Service Status List) URL
TSLCERTS	`NSArray*`	Array of `NSString` associated with TSL certificates (PEM or DER format)
TSAURL	`NSString*`	TSA (Time Stamping Authority) URL
OCSPISSUERS	`NSDictionary*`	Dictionary of `NSString` : `NSString` associated with OCSP (Online Certificate Status Protocol) issuers

Mobile-ID

Mobile-ID service now uses the Mobile-ID REST API and has been moved to "SkSigningLib" package. The package is written in Swift programming language. The following examples are in Swift language.

RequestSignature

Requests signature for Mobile-ID

getCertificate

RequestSignature.swift, protocol CertificateRequest

Syntax

func getCertificate(baseUrl: String, requestParameters: CertificateRequestParameters, trustedCertificates: [String]?, completionHandler: @escaping (Result<CertificateResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Mobile-ID. Path "/certificate" will be added to the base URL.
requestParameters	`CertificateRequestParameters`	Parameters that are sent to the service.
completionHandler	`Result<CertificateResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to get certificate for signing with Mobile-ID.

Session

Gets the session ID and polls session status

getSession

Session.swift, protocol SessionRequest

Syntax

func getSession(baseUrl: String, requestParameters: SessionRequestParameters, trustedCertificates: [String]?, completionHandler: @escaping (Result<SessionResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Mobile-ID. Path "/signature" will be added to the base URL.
requestParameters	`SessionRequestParameters`	Parameters that are sent to the service.
completionHandler	`Result<SessionResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to get session ID for signing with Mobile-ID. Session ID is used to poll session status.

getSessionStatus

Session.swift, protocol SessionRequest

Syntax

func getSessionStatus(baseUrl: String, process: PollingProcess, requestParameters: SessionStatusRequestParameters, trustedCertificates: [String]?, completionHandler: @escaping (Result<SessionStatusResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Mobile-ID. Path "/signature/session/{sessionId}?timeoutMs={timeoutMs}" will be added to the base URL. Values are taken from requestParameters.
process	`PollingProcess`	Determines if session is for authentication or signing.
requestParameters	`SessionRequestParameters`	Parameters that are used in URL.
completionHandler	`Result<SessionStatusResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to poll as long as Mobile-ID signing service responds.

Validate signature (MoppLib)

Validate signature after successful Mobile-ID response. MoppLib framework must be used.

isSignatureValid

MoppLibManager.h, @interface MoppLibManager

Syntax

+ (void)isSignatureValid:(NSString *)cert signatureValue:(NSString *)signatureValue success:(BoolBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
cert	`NSString*`	Certificate in base64 format
signatureValue	`NSString*`	Signature value from Mobile-ID successful response
success	`BoolBlock`	`YES` if validation is successful, `NO` otherwise
failure	`FailureBlock`	Called when validating signature fails

Return value

None

Remarks

This method validates Mobile-ID signature

Smart-ID

Smart-ID service uses the Smart-ID REST API and has been implemented in "SkSigningLib" package. The package is written in Swift programming language. The following examples are in Swift language.

getCertificate

Requests certificate for Smart-ID

SIDRequest.swift, protocol SIDRequestProtocol

Syntax

func getCertificate(baseUrl: String, country: String, nationalIdentityNumber: String, requestParameters: SIDCertificateRequestParameters, trustedCertificates: [String]?, completionHandler: @escaping (Result<SIDSessionResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Smart-ID. Path "/certificate/pno/{country}/{nationalIdentityNumber}" will be added to the base URL.
country	`String`	User country
nationalIdentityNumber	`String`	User personal code
requestParameters	`SIDCertificateRequestParameters`	Parameters that are sent to the service.
trustedCertificates	`[String]?`	Certificates to trust
completionHandler	`Result<SIDSessionResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to get certificate and session ID for signing with Smart-ID.

getSignature

Requests signature for Smart-ID

SIDRequest.swift, protocol SIDRequestProtocol

Syntax

func getSignature(baseUrl: String, documentNumber: String, requestParameters: SIDSignatureRequestParameters, trustedCertificates: [String]?, completionHandler: @escaping (Result<SIDSessionResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Smart-ID. Path "/certificate/pno/{country}/{nationalIdentityNumber}" will be added to the base URL.
documentNumber	`String`	User country
requestParameters	`SIDCertificateRequestParameters`	Parameters that are sent to the service.
trustedCertificates	`[String]?`	Certificates to trust
completionHandler	`Result<SIDSessionResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to get session ID for signing with Smart-ID.

getSessionStatus

Requests session status and response for Smart-ID

SIDRequest.swift, protocol SIDRequestProtocol

Syntax

func getSessionStatus(baseUrl: String, sessionId: String, timeoutMs: Int?, trustedCertificates: [String]?, completionHandler: @escaping (Result<SIDSessionStatusResponse, SigningError>) -> Void)

Parameters

Parameter	Type	Description
baseUrl	`String`	The base URL for Smart-ID. Path "/certificate/pno/{country}/{nationalIdentityNumber}" will be added to the base URL
sessionId	`String`	Session ID retrieved from signature response
timeoutMs	`Int?`	Timeout interval to poll session status (milliseconds)
trustedCertificates	`[String]?`	Certificates to trust
completionHandler	`Result<SIDSessionStatusResponse, SigningError>`	Callback handling on request response.

Return value

None

Remarks

This method is used to poll as long as Smart-ID signing service responds.

Validate signature (MoppLib)

Validate signature after successful Smart-ID response. MoppLib framework must be used.

isSignatureValid

MoppLibManager.h, @interface MoppLibManager

Syntax

+ (void)isSignatureValid:(NSString *)cert signatureValue:(NSString *)signatureValue success:(BoolBlock)success failure:(FailureBlock)failure;

Parameters

Parameter	Type	Description
cert	`NSString*`	Certificate in base64 format
signatureValue	`NSString*`	Signature value from Smart-ID successful response
success	`BoolBlock`	`YES` if validation is successful, `NO` otherwise
failure	`FailureBlock`	Called when validating signature fails

Return value

None

Remarks

This method validates Smart-ID signature

Constants and types

Block type definitions

Type	Description
CertificateRequestParameters	Object needed to send to Mobile-ID service to request user certificate
CertificateResponse	Certificate will be returned on successful response
SessionRequestParameters	Object needed to send to Mobile-ID service to request session ID
SessionResponse	Session ID will be returned on successful response
PollingProcess	Determines if polling authentication or signing request
SessionStatusRequestParameters	Object needed to send to Mobile-ID service to request session status
SessionStatusResponse	Returns session signature on successful response
SIDCertificateRequestParameters	Object needed to send to Smart-ID service to request session ID
SIDSessionResponse	Returns session ID on successful response
SIDSignatureRequestParameters	Relying party UUID and relying party name that are sent to Smart-ID service
SIDSessionStatusResponse	Returns session signature on successful response
SigningError	Object returned on operation failure

Request objects

SkSigningLib request objects

CertificateRequestParameters

CertificateRequestParameters.swift, struct CertificateRequestParameters

Properties

Name	Type	Description
relyingPartyUUID	`String`	Relying party UUID
relyingPartyName	`String`	Relying party name
phoneNumber	`String`	Phone number
nationalIdentityNumber	`String`	Personal code

SessionRequestParameters

SessionRequestParameters.swift, struct SessionRequestParameters

Properties

Name	Type	Description
relyingPartyName	`String`	Relying party name
relyingPartyUUID	`String`	Relying party UUID
phoneNumber	`String`	Phone number
nationalIdentityNumber	`String`	Personal code
hash	`String`	Hash to be sent to Mobile-ID service
hashType	`String`	Hash type (eg. SHA256)
language	`String`	Language (eg. EST)
displayText	`String?`	Text to display on user's phone
displayTextFormat	`String?`	Display format (eg. GSM-7)

enum PollingProcess

RequestMethod.swift

Syntax

PollingProcess.SIGNING

Entries

Name	Description
AUTHENTICATION	Poll for authentication (not supported)
SIGNING	Poll for signing

SessionStatusRequestParameters

SessionStatusRequestParameters.swift, struct SessionStatusRequestParameters

Properties

Name	Type	Description
sessionId	`String`	Session ID retrieved from session request
timeoutMs	`String`	Timeout interval to poll session status (milliseconds)

SIDCertificateRequestParameters

SIDCertificateRequestParameters.swift, struct SIDCertificateRequestParameters

Properties

Name	Type	Description
relyingPartyName	`String`	Relying party name
relyingPartyUUID	`String`	Relying party UUID

SIDSignatureRequestParameters

SIDSignatureRequestParameters.swift, struct SIDSignatureRequestParameters

Properties

Name	Type	Description
relyingPartyName	`String`	Relying party name
relyingPartyUUID	`String`	Relying party UUID
hash	`String`	Hash to be sent to Smart-ID service
hashType	`String`	Hash type (eg. SHA256)
displayText	`String?`	Text to display on user's phone
requestProperties	`SIDSignatureRequestParametersProperties?`	Relying party UUID

SIDSignatureRequestParametersProperties

SIDSignatureRequestParameters.swift, struct SIDSignatureRequestParametersProperties

Properties

Name	Type	Description
vcChoice	`String`	Verification code choice

Response objects

SkSigningLib response objects

CertificateResponse

CertificateResponse.swift, struct CertificateResponse

Properties

Name	Type	Description
result	`ResponseResult?`	`OK` if certificate is valid, `NOT_FOUND` or `NOT_ACTIVE` otherwise
cert	`String?`	Certificate in base64 if response is successful
time	`String?`	Request time if response is successful
traceId	`String?`	Trace ID if response is successful
error	`String?`	Error description if response is unsuccessful

ResponseResult enum

| Name | Description | ---- | ----- | ---- | | OK | Result is successful | NOT_FOUND | Mobile-ID account not found | NOT_ACTIVE | Mobile-ID account not active

SessionResponse

SessionResponse.swift, struct SessionResponse

Properties

Name	Type	Description
sessionID	`String?`	Session ID will be returned if response is successful
time	`String?`	Request time if response is successful
traceId	`String?`	Trace ID if response is successful
error	`String?`	Error description if response is unsuccessful

SessionStatusResponse

SessionStatusResponse.swift, struct SessionStatusResponse

Properties

Name	Type	Description
state	`SessionResponseState`	Determines if session is running or has completed
result	`SessionResultCode?`	Session result. `OK` on successful response
signature	`SessionResponseSignature?`	Returned signature value
cert	`String?`	Certificate in base64 if response is successful
time	`String?`	Request time if response is successful
traceId	`String?`	Trace ID if response is successful
error	`String?`	Error description if response is unsuccessful

SessionResponseState enum

Name	Description
RUNNING	Session is still processing
COMPLETE	Session processing has finished

SessionResultCode enum

Name	Description
OK	Session result successful
TIMEOUT	Session has timed out
NOT_MID_CLIENT	Account does not have Mobile-ID
USER_CANCELLED	User has cancelled signing process
SIGNATURE_HASH_MISMATCH	Signature hash mismatched
PHONE_ABSENT	SIM card is not available
DELIVERY_ERROR	Error when sending SMS
SIM_ERROR	Invalid response from SIM card

SessionResponseSignature

SessionResponseSignature.swift, struct SessionResponseSignature

Properties

Name	Type	Description
value	`String`	Signature value
algorithm	`String`	Signature algorithm

SIDSessionResponse

SIDSessionResponse.swift, struct SIDSessionResponse

Properties

Name	Type	Description
sessionID	`String`	Session ID to poll for status

SIDSessionStatusResponse

SIDSessionStatusResponse.swift, struct SIDSessionStatusResponse

Properties

Name	Type	Description
state	`SIDSessionStatusResponseState`	Determines if session is running or has completed
result	`SIDSessionStatusResponseResult?`	Session result. `OK` on successful response with documentNumber
signature	`SIDSessionStatusResponseSignature?`	Returned signature value
cert	`SIDSessionStatusResponseCertificate?`	Returned certificate value with level

SIDSessionStatusResponseResult

SIDSessionStatusResponse.swift, struct SIDSessionStatusResponseResult

Properties

Name	Type	Description
endResult	`SIDSessionStatusResponseState`	Returned session status. `OK` for successful response
documentNumber	`SIDSessionStatusResponseResult?`	User document number

SIDSessionStatusResponseCode enum

Name	Description
OK	Successful response
USER_REFUSED	User refused to continue
TIMEOUT	Session has timed out
DOCUMENT_UNUSABLE	Unknown error
WRONG_VC	Incorrect verification code choice

SIDSessionStatusResponseSignature

SIDSessionStatusResponse.swift, struct SIDSessionStatusResponseSignature

Properties

Name	Type	Description
value	`String`	Signature value
algorithm	`String`	Signature algorithm

SIDSessionStatusResponseCertificate

SIDSessionStatusResponse.swift, struct SIDSessionStatusResponseCertificate

Properties

Name	Type	Description
value	`String`	Certificate value
certificateLevel	`String`	Certificate level

enum SigningError

SigningError.swift

Syntax

SigningError.generalError

Entries

Name	Description
invalidURL	URL is not valid
noResponseError	No response, no Internet connection
generalError	General error
generalSignatureAddingError	Error when adding signature to container
invalidSSLCert	SSL certificate is invalid
notFound	Account not found
notActive	Account not active
parameterNameNull	Required parameter is empty
userAuthorizationFailed	Failed to authorize user
methodNotAllowed	Method not allowed response error
internalError	Internal error on server side
hashLengthInvalid	Invalid hash length
hashEncodingInvalid	Invalid hash encoding
sessionIdMissing	Session ID missing
sessionIdNotFound	Session ID not found
exceededUnsuccessfulRequests	Too many unsuccessful requests
timeout	Session status timeout
notMidClient	Not a Mobile-ID client
userCancelled	User cancelled request
signatureHashMismatch	Signature hash mismatch
phoneAbsent	SIM is not available
deliveryError	Unable to send SMS
simError	Invalid response from SIM card
tooManyRequests	Too many requests (Rate limiting)
midInvalidAccessRights	Invalid relying party UUID for Mobile-ID
sidInvalidAccessRights	Invalid relying party UUID for Smart-ID
ocspInvalidTimeSlot	Invalid OCSP time slot
certificateRevoked	Account certificate has been revoked
wrongVC	Incorrect verification code choice
documentUnusable	Unknown error
notQualified	Invalid qualification
oldApi	API too old
sidTimeout	Smart-ID timeout error
forbidden	Wrong country with RPUUID
accountNotFound	Smart-ID account not found