The OSGi framework can authenticate code in the following ways:

At higher layers there are defined services that can manage the permissions that are associated with the authenticated unit of code. These services are:

For signing, this requires the JAR files to be signed; this is described in Digitally Signed JAR Files.

The Java platform on which the Framework runs must provide the Java Security APIs necessary for Java permissions. On resource-constrained platforms, these Java Security APIs may be stubs that allow the bundle classes to be loaded and executed, but the stubs never actually perform the security checks. The behavior of these stubs must be as follows:

This behavior allows code to run as if all bundles have AllPermission.

A JAR can be signed by multiple signers. Each signer must store two resources in the JAR file. These resources are:

These JAR file signing resources must be placed in the META-INF directory. For signing, the META-INF directory is special because files in there are not signed in the normal way. These signing resources must come directly after the MANIFEST.MF file, and before any other resources in a JAR stream. If this is not the case, then a Framework should not accept the signatures and must treat the bundle as unsigned. This ordering is important because it allows the receiver of the JAR file to stream the contents without buffering. All the security information is available before any resources are loaded. This model is shown in Figure 2.2.

Figure 2.2 Signer files in JAR

The signature instruction resource contains digests of the Manifest resource, not the actual resource data itself. A digest is a one way function that computes a value from the bytes of a resource in such a way that it is very difficult to create a set of bytes that matches that digest value.

The JAR Manifest must therefore contain one or more digests of the actual resources. These digests must be placed in their name section of the manifest. The name of the digest header is constructed with its algorithm followed by -Digest. An example is the SHA-256-Digest. It is recommended that OSGi Framework implementations support the following digest algorithms.

The hash must be encoded with a Base 64 encoding. Base 64 encoding is defined in [7] RFC 1421 Privacy Enhancement for Internet Electronic Mail.

For example, a manifest could look like:

Manifest-Version: 1.0
Bundle-Name: DisplayManifest
↵
Name: x/A.class
SHA-256-Digest: 7CCToQk6yvRusxNl0uSwrv37UY/fdz6aHou29mbswsM=
↵
Name: x/B.class
SHA-256-Digest: C+0CG/cy13WD2sq8dRZm+dNWAHIjm4RQmUVeLLv7DVU=
↵

Graphically this looks like Figure 2.3.

Figure 2.3 Signer files in JAR

OSGi JARs must be signed by one or more signers that sign all resources except the ones in the META-INF directory; the default behavior of the jarsigner tool. This is a restriction with respect to standard Java JAR signing; there is no partial signing for an OSGi JAR. The OSGi specification only supports fully signed bundles. The reason for this restriction is because partially signing can break the protection of private packages. It also simplifies the security API because all code of a bundle is using the same protection domain.

Signature files in nested JAR files (For example JARs on the Bundle-ClassPath) must be ignored. These nested JAR files must share the same protection domain as their containing bundle. They must be treated as if their resources were stored directly in the outer JAR.

Each signature is based on two resources. The first file is the signature instruction file; this file must have a file name with an extension .SF. A signature file has the same syntax as the manifest, except that it starts with Signature-Version: 1.0 instead of Manifest-Version: 1.0.

The only relevant part of the signature resource is the digest of the Manifest resource. The name of the header must be the name algorithm (e.g. SHA-256) followed by -Digest-Manifest. For example:

Signature-Version: 1.0
SHA-256-Digest-Manifest: HmK7445BA7n5UYYI9xZKfSdMAPci44Jn7ZcmoyoiWoM=

The signature resource can contain name sections as well. However, these name sections should be ignored.

If there are multiple signers, then their signature instruction resources can be identical if they use the same digest algorithms. However, each signer must still have its own signature instruction file. That is, it is not allowed to share the signature resource between signers.

The indirection of the signature instruction files digests is depicted in Figure 2.4 for two signers: ACME and DAFFY.

Figure 2.4 Manifest, signature instruction files and digests in JAR

OSGi bundles are always valid JAR files. However, there are a few restrictions that apply to bundles that do not apply to JAR files.

