iaik.smime.ess

Class SigningCertificate

java.lang.Object

iaik.smime.ess.SigningCertificate

public class SigningCertificate
extends java.lang.Object

This class implements the S/MIMEv3 SigningCertificate type.

The Enhanced Security Services for S/MIMEv3 (ESS) (RFC 2634) specify the SigningCertificate type for providing a way to include certificate identification information into the signed attributes of a CMS SignerInfo object:

 SigningCertificate ::=  SEQUENCE {
     certs        SEQUENCE OF ESSCertID,
     policies     SEQUENCE OF PolicyInformation OPTIONAL
  }
 

 ESSCertID ::=  SEQUENCE {        
   certHash     Hash,
   issuerSerial IssuerSerial OPTIONAL   }
 

 Hash ::= OCTET STRING -- SHA1 hash of entire certificate
 

 IssuerSerial ::= SEQUENCE {        
   issuer       GeneralNames,
   serialNumber CertificateSerialNumber   }
 

The ESSCertID type is used for for identifying a certificate by cert hash and optionally issuer information and issuer-specific certificate serial number. PolicyInformations (X.509) are used for indicating the policy under which a certificate has been issued and the purposes for which the certificate may be used.

When creating a SigningCertificate, you either immediately may supply the ESSCertID objects to be added or you may supply certificates to let this class calculate the corresponding ESSCertIDs, e.g.:

 // the cert used for signing:
 X509Certificate signerCert = ...;
 // the issuer of the signer:
 X509Certificate issuerCert = ...;
 // an attribute certificate:
 AttributeCertificate attributeCert = ...;
 // the certificate of the signer must be the first!
 Certificate[] certs = { signerCert, issuerCert, attributeCert };
 // IssuerSerial shall be inlcuded in the ESSCertIDs:
 boolean includeIssuerSerial = true;
 SigningCertificate signingCertificate = new SigningCertificate(certs, includeIssuerSerial);
 

Use method setPolicies for including any PolicyInformation terms:

 PolicyInformation[] policies = ...;
 signingCertificate.setPolicies(policies);
 

For adding a SigningCertificate to the signed attributes field of a SignerInfo object, use method setSignedAttributes:

 Attribute[] signedAttributes = ...;
 ...
 attributes[i] = new Attribute(ObjectID.signingCertificate, 
                               new ASN1Object[] {signingCertificate.toASN1Object()});
 ...
 signerInfo.setSignedAttributes(signedAttributes);
 

Use method getSignedAttribute for getting the SigningCertificate (if included) attribute from a SignerInfo object:

 Attribute signingCertificateAttr = signerInfo.getSignedAttribute(ObjectID.signingCertificate);
 if (signingCertificateAttr != null) {
   SigningCertificate signingCertificate = 
      new SigningCertificate(signingCertificateAttr.getValue()[0]);
 ...
 }
 

See Also:

ESSIssuerSerial, ESSCertID, X509Certificate, AttributeCertificate, Attribute, PolicyInformation, CertificateSet, SignerInfo

Constructor Summary

Constructors

Constructor and Description
SigningCertificate(ASN1Object obj) Creates a new SigningCertificate from an ASN1Object.
SigningCertificate(java.security.cert.Certificate[] certs, boolean includeIssuerSerial) Creates a SigningCertificate attribute for the given certificates.
SigningCertificate(CertificateSet certSet, boolean includeIssuerSerial) Creates a SigningCertificate attribute for the given certificates.
SigningCertificate(ESSCertID[] essCertIDs) Creates a SigningCertificate for the given ESSCertIDs.

Method Summary

Methods

Modifier and Type	Method and Description
int	countPolicies() Returns the number of PolicyInformation terms included.
void	decode(ASN1Object obj) Decodes the given ASN.1 SigningCertificate object for parsing the internal structure.
java.security.cert.Certificate[]	getAuthorizedCertificates(java.security.cert.Certificate[] certificates) Gets the authorized certificates from the set of supplied certficates.
ESSCertID	getESSCertID(java.security.cert.Certificate cert) Searches for the ESSCertID identifying the given cert.
ESSCertID[]	getESSCertIDs() Returns the ESS certs IDs.
PolicyInformation[]	getPolicies() Returns the policiy informations.
java.security.cert.Certificate[]	getPolicyInformationCerts(java.security.cert.Certificate[] certificates) Gets those certificates from the supplied set of certificates having a CertificatePolicies extension with any of the PolicyInformation terms included in this SigningCertificate set.
PolicyInformation[]	getPolicyInformations(java.security.cert.Certificate cert) Looks if the supplied certificate has a CertificatePolicies extension containing any of the PolicyInformation terms of this SigningCertificate attribute.
boolean	isSignerCertificate(X509Certificate certificate) Checks if this SigningCertificate identifies the given certificate as certificate of the signer to whom this SigningCertificate belongs.
void	setPolicies(PolicyInformation[] policies) Sets the policy informations of this SigningCertificate.
ASN1Object	toASN1Object() Returns this SigningCertificate as ASN1Object.
java.lang.String	toString() Returns a string that represents the contents of this SigningCertificate object.

