iaik.x509

Class NetscapeCertRequest

java.lang.Object

iaik.x509.NetscapeCertRequest

All Implemented Interfaces:

CertRequest, java.io.Serializable

public class NetscapeCertRequest
extends java.lang.Object
implements java.io.Serializable, CertRequest

This class represents a certificate request as has been introduced by Netscape Navigator 3.0 and 4.x and used with the HTML <keygen> of many browsers.

The Netscape Certificate Specification has specified the NetscapeCertRequest as ASN.1 SignedPublicKeyAndChallenge containing a PublicKeyAndChallenge element that has been signed with the private key of the certificate applicant. For verification purposes signature algorithm and signature value are included in the SignedPublicKeyAndChallenge object: s:

 SignedPublicKeyAndChallenge ::= SEQUENCE {
    publicKeyAndChallenge PublicKeyAndChallenge,
    signatureAlgorithm AlgorithmIdentifier,
    signature BIT STRING
 }
 

where:

 PublicKeyAndChallenge ::= SEQUENCE {
    spki SubjectPublicKeyInfo,
    challenge IA5STRING
 }
 

Although this class offers a constructor allowing to create a NetscapeCertRequest from scratch the main use case might be the parsing and verification of NetscapeCertRequests that have been generated and submitted from some client browser by using the HTML keygen tag.

When parsing a NetscapeCertRequest the DER/PEM encoded SignedPublicKeyAndChallenge has to be given as byte array or may be read from an input stream. After having verified the signature of the request you can get the included public key and challenge:

 // the input stream from which to read the request:
 InputStream in = ...;
 // parse request
 NetscapeCertRequest request = new NetscapeCertRequest(in);
 // verify the request
 if (!request.verify()) {
   throw new SignatureException("Request verification failure!");
 }
 // get public key and challenge
 PublicKey publicKey = request.getPublicKey();
 String challenge = request.getChallenge();
 

Version:

File Revision 34

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
NetscapeCertRequest(byte[] arr) Creates a NetscapeCertRequest from a byte array supplying the PEM or DER encoded request.
NetscapeCertRequest(java.io.InputStream is) Creates a NetscapeCertRequest from an input stream supplying the PEM or DER encoded request.
NetscapeCertRequest(java.security.PublicKey publicKey, java.lang.String challenge) Creates a new CertificateRequest from a public key and a challenge.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getChallenge() Gets the challenge of this NetscapeCertRequest.
byte[]	getFingerprint() Returns the fingerprint of this NetscapeCertRequest.
byte[]	getFingerprint(java.lang.String digestAlgorithm) Returns the fingerprint of this NetscapeCertRequest calculated with the given hash algorithm.
byte[]	getFingerprintSHA() Get the SHA-1 fingerprint of this NetscapeCertRequest.
java.security.PublicKey	getPublicKey() Returns the public key of this NetscapeCertRequest.
byte[]	getPublicKeyAndChallenge() Returns the DER encoded PublicKeyAndChallenge ASN.1 data structure over which the signature is calculated:
AlgorithmID	getSignatureAlgorithmID() Returns the signature algorithm of this NetscapeCertRequest.
void	setSignature(AlgorithmID signatureAlgorithm, byte[] signatureValue) Sets the signature value of this NetscapeCertRequest.
void	sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey privateKey) Signs the NestcapeCertRequest with the private key of the certificate applicant.
void	sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey privateKey, java.security.Provider provider) Signs the NestcapeCertRequest with the private key of the certificate applicant.
void	sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey privateKey, java.lang.String providerName) Signs the NestcapeCertRequest with the private key of the certificate applicant.
byte[]	toByteArray() Returns this NetscapeCertRequest in a byte array in DER format.
java.lang.String	toString() Returns a string that represents the contents of this NetscapeCertRequest.
boolean	verify() Verifies the signature of this NetscapeCertRequest.
boolean	verify(java.security.Provider provider) Verifies the the signature of this NetscapeCertRequest.
boolean	verify(java.lang.String providerName) Verifies the the signature of this NetscapeCertRequest.
void	writeTo(java.io.OutputStream os) Writes this NetscapeCertRequest DER encoded to the given output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

NetscapeCertRequest

public NetscapeCertRequest(java.io.InputStream is)
                    throws java.io.IOException,
                           CodingException

Creates a NetscapeCertRequest from an input stream supplying the PEM or DER encoded request.

