The CryptoX509 class

Summary:

Syntax
Methods
CryptoX509 Features
Examples

Syntax

The CryptoX509 class provides methods to manipulate X509 certificates needed for identification of individual persons, groups or any entities during XML encryption or signature process. It also provides additional load and save functions to interact with other applications in XML or in BASE64, such as in WS-Security compliant applications. It follows the XML-Signature and XML-Encryption specifications.

The status is set to zero after a successful method call.

Syntax

xml.CryptoX509

Creation method

Class Methods
Name	Description
`xml.CryptoX509.Create() RETURNING xml.CryptoX509`	Constructor of an empty CryptoX509 object. Returns a CryptoX509 object or NULL. Throws an exception in case of errors, and updates status with an error code.
`xml.CryptoX509.CreateFromNode( node xml.DomNode) RETURNING xml.CryptoX509`	Constructor of a new CryptoX509 object from a XML X509 certificate node, according to the XML-Signature specification; where node is an ELEMENT node with X509Data as local name, and belonging to the XML-Signature namespace http://www.w3.org/2000/09/xmldsig#. Returns a CryptoX509 object or NULL. Note : if the X509 certificate is incomplete, the certificate will be created from the application global certificate list if one of SubjectName or Issuer matches. (See addCertificate for more details) Throws an exception in case of errors, and updates status with an error code.

Back to the top

Access method

Object Methods
Name	Description
`getIdentifier() RETURNING STRING`	Returns the indentification part of this X509 certificate in a STRING. Example: /C=FR/ST=France/L=Schiltigheim/O=MC/OU=My Company Name/CN=cert Throws an exception in case of errors, and updates status with an error code.

Back to the top

Modify methods

Object Methods
Name	Description
`createPublicKey( url STRING ) RETURNING xml.CryptoKey`	Creates a new public CryptoKey object for the given url, from the public key embedded in this certificate if any; NULL otherwise. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Load and save methods

Object Methods
Name	Description
`loadPEM( file STRING )`	Loads a X509 certificate from a file in PEM format, where file is the filename or an entry in the FGLPROFILE file. Throws an exception in case of errors, and updates status with an error code.
`loadDER( file STRING )`	Loads a X509 certificate from a file in DER format, where file is the filename or an entry in the FGLPROFILE file. Throws an exception in case of errors, and updates status with an error code.
`save() RETURNING xml.DomDocument`	Saves the CryptoX509 certificate into a XML document with ds:X509Data as root node according to the XML-Signature specification. (See also the RetrievalMethod feature) Throws an exception in case of errors, and updates status with an error code.
`saveToString() RETURNING STRING`	Saves the CryptoX509 certificate into a BASE64 string format. Throws an exception in case of errors, and updates status with an error code.
`load( xml xml.DomDocument)`	Loads the given XML document with ds:X509Data as root node according to the XML-Signature specification, into the CryptoX509 object. Note: if the X509 certificate in the XML document is incomplete, the certificate will be loaded from the global certificate list if one of SubjectName or Issuer matches. Throws an exception in case of errors, and updates status with an error code.
`loadFromString( str STRING)`	Loads the given X509 certificate in BASE64 string format into this CryptoX509 object. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Feature methods

Object Methods
Name	Description
`setFeature( feature STRING, value STRING)`	Sets or resets the given feature for this CryptoX509 object. Throws an exception in case of errors, and updates status with an error code.
`getFeature( feature STRING) RETURNING STRING`	Returns the value of the given feature for this CryptoX509 object, or NULL if feature is not set. Throws an exception in case of errors, and updates status with an error code.

CryptoX509 Features

Feature	Description
X509Certificate (See specification for details)	Defines or returns whether the complete X509 certificate is added during XML signature or encryption. Note: default value is FALSE.
X509SubjectName (See specification for details)	Defines or returns whether the subject name of the X509 certificate is added during XML signature or encryption. Note: default value is FALSE.
X509IssuerSerial (See specification for details)	Defines or returns whether the issuer name and serial number of the X509 certificate is added during XML signature or encryption. Note: default value is FALSE.
RetrievalMethod (See specification for details)	Defines or returns the URL where the XML form of the X509 certificate will be set during a XML signature, and loaded during a XML verification process, and based on that CryptoX509 object. Note 1: default value is NULL, meaning that no retrieval method is used. Note 2: the XML form of a X509 certificate can be obtain by the save() method.

Back to the top

Examples

Example 1 : Loading a certificate from a PEM file

01 IMPORT xml
02 
03 MAIN
04   DEFINE x509 xml.CryptoX509 
05   LET x509 = xml.CryptoX509.Create()
06   TRY
07     CALL x509.loadPEM("Certificate.crt");
08     DISPLAY "Id : ",x509.getIdentifier()
09   CATCH
10     DISPLAY "Unable to load certificate :",STATUS
11   END TRY 
12 END MAIN

Example 2 : Creating a public key for signature verification from a certificate

01 IMPORT xml
02 
03 MAIN
04   DEFINE x509 xml.CryptoX509 
05   DEFINE key xml.CryptoKey 
06   LET x509 = xml.CryptoX509.Create()
07   TRY
08     CALL x509.loadPEM("RSA1024Certificate.crt");
09   CATCH
10     DISPLAY "Unable to load certificate :",STATUS
11     EXIT PROGRAM
12   END TRY 
13   TRY
14     LET key = x509.createPublicKey("http://www.w3.org/2000/09/xmldsig#rsa-sha1")
15     DISPLAY "Key size (in bytes) : ",key.getSize() # displays 1024 (bits)
16     DISPLAY "Key type : ",key.getType() # displays PUBLIC
17     DISPLAY "Key usage : ",key.getUsage() # displays SIGNATURE
18   CATCH
19     DISPLAY "Unable to create public key :",STATUS
20   END TRY 
21 END MAIN

Example 3 : Saving the subjectName of a certificate in XML

01 IMPORT xml
02 
03 MAIN
04   DEFINE x509 xml.CryptoX509 
05   DEFINE key xml.CryptoKey 
06   DEFINE doc xml.DomDocument
07   LET x509 = xml.CryptoX509.Create()
08   TRY
09     CALL x509.loadPEM("RSA1024Certificate.crt");
10   CATCH
11     DISPLAY "Unable to load certificate :",STATUS
12     EXIT PROGRAM
13   END TRY 
14   TRY
15     CALL x509.setFeature("X509SubjectName",TRUE)
16     LET doc = x509.save()
17     CALL doc.setFeature("format-pretty-print",TRUE)
18     CALL doc.save("RSAX509SubjectName.xml")
19   CATCH
20     DISPLAY "Unable to save certificate :",STATUS
21   END TRY 
22 END MAIN

Note: All certificates in PEM format were created with the OpenSSL tool

Back to the top