pyCertLogo

OpenSSL template file generator for embedding pictures or audio logotypes into X.509 digital certificates. This tool's main purpose is help with automated generation of OpenSSL templates for embedding specific logotypes (either images and audio, cfr. below) into either public-key and attribute certificates conforming with ITU-T X.509 / RFC 5280 standard.

Rationale

Certificate logos/logotypes augment the UX of end-user applications and improve the overall digital trust, as they provide trusted visual representations of people, organizations, website and/or IT systems which digital certificates are bound to. The digital signature of a CA over such digital certificate also protects the embedded logos/logotypes, thus ensuring their integrity and authenticity together with the rest of the certified data (e.g. a public key or attribute). In order to effectively exploit this "side-channel trust", either the digital signing or the digital signature validation processes should support parsing the logo(s) from the certificate payload (further details in the 7 examples below).

Standards

Implements X.509 Public Key Infrastructure (PKI) standard RFC 9399 (“Logotypes in X.509 Certificates”) from May 2023, which obsoletes both RFC 3709 and RFC 6170. This may also be used for electronic certificates, pursuant to Regulation (UE) №910/2014 “eIDAS”, currently at its final stages of legislative review to transit into eIDAS2, which norms European electronic signatures (e-signing), seals (e-sealing), attestations of attributes, electronic ledgers (DLTs), website authentication certificates (WAC), as well as other types of electronic trust services. Other relevant technical standards where certificate logotypes may improve the overall UX are those on advanced digital signatures (including advanced e-signatures/seals) on additional file formats:

• PDF: both Adobe's PDF Signature (ISO 32000-2), and “PAdES” from the ETSI EN 319-142 family;
• XML: both W3C's XML Digital Signature (XML-DSIG), and “XAdES” from the ETSI EN 319-132 family;
• PKCS#7: both “CAdES” from the ETSI EN 319-122 family, and the original “CMS”* (RFC 5652;
• JSON: both JSON Web Signature (JWS from RFC 7515), and “JAdES” from the ETSI TS 119-182 family.

Applications

A non-exhaustive list of applications potentially benefiting from the embedding of images or audio content as certificate logos/logotypes includes:

1. Compositing, on an electronically signed (e-sign) PDF document, the scanned raster of the signatory (natural person)'s handwritten signature, derived from the e-certificate itself. When the e-signed document is printed on paper or viewed on screen, this provides a convincing visual representation of an handwritten signature to relying parties. Besides, the signature is not pasted from a potentially untrusted image under the control of anyone, but rather it is parsed from the e-certificate itself as part of the e-signing process, thus that is still under the control of the signatory. The signature's raster is indeed a public payload, thus it may be copied on untrusted certificates or even documents without a valid e-signature. Yet, its association with the e-certificate's public key (and, reflectively, with the e-signature itself) is cryptographically sound: relying parties who trust an e-signing process designed to enable a "certificate logotype workflow" will also trust the authenticity of the signature raster. The e-signature itself, however, not the embedded logo, is the one legally binding evidence on the document. Cfr. ETSI EN 319-142 “PAdES” standards' family for more details.
2. Compositing, on an electronically sealed (e-seal) PDF document, the organizationl logotypes (legal person) that visually improve both the document's integrity and authenticity. Cfr. considerations from the previous bullet point.
3. Extract, from the identification (IdV) certificate in an electronic identification (eID) means (e.g. an e-Passport, or the Italian CIE eID card), the owner's ICAO-compliant photograph raster. The Authority that e-sealed the above certificate has previously and authoritatively identity-proofed the subject. Relying parties may trust such cryptographic binding to identify the subject, by comparing the photograph embedded into the IdV certificate with a real-time scan of the subject's appearence, acquired during automated or manual inspection by a (e.g. customs) officer. Comparison with the printed photograph on the eID card may also be used to authenticate the ID/travel document itself. This process augments and builds from eID Passive Authentication (PAC) method (cfr. BSI TR-03110 standard).
4. The web browser where a given website (or any other online HTTPS resource) is visited displays the logotype of such trusted website's organization directly parsing it from its website authentication certificate (WAC), or "TLS certificate". In this case the logo extracted from the validated WAC provides improved user experience (UX) on the association of the visited page with its legitimate owner (instead of relying on commonName or lenghtier-to-read distinguished names in the WAC). Again, relying parties trusting the web browser's WAC validation process should trust the authenticity of websites with such valid WACs.
5. Applications performing identification/authentication/authorization processes, e.g. by means of XML/JSON/JWS based messaging like SAML/OAuth/OpenID Connect (OIDC) assertons, tokens, decentralized identifiers (DIDs), transactions on databases/e-ledgers/blockchains, as well as attestations of attributes may carry pictures representing such processes, as well as the logotypes of their service/identity providers and relying parties. These logos may be displayed by web/mobile applications to improve visual identification of such parties and provide better UX and digital trust to the users.
6. Web/mobile apps processing e-money, payment cards or cryptocurrency transactions may display the logos from either the card's EMV circuit, the issuing bank, the merchant(s), the cryptocurrency system and the crypto-wallet itself, again, in order to improve the overall UX and provide real-time "visual trust" to such transactions.
7. Operating systems parsing an e-signed/sealed file may represented on the desktop/GUI via an icon (which usually resembles the file format or provides a thumbnail preview of the file content). Even without, or before, formally validation of the digital signature(s) in the file (as per RFC 5280) the logo(s) embedded in the corresponding certificate(s) may be parsed and superimposed over the icon, in the form of one or multiple badges. That may improves the users' visibility as to whether the file was digitally signed, as well as to the technical and legal binding of those signature (e.g. whether the file has a single, multiple or parallel signatures; whether they are advanced, simple or qualified e-signatures/seals; etc.). After formal validation, an additional badge may display the outcome for each signature (for a limited time only, to account for certificates having been potentially revoked/suspended/expired)