From the request derived from the given input stream the SignedPublicKeyAndChallange ASN.1 data structure is created.
For example:

 // the input stream from which to read the request:
 InputStream in = ...;
 // parse request
 NetscapeCertRequest request = new NetscapeCertRequest(in);
 // verify the request
 if (!request.verify()) {
   throw new SignatureException("Request verification failure!");
 }
 // get public key and challenge
 PublicKey publicKey = request.getPublicKey();
 String challenge = request.getChallenge();
 

Parameters:

is - the input stream from where to read the PEM/DER encoded cert request

Throws:

java.io.IOException - if an I/O error occurs.

CodingException - if the NetscapeCertRequest could not be parsed

NetscapeCertRequest

public NetscapeCertRequest(byte[] arr)
                    throws CodingException

Creates a NetscapeCertRequest from a byte array supplying the PEM or DER encoded request.

From the request derived from the given byte array the SignedPublicKeyAndChallange ASN.1 data structure is created.
For example:

 // the byte array from which to read the request:
 byte[] encodedRequest = ...;
 // parse request
 NetscapeCertRequest request = new NetscapeCertRequest(encodedRequest);
 // verify the request
 if (!request.verify()) {
   throw new SignatureException("Request verification failure!");
 }
 // get public key and challenge
 PublicKey publicKey = request.getPublicKey();
 String challenge = request.getChallenge();
 

Parameters:

arr - the array containing the DER/PEM encoded CertRequest

Throws:

CodingException - if the CertRequest could not be parsed

NetscapeCertRequest

public NetscapeCertRequest(java.security.PublicKey publicKey,
                   java.lang.String challenge)

Creates a new CertificateRequest from a public key and a challenge.

This constructor maybe used to create a NetscapeCertRequest SignedPublicKeyAndChallange from scratch. After having created the request it has to be signed and encoded to be transmitted to a certificate issuing certification authority.
For example:

 // public key and challenge:
 PublicKey publicKey = ...;
 String challenge = ...;
 // create request
 NetscapeCertRequest request = new NetscapeCertRequest(publicKey, challenge);
 // sign the request
 AlgorithmID signatureAlgorithm = ...;
 PrivateKey privateKey = ...;
 request.sign(signatureAlgorithm, privateKey);
 // encode request
 byte[] encodedRequest = request.toByteArray(); 
 

Parameters:

publicKey - the public key

challenge - the challenge

Method Detail

getPublicKeyAndChallenge

public byte[] getPublicKeyAndChallenge()
                                throws CodingException

Returns the DER encoded PublicKeyAndChallenge ASN.1 data structure over which the signature is calculated:

 PublicKeyAndChallenge ::= SEQUENCE {
   spki SubjectPublicKeyInfo,
   challenge IA5STRING
 }
 

Returns:

the inherent PublicKeyAndChallenge as DER encoded ASN.1 structure

Throws:

CodingException - if an encoding error occurs

getChallenge

public java.lang.String getChallenge()

Gets the challenge of this NetscapeCertRequest.

Returns:

the challenge of this NetscapeCertRequest

sign

public void sign(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey privateKey)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException

Signs the NestcapeCertRequest with the private key of the certificate applicant.

Parameters:

signatureAlgorithm - the AlgorithmID of the signature algorithm

privateKey - the private key of the certificate applicant

Throws:

java.security.SignatureException - if the signature could not be created

java.security.InvalidKeyException - if the format of the key is wrong

java.security.NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm

sign

public void sign(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey privateKey,
        java.lang.String providerName)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException

Signs the NestcapeCertRequest with the private key of the certificate applicant.

Parameters:

signatureAlgorithm - the AlgorithmID of the signature algorithm

privateKey - the private key of the certificate applicant

providerName - the name of the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm

Throws:

java.security.SignatureException - if the signature could not be created

java.security.InvalidKeyException - if the format of the key is wrong

java.security.NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm

sign

public void sign(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey privateKey,
        java.security.Provider provider)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException

Signs the NestcapeCertRequest with the private key of the certificate applicant.
This method uses a Signature engine from the given provider for signing the request.
If Provider object based JCA/JCE Signature engine instantiation is not available the Java VM in use (<1.4), this method tries to get an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method Signature.getInstance(algorithm,provider) is not available method Signature.getInstance(algorithm,provider.getName()) is tried.

Parameters:

signatureAlgorithm - the AlgorithmID of the signature algorithm

privateKey - the private key of the certificate applicant

provider - the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm

Throws:

java.security.SignatureException - if the signature could not be created

java.security.InvalidKeyException - if the format of the key is wrong

java.security.NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm

setSignature