Methods inherited from class java.lang.Object

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

Constructor Detail

SigningCertificate

public SigningCertificate(ESSCertID[] essCertIDs)

Creates a SigningCertificate for the given ESSCertIDs.

Parameters:

essCertIDs - the cert IDs to be set

SigningCertificate

public SigningCertificate(java.security.cert.Certificate[] certs,
                  boolean includeIssuerSerial)
                   throws java.security.NoSuchAlgorithmException,
                          java.security.cert.CertificateException

Creates a SigningCertificate attribute for the given certificates.

Attention! Only X.509 public key certificates (instances of iaik.x509.X509Certificate) or X.509 attribute certificates (instances of iaik.x409.attr.AttributeCertificate) can be handled by this constructor; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

Parameters:

certs - the certificates for which to create an SigningCertificate (may be instances of iaik.x509.X509Certificate and/or instances of iaik.x509.attr.AttributeCertificate

includeIssuerSerial - if the IssuerSerial component should be set for the ESSCertIDs to be created for the given certificates

Throws:

java.lang.IllegalArgumentException - if any of the supplied certificates is not an iaik.x509.X509Certificate or iaik.x509.attr.AttributeCertificate

java.security.NoSuchAlgorithmException - if SHA-1, required for hash computation, is not supported by the installed providers

java.security.cert.CertificateException - if an error occurs while encoding any of the certificates for computing the hash, or any of the given certificates is an attribute certificate, but the issuer information included is not sufficient to construct an IssuerSerial (if V2Form is used for indicating the issuer, but not the issuerName option)

SigningCertificate

public SigningCertificate(CertificateSet certSet,
                  boolean includeIssuerSerial)
                   throws java.security.NoSuchAlgorithmException,
                          java.security.cert.CertificateException

Creates a SigningCertificate attribute for the given certificates.

Attention! Only X.509 public key certificates (instances of iaik.x509.X509Certificate) or X.509 attribute certificates (instances of iaik.x409.attr.AttributeCertificate) can be handled by this constructor; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

Parameters:

certs - the certificates for which to create an SigningCertificate (may be instances of iaik.x509.X509Certificate and/or instances of iaik.x509.attr.AttributeCertificate

includeIssuerSerial - if the IssuerSerial component should be set for the ESSCertIDs to be created for the given certificates

Throws:

java.lang.IllegalArgumentException - if any of the supplied certificates is not an iaik.x509.X509Certificate or iaik.x509.attr.AttributeCertificate

java.security.NoSuchAlgorithmException - if SHA-1, required for hash computation, is not supported by the installed providers

java.security.cert.CertificateException - if an error occurs while encoding any of the certificates for computing the hash, or any of the given certificates is an attribute certificate, but the issuer information included is not sufficient to construct an IssuerSerial (if V2Form is used for indicating the issuer, but not the issuerName option)

SigningCertificate

public SigningCertificate(ASN1Object obj)
                   throws CodingException

Creates a new SigningCertificate from an ASN1Object.

The ASN1Object supplied to this constructor represents an already exisiting SigningCertificate object that may have been created by calling toASN1Object.

Parameters:

obj - the SigningCertificate as ASN1Object

Throws:

CodingException - if the ASN1Object could not be parsed

Method Detail

setPolicies

public void setPolicies(PolicyInformation[] policies)

Sets the policy informations of this SigningCertificate.

Parameters:

policies - the the policy informations to be set

getESSCertIDs

public ESSCertID[] getESSCertIDs()

Returns the ESS certs IDs.

Returns:

the ESS certs IDs included, or null if no cert ID is set

getESSCertID

public ESSCertID getESSCertID(java.security.cert.Certificate cert)

Searches for the ESSCertID identifying the given cert.

Parameters:

cert - the cert for which to look if a corresponding ESSCertID is included

Returns:

the ESSCertID identifying the given cert, or null if no corresponding certID can be found

isSignerCertificate

public boolean isSignerCertificate(X509Certificate certificate)
                            throws java.security.NoSuchAlgorithmException

Checks if this SigningCertificate identifies the given certificate as certificate of the signer to whom this SigningCertificate belongs.

Parameters:

certificate - the certificate to be checked of being the certificate of the signer

true - if this SigningCertificate attribute does not contain any ESSCertIDs or if the first ESSCertID of this SigningCertificate identifies the given certificate, false in any other case

Throws:

java.security.NoSuchAlgorithmException - if the check cannot be performed since the required SHA-1 algorithm is not supported by the installed cryptography providers

getAuthorizedCertificates

public java.security.cert.Certificate[] getAuthorizedCertificates(java.security.cert.Certificate[] certificates)

Gets the authorized certificates from the set of supplied certficates.

The S/MIMEv3 ESS SigningCertificate attribute allows to limit the set of authorization certificates that are used during signature validation. Authorization certificates may be attribute certificates or public key certificates. This method scans the provided certificate set for those certificates authorized by the ESSCertID identifiers included in this SigningCertificate. The array returned by this method may contain all certificates supplied if this SigningCertificate does not limit the set of authorization certificates at all (only contains one ESSCertID, the one identifying the signing certificate) or if this SigningCertificate contains ESSCertIDs for all the certificates supplied.

Note that only authorization certificates are returned, i.e. the first ESSCertID is not checked, e.g.:
Assuming you supply five certificates cert1, cert2, ... , cert5 to this method and only for the first three certs ESSCertIDs are included in this SigningCertificate attribute, this method will return cert1 and cert2 as authorization cerificates.

Attention! Only X.509 public key certificates (instances of iaik.x509.X509Certificate) or X.509 attribute certificates (instances of iaik.x409.attr.AttributeCertificate) can be handled by this method; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

Parameters:

certificates - the certificates to be asked if being authorized

Returns:

the authorization certificates identified by this SigningCertificate or null if none of the supplied certificates is an authorization certificate

Throws:

java.lang.IllegalArgumentException - if any of the supplied certificates is not an iaik.x509.X509Certificate or iaik.x509.attr.AttributeCertificate

getPolicyInformations

public PolicyInformation[] getPolicyInformations(java.security.cert.Certificate cert)

Looks if the supplied certificate has a CertificatePolicies extension containing any of the PolicyInformation terms of this SigningCertificate attribute.

Parameters:

cert - the cert for which to look if having a CertificatePolicies extension containing any of the PolicyInformation terms of this SigningCertificate attribute.

Returns:

those PolicyInformation terms of the CertificatePolicies extension of the supplied certificate having the same OID as any of the PolicyInformation terms of this SigningCertificate; if no PolicyInformation terms are included in this SigningCertificate attribute, this method returns all the PolicyInformation terms of the supplied certificate´s CertificatePolicies extension (if present); this method may return null if the supplied certificate does not contain the CertificatePolicies extension at all, or if none of the PolicyInformation terms of the certificate´s CertificatePolicies extension matches to any one of the PolicyInformation terms of this SigningCertificate attribute

Throws:

java.lang.IllegalArgumentException - if any of the supplied certificates is not an iaik.x509.X509Certificate or iaik.x509.attr.AttributeCertificate

getPolicyInformationCerts

public java.security.cert.Certificate[] getPolicyInformationCerts(java.security.cert.Certificate[] certificates)

Gets those certificates from the supplied set of certificates having a CertificatePolicies extension with any of the PolicyInformation terms included in this SigningCertificate set.

The S/MIMEv3 ESS SigningCertificate attribute allows to identify those certificate policies that the signer asserts apply to a certificate, and under which the certificate should rely upon. This value suggests a policy value to be used in the relying party´s certification path validation.

This method scans the provided certificate set and for those certificates having a CertificatePolicies extension with any of the PolicyInformation terms included in this SigningCertificate. The array returned by this method may contain all certificates supplied if this SigningCertificate does contain any PolicyInformation terms at all or if each certificate supplied has a CertificatePolicies extensions containing at least one of the PolicyInformation terms included in this SigningCertificate attribute.

Attention! Only X.509 public key certificates (instances of iaik.x509.X509Certificate) or X.509 attribute certificates (instances of iaik.x409.attr.AttributeCertificate) can be handled by this method; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

Parameters:

certificates - the certificates to be asked of having a CertificatePolicies extension containing any of the PolicyInformation terms of this SigningCertificate

Returns:

the certificates having a CertificatePolicies extension with any of the PolicyInformation terms included in this SigningCertificate or null if none of the supplied certificates has a CertificatePolicies extensions with any of the PolicyInformation terms of this SigningCertificate attribute

Throws:

java.lang.IllegalArgumentException - if any of the supplied certificates is not an iaik.x509.X509Certificate or iaik.x509.attr.AttributeCertificate

getPolicies

public PolicyInformation[] getPolicies()

Returns the policiy informations.

Returns:

the policiy informations included, or null if no policy informations are set

countPolicies

public int countPolicies()

Returns the number of PolicyInformation terms included.

Returns:

the number of PolicyInformation terms included

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes the given ASN.1 SigningCertificate object for parsing the internal structure.

This method internally is called when creating a SigningCertificate object from an already existing SigningCertificate object, supplied as ASN1Object.

Parameters:

obj - the ESS SigningCertificate as ASN1Object

Throws:

CodingException - if the object can not be parsed

toASN1Object

public ASN1Object toASN1Object()

Returns this SigningCertificate as ASN1Object.

The ASN1Object returned by this method may be used as parameter value when creating an SigningCertificate object using the SigningCertificate(ASN1Object obj) constructor.

Returns:

this SigningCertificate as ASN1Object

toString

public java.lang.String toString()

Returns a string that represents the contents of this SigningCertificate object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation