iaik.smime.ess
Class SigningCertificate

java.lang.Object
  iaik.asn1.structures.AttributeValue
      iaik.smime.ess.ESSAttributeValue
          iaik.smime.ess.SigningCertificate

All Implemented Interfaces:

ASN1Type

Direct Known Subclasses:

SigningCertificateV2

public class SigningCertificate
extends ESSAttributeValue

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 };
 SigningCertificate signingCertificate = new SigningCertificate(certs);
 

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 = ...;
 ...
 signedAttributes[i] = new Attribute(signingCertificate);
 ...
 signerInfo.setSignedAttributes(signedAttributes);
 

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

 SigningCertificate signingCertificate = 
   (SigningCertificate)signerInfo.getSignedAttributeValue(SigningCertificate.oid);
 if (signingCertificate != null) {
   ...
 }
 

If you want to use the SigningCertificate attribute with other hash algorithms than SHA-1, use the SigningCertificateV2 attribute.

See Also:

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

Field Summary

static ObjectID

oid The attributeType object identifier of this SigningCertificate extension.

Constructor Summary

SigningCertificate()
Empty default constructor.

SigningCertificate(ASN1Object obj)
Creates a new SigningCertificate from an ASN1Object.

SigningCertificate(java.security.cert.Certificate[] certs)
Creates a SigningCertificate attribute for the given certificates.

SigningCertificate(java.security.cert.Certificate[] certs, boolean includeIssuerSerial)
Creates a SigningCertificate attribute for the given certificates.

SigningCertificate(java.security.cert.Certificate[] certs, boolean includeIssuerSerial, SecurityProvider securityProvider)
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

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.
boolean	equals(java.lang.Object obj) Compares this SigningCertificate to the specified object.
ObjectID	getAttributeType() Returns the OID identifying the SigningCertificate attribute type.
java.security.cert.Certificate[]	getAuthorizedCertificates(java.security.cert.Certificate[] certificates) Gets the authorized certificates from the set of supplied certificates.
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.
SecurityProvider	getSecurityProvider() Gets the SecurityProvider installed for this SigningCertificate.
int	hashCode() Returns a hashcode for this object.
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.
void	setSecurityProvider(SecurityProvider securityProvider) Sets the SecurityProvider for 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 iaik.smime.ess.ESSAttributeValue

multipleAllowed

Methods inherited from class iaik.asn1.structures.AttributeValue

getName

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

oid

public static final ObjectID oid

The attributeType object identifier of this SigningCertificate extension. The corresponding OID string is "1.2.840.113549.1.9.16.2.12".

Constructor Detail

SigningCertificate

public SigningCertificate()

Empty default constructor. Required for dynamic object creation. Shall not be used by an application!

SigningCertificate

public SigningCertificate(ESSCertID[] essCertIDs)

Creates a SigningCertificate for the given ESSCertIDs. All ESSCertIDs must be V1 ESSCertIDs, otherwise an IllegalArgumentException is thrown.

Parameters:

essCertIDs - the cert IDs to be set

SigningCertificate

public SigningCertificate(java.security.cert.Certificate[] certs)
                   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.x509.attr.AttributeCertificate) can be handled by this constructor; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

When using the constructor for creating a SigningCertificate attribute, the IssuerSerial component is calculated and set for each ESSCertID element to be created.

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

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(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.x509.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(java.security.cert.Certificate[] certs,
                          boolean includeIssuerSerial,
                          SecurityProvider securityProvider)
                   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.x509.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

securityProvider - the SecurityProvider to be explicitly used for the cryptographic operations (cert hash calculation) required by this object, if null the default system-wide installed security provider will be used

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.x509.attr.AttributeCertificate) can be handled by this constructor; PKCS#6 ExtendedCertificates are obsolete and therefore not supported.

Parameters:

certSet - 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

setSecurityProvider

public void setSecurityProvider(SecurityProvider securityProvider)

Sets the SecurityProvider for this SigningCertificate.

This method allows to explicitly set a SecurityProvider for this SigningCertificate. If no explicit SecurityProvider is set, the default system wide installed SecurityProvider will be used for the required cryptographic operations.

This class may use the following method(s) of the SecurityProvider, which may be overriden by an application, if required:

• getHash() to calculate an SHA-1 hash from the encoded certificates required for the ESSCertID objects of the SigningCertificate

An application may prefer to immediately supply the SecurityProvider when creating a new SigningCertificate for some certificate.

Parameters:

securityProvider - the SecurityProvider to be set

getSecurityProvider

public SecurityProvider getSecurityProvider()

Gets the SecurityProvider installed for this SigningCertificate.

This class uses the following method(s) of the SecurityProvider, which may be overriden by an application, if required:

• getHash() to calculate an SHA-1 hash from the encoded certificates required for the ESSCertID objects of the SigningCertificate

If no explicit SecurityProvider has been set for this object, the default system wide installed SecurityProvider will be used for the required cryptographic operations. However, this method will return null if it does not have its own SecurityProvider.

Returns:

the SecurityProvider explicitly installed for this object, or null if this object does not have its own SecurityProvider

setPolicies

public void setPolicies(PolicyInformation[] policies)

Sets the policy informations of this SigningCertificate.

Parameters:

policies - the the policy informations to be set

getAttributeType

public ObjectID getAttributeType()

Returns the OID identifying the SigningCertificate attribute type.

Specified by:

getAttributeType in class AttributeValue

Returns:

the OID identifying the SigningCertificate attribute type.

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

Returns:

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 certificates.

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 cert2 and cert3 as authorization cerificates (cert1 will be not returned since it is the signer certificate itself).

Attention! Only X.509 public key certificates (instances of iaik.x509.X509Certificate) or X.509 attribute certificates (instances of iaik.x509.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; if this SigningCertificate contains only one ESSCertID (the one identifying the signer cert), all supplied certificates are returned by this method since there is no limitation to the set of authorization certificates

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 CertificatePolicies extension (if present) of the given certificate; 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 CertificatePolicies extension of the certificate 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 by certification path validation of the relying party.

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.x509.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; if this SigningCertificate does not contain any PolicyInformation terms, all supplied certificates are returned by this method

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

equals

public boolean equals(java.lang.Object obj)

Compares this SigningCertificate to the specified object.

Specified by:

equals in class ESSAttributeValue

Parameters:

obj - the object to compare this SigningCertificate against.

Returns:

true, if the given object is equal to this SigningCertificate, false otherwise

hashCode

public int hashCode()

Returns a hashcode for this object.

Overrides:

hashCode in class ESSAttributeValue

Returns:

a hashcode for this object

toString

public java.lang.String toString()

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

Specified by:

toString in class AttributeValue

Returns:

the string representation