Usage

The first argument to pass is the pathname an OpenSSL-valid configuration file (may also be empty when initially written by the present tool, otherwise data are just appended to it). Other arguments are optional (but at least one is required):

[-i URIorFilename]        Filename or URI where a valid Issuer logotype can be found;
[-s URIorFilename]        Filename or URI where a valid Subject logotype can be found;
[-c URIorFilename]        Filename or URI where valid Community logotype(s) can be found (can be invoked multiple times);
[-O oid -o URIorFileame]  OID and filename (or URI) where any other logotype(s) can be found (can be invoked multiple times);.

Examples

Certificate logotypes for the seven applications above may be generated using pyCertLogo using the following suggested commands:

1. Electronic trust service provider (eTSP) issuing e-signing certificate with the eTSP's own logo as Issuer logotyoe (-i/--issuer) and a raster image representing the signer's handwritten signature (e.g. a monochromatic transparent PNG) as the Subject logotype (-s/--subject). A Qualified trust service provider (QTSP) may add the eIDAS trust mark, pursuant to CIR (EU) 2015/806, as another logotype (-O and -o) associated to a reserved OID by the European Commission (EC).
2. eTSP issuing e-sealing certificate with the eTSP's own logo as Issuer logotyoe (-i) and a raster image representing the seal-creator organization's logo as the Subject logotype (-s). Optionally, a QTSP may add the eIDAS trust mark as another logotype (-O+-o) associated to the aforementioned EC-reserved OID.
3. Authority governing an ID/eID means issues an IdV certificate using the Authority's own logo as Issuer logotype (-i), the eID subject's photograph as Subject logotype (-s) and, optionally, either the ICAO logo and the organization manufacturing the smartcard's logo as community logos (multiple -c/--community).
4. eTSP issuing web access certificate (WAC) using the eTSP's own logo as Issuer logotype (-i), the website owner's own logo as Subject logotype (-s) and, optionally, the CA/Browser Forum's own logo as Community (-c) or other logotype (-o+-O). A QTSP may add the eIDAS trust mark as another logotype (-O+-o) associated to the aforementioned EC-reserved OID, for further display, by the web browser, of the qualified status of the authenticated website (pursuant to eIDAS2 Regulation art.45).
5. The application e-seals every messages (e.g. SAML requests/responses/assertions, or OAuth/OIDC tokens) for authentication/integrity purposes, using the certificate's issuing CA's logo as Issuer logotype (-i), the application's (or the app owner's) own logo as Subject logotype (-s). Optionally, either the logo of the identification/authentication/authorization framework (e.g. the OAuth logo) and the specific federation (e.g. the SPID or the CieID logos for the Italian eIDs) as either community (-c) and other logotype, each identifiedy by its own reserved OIDs (multiple -o+-O).
6. Authorization certificate for e-money transactions contains (references to) the logo(s) of either the card's circuit (e.g. EMV), issuing central or commercial bank, cryptowallet provider, merchant, cryptocurrency framework, etc.., as well as some logo referring to the card's owner (e.g. the company logo in case of business payment cards).
7. The certificate parsed from the e-signature/seal uses the issuing eTSP as Issuer logotype (-i), a visual identifier of the signatory/seal-creator's (e.g. its logo, the raster of a stamp from the organization, or the CEO's handwritten signature) as Subject logotype (-s), plus additional logos. To help blending such badges with different OS graphic backgrounds, a background picture may also be parsed from the certificate, which badges are composited over. Alternatively, an image representing the digital certificate itself (along with its SubjectDN, IssuerDN, expiration dates, etc.) may be included. These two options are embedded as other logotypes (-o+-O), with specific OIDs, repsectively input as either id-logo-background and id-logo-certImage strings.