public void setSignature(AlgorithmID signatureAlgorithm,
                byte[] signatureValue)
                  throws java.security.SignatureException

Sets the signature value of this NetscapeCertRequest.

This method provides an alternative to method sign when it is required to set the signature value from outside (e.g. calculated by means of a smartcard):

 // public key and challenge:
 PublicKey publicKey = ...;
 String challenge = ...;
 // create request
 NetscapeCertRequest request = new NetscapeCertRequest(publicKey, challenge);
 // get the to-be-signed PublicKeyAndChallenge value
 byte[] pkac = request.getPublicKeyAndChallenge();
 // now calculate the signature over the PublicKeyAndChallenge
 AlgorithmID signatureAlgorithm = ...;
 byte[] signatureValue = calculateSignature(pkac, signatureAlgorithm);
 // and set the signatureValue
 request.setSignature(signatureAlgorithm, signatureValue);
 // encode the request
 byte[] encodedRequest = request.toByteArray();
 

Parameters:

signatureValue - the signature calculated outside

Throws:

java.security.SignatureException - if the request cannot not be signed

verify

public boolean verify()
               throws java.security.SignatureException

Verifies the signature of this NetscapeCertRequest.

Specified by:

verify in interface CertRequest

Returns:

true if the signature of this NetscapeCertRequest request is OK, false if not

Throws:

java.security.SignatureException - if the NetscapeCertRequest cannot not be verified

verify

public boolean verify(java.lang.String providerName)
               throws java.security.SignatureException

Verifies the the signature of this NetscapeCertRequest.

Parameters:

providerName - the name of the provider supplying the Signature engine to be used; if null the first available provider will be used the supports the signature algorithm

Returns:

true if the signature of this NetscapeCertRequest request is OK, false if not

Throws:

java.security.SignatureException - if the certificate request could not be verified

verify

public boolean verify(java.security.Provider provider)
               throws java.security.SignatureException

Verifies the the signature of this NetscapeCertRequest.

This method uses a Signature engine from the given provider for verifying the request.
If Provider object based JCA/JCE Signature engine instantiation is not available the Java VM in use (<1.4), this method tries to get an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method Signature.getInstance(algorithm,provider) is not available method Signature.getInstance(algorithm,provider.getName()) is tried.

Parameters:

provider - the provider supplying the Signature engine to be used; if null the first available provider will be used the supports the signature algorithm

Returns:

true if the signature of this NetscapeCertRequest request is OK, false if not

Throws:

java.security.SignatureException - if the certificate request could not be verified

toByteArray

public byte[] toByteArray()

Returns this NetscapeCertRequest in a byte array in DER format.

The DER format (Distinguished Encoding Rules) defines a binary representation of an abstract ASN.1 data structure.

Returns:

the encoded NetscapeCertRequest as byte array in DER format

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes this NetscapeCertRequest DER encoded to the given output stream.

Parameters:

os - the output stream to which the NetscapeCertRequest shall be written

Throws:

java.io.IOException - if an I/O error occurs

getSignatureAlgorithmID

public AlgorithmID getSignatureAlgorithmID()

Returns the signature algorithm of this NetscapeCertRequest.

Returns:

the signature algorithm used to sign this NetscapeCertRequest as AlgorithmID

getPublicKey

public java.security.PublicKey getPublicKey()
                                     throws java.security.InvalidKeyException

Returns the public key of this NetscapeCertRequest.

Specified by:

getPublicKey in interface CertRequest

Returns:

the public key of NetscapeCertRequest

Throws:

java.security.InvalidKeyException

getFingerprint

public byte[] getFingerprint()

Returns the fingerprint of this NetscapeCertRequest. This is a MD5 hash of the DER encoded NetscapeCertRequest.

Returns:

the fingerprint of the certificate request

getFingerprint

public byte[] getFingerprint(java.lang.String digestAlgorithm)
                      throws java.security.NoSuchAlgorithmException

Returns the fingerprint of this NetscapeCertRequest calculated with the given hash algorithm.

Parameters:

digestAlgorithm - the digest algorithm to be used

Returns:

the fingerprint of the certificate request

Throws:

java.security.NoSuchAlgorithmException - if the requested algorithm is not supported

getFingerprintSHA

public byte[] getFingerprintSHA()

Get the SHA-1 fingerprint of this NetscapeCertRequest. The result is cached for subsequent calls.

Returns:

the SHA-1 fingerprint

toString

public java.lang.String toString()

Returns a string that represents the contents of this NetscapeCertRequest.

Overrides:

toString in class java.lang.Object

Returns:

the string representation