A bundle can be signed with a signature by multiple signers. A signature contains a pair of a signature file, with a SF extension and a PKCS#7 resource that has the same name as the signature file but with either an RSA or DSA extension.

Such a signature is valid when:

For a complete bundle to be validly signed it is necessary that all signatures are valid. That is, if one of the signatures is invalid, the whole bundle must be treated as unsigned.

Several different available algorithms can perform digital signing. OSGi Framework implementations should support the following algorithms:

The signature files for RSA and DSA are stored in a PKCS#7 format. This is a format that has a structure as defined in [10] Public Key Cryptography Standard #7. The PKCS#7 standard provides access to the algorithm specific signing information as well as the certificate with the public key of the signer. The verification algorithm uses the public key to verify that:

The complete signing structure is shown in Figure 2.4.

A certificate is a general term for a signed document containing a name and public key information. Such a certificate can take many forms but the OSGi JAR signing is based on the X.509 certificate format. It has been around for many years and is part of the OSI group of standards. X.509 is defined in [2] X.509 Certificates.

An X.509 certificate contains the following elements:

The structure of a certificate is depicted in Figure 2.5.

Figure 2.5 Structure of a certificate

Certificates can be freely dispersed; they do not contain any secret information. Therefore, the PKCS#7 resource contains the signing certificate. It cannot be trusted at face value because the certificate is carried in the bundle itself. A perpetrator can easily create its own certificate with any content. The receiver can only verify that the certificate was signed by the owner of the public key (the issuer) and that it has not been tampered with. However, before the statement in the certificate can be trusted, it is necessary to authenticate the certificate itself. It is therefore necessary to establish a trust model.

One trust model, supported but not required by the OSGi specifications, is placing the signing certificate in a repository. Any certificate in this repository is treated as trusted by default. However, placing all possible certificates in this repository does not scale well. In an open model, a device would have to contain hundreds of thousands of certificates. The management of the certificates could easily become overwhelming.

The solution is to sign a certificate by another certificate, and this process can be repeated several times. This delegation process forms a chain of certificates. All certificates for this chain are carried in the PKCS#7 file: if one of those certificates can be found in the trusted repository, the other dependent ones can be trusted, on the condition that all the certificates are valid. This model scales very well because only a few certificates of trusted signers need to be maintained. This is the model used in web browsers, as depicted in Figure 2.6.

Figure 2.6 Certificate authorities fan out

This specification does not specify access to the trusted repository. It is implementation specific how this repository is populated and maintained.

An X.509 name is a Distinguished Name (DN). A DN is a highly structured name, officially identifying a node in an hierarchical namespace. The DN concept was developed for the X.500 directory service which envisioned a world wide namespace managed by PTTs. Today, the DN is used as an identifier in a local namespace, as in a namespace designed by an Operator. For example, given a namespace that looks like Figure 2.7, the DN identifying Bugs looks like:

cn=Bug,o=ACME,c=US

Figure 2.7 Country, Company, Person based namespace.

The traversal of the namespace is reversed from the order in the DN, the first part specifies the least significant but most specific part. That is, the order of the attribute assertions is significant. Two DNs with the same attributes but different order are different DNs.

In the example, a node is searched in the root that has an attribute c (countryName) with a value that is US. This node is searched for a child that has an attribute o (organizationName) with a value of ACME. And the ACME node is searched for a child node with an attribute cn (commonName) that has a value "Bugs Bunny".

The tree based model is the official definition of a DN from the X.500 standards. However, in practice today, many DNs contain attributes that have no relation to a tree. For example, many DNs contain comments and copyrights in the ou (organizationalUnit) attribute.

The DN from an X.509 certificate is expressed in a binary structure defined by ASN.1 (a type language defined by ISO). However, the Distinguished Name is often used in interaction with humans. Sometimes, users of a system have to acknowledge the use of a certificate or an employee of an Operator must grant permissions based on a Distinguished Name of a customer. It is therefore paramount that the Distinguished Name has a good human readable string representation. The expressiveness of the ASN.1 type language makes this non-trivial. This specification only uses DN strings as defined in [1] RFC 2253Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names with a number of extensions that are specified by the javax.security.auth.x500.X500Principal class in CANONICAL form.