Implementation details

Logotypes may be “directly” embedded in the X.509 certificate. That considerably increases their payload size, up to some very resource-constrained applications/hardware failing to process the certificate, despite the Logotype extension (OID 1.3.6.1.5.5.7.20) is non-critical. Alternatively, logos may be “indirectly” referenced from the certificate: each logotype is an externally provided content (e.g. uploaded on a CDN) and the certificate just contains a URI to that. In this case the certificate payload is not significantly increased, but at the expenses of the issuing CA, which should provide for the logotype(s)' online availability. Hashing of logotypes is mandatory as per RFC 9399 (both for direct and indirect ones), yet but their trust function is relevant only in the indirect referencing, as the digital certificate's own digital signature also protects directly embedded logos. Thus, at least a SHA-256 digest should be used for indirectly-referenced logotypes, whereas SHA-1 may be used for directly embedded ones, as they are less usefull byt may further reduce the certificate's size. Therefore, direct embedding should be evalued for small raster logos (GIF or PNG no bigger than 200×150 pixels) or very "simple" vector logos (SVG).

Currently supported file formats for certificate logotypes are SVG (and SVGZ), PNG, JPEG, PDF and GIF, as well as MP3 (meant to contain audio descriptions for pictorial logotypes). This tool checks that input files are valid in their respective formats, but does not perform strict constraints checking (e.g. it checks for the lack of any <script> elements in an SVG and also canonicalizes it, but does not validate it as SVG Tiny 1.2, as per RFC). However, it is up to the users' sole responsibility to ensure the files both comply with the technical format constrains from RFC 9399 and, above all, do not contain any malware, as this would end up being embedded in or referenced by digital certificates, potentially providing an out-of-band attack vector.

This Python script includes a class to manipulate Object Identifiers (OIDs), plus classes to prepare the logos embedding within X.509 certificates. The script's output is a multi-section, OpenSSL configuration text file template that can be used by OpenSSL itself to embed commandline-input logotypes into newly generated digital certificates relying on that template.

Considerations for PKI and other advanced users

Certificates whch are part of a chain, particularly leaf certificates, should not include logos referred by/to CAs higher along the trust chain ‒ provided embedded logotypes are used for intermediate (sub-CA) and root CAs as well. Those logos should in fact be included only as logotypes within those CA certificates. For example, it is not recommended, as it is a waste of resources, to have the same logo embedded as a Subject logo in a CA certificate as well as the Issuer logo in subordinate or end-user certificates issued by that CA.

Logos associated to a whole (technical or administrative) PKI may be included as Community/other logos within the root certificates of the PKI. Logos associated to circuits, frameworks and/or programs, should be embedded only in the highest-ranking sub-CA certificate dedicated to issuing certificates for those circuits/frameworks/programs.

In all the aforementioned cases and if there is a requirement ‒ e.g. to allow atomic display of all logos associated to a leaf certificate by parsing only one certificate ‒ you may consider to only embed the certificates in the leaf certificate, while referencing them in higher-rank CA certificates (or vice versa). Consider what each alternative entails, both technically with your digital signing and validation processes, as well as UX-wise, then ensure to stay consistent about that. Long story short, a logotype for an internal CA which acts as both a certificate issuer and subject along the chain, should be directly embedded once only within certificates along the trust chain, so that a validation algorithm is expected to perform one parsing operation, for the same logo, during the validation process of any end-user certificate.