com.lacunasoftware.restpki

Class Authentication

java.lang.Object

com.lacunasoftware.restpki.Authentication

public class Authentication
extends java.lang.Object

Class used to authenticate a user with a X.509 public key certificate.

Constructor Summary

Constructors

Constructor and Description
Authentication(RestPkiClient client)

Method Summary

Modifier and Type	Method and Description
ValidationResults	complete(java.lang.String nonce, java.lang.String certificate, java.lang.String signature, SecurityContext securityContext) Deprecated. Use complete2() method.
AuthenticationResult	complete2(java.lang.String token, java.lang.String certificate, java.lang.String signature) Performs the final of two steps, receiving (1) the token that identifies the authentication process; (2) the user's certificate encoding; (3) the signature of the nonce.
ValidationResults	completeWithWebPki(java.lang.String token)
boolean	getIgnoreRevocationStatusUnknown()
PKCertificate	getPKCertificate() Returns the user certificate's information (must only be called after calling the complete() method).
void	setIgnoreRevocationStatusUnknown(boolean ignoreRevocationStatusUnknown) Sets the option of "IgnoreRevocationStatusUnknown".
java.lang.String	start() Deprecated. Use a modern start2() method.
ClientSideSignatureInstructions	start2(SecurityContext securityContext) Performs the first of two steps, yielding a cryptographic nonce that must be signed using the user certificate's private key.
java.lang.String	startWithWebPki(SecurityContext securityContext)

Methods inherited from class java.lang.Object

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

Constructor Detail

Authentication

public Authentication(RestPkiClient client)

Method Detail

getIgnoreRevocationStatusUnknown

public boolean getIgnoreRevocationStatusUnknown()

setIgnoreRevocationStatusUnknown

public void setIgnoreRevocationStatusUnknown(boolean ignoreRevocationStatusUnknown)

Sets the option of "IgnoreRevocationStatusUnknown".

Parameters:

ignoreRevocationStatusUnknown - The option of "IgnoreRevocationStatusUnknown".

start

@Deprecated
public java.lang.String start()
                                    throws RestException

Deprecated. Use a modern start2() method.

Performs the first of two steps, yielding a cryptographic nonce that must be signed using the user certificate's private key.

If you are using the Web PKI component to perform the client-side signature, this value must be passed to the component's method signData. The nonce is returned encoded in Base64, which is the same encoding expected by the component's signData method.

Returns:

The cryptographic nonce that must be signed using the user certificate's private key, encoded in Base64.

Throws:

RestException - If an error occurs while calling the REST PKI API.

start2

public ClientSideSignatureInstructions start2(SecurityContext securityContext)
                                       throws RestException

Performs the first of two steps, yielding a cryptographic nonce that must be signed using the user certificate's private key.

The security context is used to determine if the user certificate can be trusted, and is mandatory. You can use one of the predefined security contexts such as pkiBrazil or pkiItaly, or you can create a custom security context by accessing the REST PKI site.

If you are using the Web PKI component to perform the client-side signature, this value must be passed to the component's method signData. The nonce is returned encoded in Base64, which is the same encoding expected by the component's signData method.

Returns:

The signature parameters to perform a client-side signature:

• token;
• toSignData;
• toSignHash;
• digestAlgorithmOid.

Throws:

RestException - If an error occurs while calling the REST PKI API.

startWithWebPki

public java.lang.String startWithWebPki(SecurityContext securityContext)
                                 throws RestException

Throws:

RestException

complete

@Deprecated
public ValidationResults complete(java.lang.String nonce,
                                               java.lang.String certificate,
                                               java.lang.String signature,
                                               SecurityContext securityContext)
                                        throws RestException

Deprecated. Use complete2() method.

Performs the final of two steps, receiving (1) the cryptographic nonce previously generated; (2) the user's certificate encoding; (3) the signature of the nonce and (4) a security context and yielding a ValidationResults.

The security context is used to determine if the user certificate can be trusted, and is mandatory. You can use one of the predefined security contexts such as pkiBrazil or pkiItaly, or you can create a custom security context by accessing the REST PKI site.

This method does not throw an exception if the validation of the user's certificate fails. Instead, it returns a ValidationResults with validation errors. In order to determine whether the authentication was successful, you must call the isValid() method on the returned ValidationResults object.

Parameters:

nonce - The cryptographic nonce generated in the first step, which was signed with the user certificate's private key.

certificate - The binary encoding of the user's certificate, encoded in Base64 (this is the format returned by the Web PKI component's readCertificate method).

signature - The digital signature of the nonce using the user certificate's private key, encoded in Base64 (this is the format returned by the Web PKI component's signData method).

securityContext - The security context to be used to validate the user's certificate.

Returns:

A ValidationResults object containing the results of the authentication (call the method isValid() to determine whether the authentication was successful).

Throws:

RestException - If an error occurs while calling the REST PKI API (this method does not throw an exception if the validation of the user's certificate fails).

complete2

public AuthenticationResult complete2(java.lang.String token,
                                      java.lang.String certificate,
                                      java.lang.String signature)
                               throws RestException

Performs the final of two steps, receiving (1) the token that identifies the authentication process; (2) the user's certificate encoding; (3) the signature of the nonce.

This method does not throw an exception if the validation of the user's certificate fails. Instead, it returns a ValidationResults with validation errors. In order to determine whether the authentication was successful, you must call the isValid() method on the returned ValidationResults object.

Parameters:

token - The token, a 43-character case-sensitive string containing only letters, numbers and the characters "-" and "_" (therefore URL and HTML safe).

certificate - The binary encoding of the user's certificate, encoded in Base64 (this is the format returned by the Web PKI component's readCertificate method).

signature - The digital signature of the nonce using the user certificate's private key, encoded in Base64 (this is the format returned by the Web PKI component's signData method).

Returns:

The result of a authentication containg the authenticated certificate and the validation of this certificate.

Throws:

RestException - If an error occurs while calling the REST PKI API (this method does not throw an exception if the validation of the user's certificate fails).

completeWithWebPki

public ValidationResults completeWithWebPki(java.lang.String token)
                                     throws RestException

Throws:

RestException

getPKCertificate

public PKCertificate getPKCertificate()

Returns the user certificate's information (must only be called after calling the complete() method).

Note: if the authentication is successful, this method is guaranteed to return an object instance. However, if the authentication fails, this method may return null.

Returns:

The user certificate's information, or null if it cannot be determined (does not happen if the authentication succeeds).