However, the complexity of the encoding/decoding is caused by the use of rarely used types and features (binary data, multi-valued RDNs, foreign alphabets, and attributes that have special matching rules). These features must be supported by a compliant implementation but should be avoided by users. In practice, these features are rarely used today.

The format of a string DN is as follows:

dn          ::= rdn ( ',' rdn ) *
rdn         ::= attribute ( '+' attribute ) *
attribute   ::= name '=' value
name        ::= readable | oid
oid         ::= number ( '.' number ) *   // See 1.3.2
readable    ::= <see attribute table>
value       ::= <escaped string>

Spaces before and after the separators are ignored, spaces inside a value are significant but multiple embedded spaces are collapsed into a single space. Wildcard asterisks ('*' \u002A) are not allowed in a value part. The following characters must be escaped with a reverse solidus ('\' \u005C):

    comma               ','     \u002C
    plus                '+'     \u002B
    double quote        '"'     \u0022
    reverse solidus     '\'     \u005C
    less then           '<'     \u003C
    greater then        '>'     \u003E
    semicolon           ';'     \u003B

Reverse solidi ('\' \u005C) must already be escaped in Java strings, requiring 2 reverse solidi in Java source code. For example:

    DN:             cn = Bugs Bunny, o = ACME++, C=US
    Canonical form: cn=bugs bunny,o=acme\+\+,c=us
    Java String:    "cn=Bugs Bunny,o=ACME\\+\\+,c=US"

The full Unicode character set is available and can be used in DNs. String objects must be normalized and put in canonical form before being compared.

    DN:             cn = Bugs Bunny, o = Ð Þ, C=US
    Canonical form: cn=bugs bunny,o=ð þ,c=us
    Java String:    "cn = Bugs Bunny, o = Ð Þ, C=US"

The names of attributes (attributes types as they are also called) are actually translated into an Object IDentifier (OID). An OID is a dotted decimal number, like 2.5.4.3 for the cn (commonName) attribute name. It is therefore not possible to use any attribute name because the implementation must know the aliasing as well as the comparison rules. Therefore only the attributes that are listed in the following table are allowed (in short or long form):

commonName              cn          2.5.4.3     ITU X.520
surName                 sn          2.5.4.4 
countryName             c           2.5.4.6
localityName            l           2.5.4.7 
stateOrProvinceName     st          2.5.4.8
organizationName        o           2.5.4.10 
organizationalUnitName  ou          2.5.4.11
title                               2.5.4.12 
givenName                           2.5.4.42 
initials                            2.5.4.43 
generationQualifier                 2.5.4.44 
dnQualifier                         2.5.4.46 

streetAddress           street                  RFC 2256
domainComponent         dc                      RFC 1274
userid                  uid                     RFC 1274/2798?
emailAddress                                    RFC 2985
serialNumber                                    RFC 2985

The following DN:

2.5.4.3=Bugs Bunny,organizationName=ACME,2.5.4.6=US

Is therefore identical to:

cn=Bugs Bunny,o=ACME,c=US

The attribute types officially define a matching rule, potentially allowing cases sensitive and case insensitive. The attributes in the previous list all match case insensitive. Therefore, an OSGi DN must not depend on case sensitivity.

The X.500 standard supports multi-valued RDNs, however, their use is not recommended. See [12] Understanding and Deploying LDAP Directory Services for the rationale of this recommendation. Multi-valued RDNs separate their constituents with a plus sign ('+' \u002B). Their order is not significant. For example:

cn=Bugs Bunny+dc=x.com+title=Manager,o=ACME,c=US

Which is the same as

dc=x.com+cn=Bugs Bunny+title=Manager, o=ACME,c=US

Certificates are matched by their Subject DN. Before matching, DNs, they must first be put in canonical form according to the algorithm specified in javax.security.auth.x500.X500Principal.

DNs can also be compared using wildcards. A wildcard asterisk ('*' \u002A) replaces all possible values. Due to the structure of the DN, the comparison is more complicated than string-based wildcard matching.

A wildcard can stand for a number of RDNs, or the value of a single RDN. DNs with a wildcard must be canonicalized before they are compared. This means, among other things, that spaces must be ignored, except in values.

The format of a wildcard DN match is:

CertificateMatch    ::= dn-match ( ';' dn-match) *
dn-match            ::= ( '*' | rdn-match ) 
                            ( ',' rdn-match ) * | '-' 
rdn-match           ::= name '=' value-match
value-match         ::= '*' | value-star
value-star          ::= < value, requires escaped '*' and'-' >

The most simple case is a single wildcard; it must match any DN. A wildcard can also replace the first list of RDNs of a DN. The first RDNs are the least significant. Such lists of matched RDNs can be empty.

For example, a DN with a wildcard that matches all nodes descendant from the ACME node in Figure 2.7 on page , looks like:

*, o=ACME, c=US

This wildcard DN matches the following DNs:

cn = Bugs Bunny, o = ACME, c = US
ou = Carots, cn=Daffy Duck, o=ACME, c=US
street = 9C\, Avenue St. Drézéry, o=ACME, c=US
dc=www, dc=acme, dc=com, o=ACME, c=US
o=ACME, c=US

The following DNs must not match:

street = 9C\, Avenue St. Drézéry, o=ACME,c=FR
dc=www, dc=acme, dc=com, c=US

If a wildcard is used for a value of an RDN, the value must be exactly *. The wildcard must match any value, and no substring matching must be done. For example:

cn=*,o=ACME,c=*

This DN with wildcard must match the following DNs:

cn=Bugs Bunny,o=ACME,c=US
cn = Daffy Duck , o = ACME , c = US
cn=Road Runner, o=ACME, c=NL

But not:

o=ACME, c=NL
dc=acme.com, cn=Bugs Bunny, o=ACME, c=US

Both forms of wildcard usage can be combined in a single matching DN. For example, to match any DN that is from the ACME company worldwide, use:

*, o=ACME, c=*

Matching of a DN takes place in the context of a certificate. This certificate is part of a certificate chain, see Certificates. Each certificate has a Subject DN and an Issuer DN. The Issuer DN is the Subject DN used to sign the first certificate of the chain. DN matching can therefore be extended to match the signer. The semicolon (';' \u003B) must be used to separate DNs in a chain.

The following example matches a certificate signed by Tweety Inc. in the US.

* ; ou=S & V, o=Tweety Inc., c=US

The wildcard matches zero or one certificates, however, sometimes it is necessary to match a longer chain. The minus sign ('-' \u002D) represents zero or more certificates, whereas the asterisk only represents a single certificate. For example, to match a certificate where the Tweety Inc. is in the certificate chain, use the following expression:

- ; *, o=Tweety Inc., c=US

The previous example matched if the Tweety Inc. certificate was trusted, or was signed by a trusted certificate. Certain certificates are trusted because they are known by the Framework, how they are known is implementation-defined.

Implied permissions are permissions that the framework grants a bundle without any specific action. These permissions are necessary for normal operation. For example, each bundle gets permissions to read, write, and delete the bundle persistent storage area. The standard list of implied permissions is as follows:

OSGi supports a number of permissions that are granted when the target of the permissions is related to a bundle. For example, Admin Permission can grant a bundle the permission to manage other bundles. This is expressed by using a filter expression for the name of the permission. When the permission is checked, the filter is evaluated with specific permission attributes as well as attributes that describe the bundle's identity. For example, a bundle can get permission to get all services registered by bundles coming from a specific location:

ServicePermission("(location=https://www.acme.com/*)",GET )

This provides a very powerful model because it allows operators to let a group of bundles closely collaborate without requiring ad hoc namespaces for services, packages, and bundles. Using the signer or location as the target for a permission, will allow the maintenance of the permission management to be significantly reduced. It is not necessary to configure for individual bundles: the signer or location is effectively used as a grouping mechanism.

The filter can contain the following keys:

    (id=256)

    (location=https://www.acme.com/download/*)

    (signer=\*,o=ACME,c=NL)

    (name=com.acme.*)

The name parameter of the permission can also be a single wildcard asterisk ('*' \u002A). In that case all bundles must match.