siemens / cmp-ra-component

A CMP Registration Authority (RA)
Apache License 2.0
3 stars 5 forks source link
cmp rfc4210 x509certificates

Features of the generic CMP RA component

The generic CMP RA component supports the implementation of applications that provide CMP Registration Authority (RA) functions. It implements the RA features specified in the Lightweight Certificate Management Protocol (CMP) Profile, reflecting the updates to CMP (RFC 4210) and CRMF (RFC 4211) given in Certificate Management Protocol (CMP) Updates and Certificate Management Protocol (CMP) Algorithms.

Basic features for use in PoCs, reference implementations, and in production

Advanced features, in particular for productive use

Structure of the generic CMP RA component

The picture below shows the overall design and relation to JAVA base components:

Structure of the generic CMP RA component

Overall software design

Message exchange API design

For simplicity, there is only one downstream interface towards clients (EEs) and one upstream interface towards server (CA). In case multiple downstream or upstream interfaces are desired:

All messages, also PKCS#10 and X.509 structures, are exchanged as ASN.1 DER-encoded byte strings.

The transport layer in the embedding RA server application is responsible for the following:

Component and interface design

The embedding application does not need to know CMP specifics. It can regard incoming and outgoing CMP messages simply as opaque Java byte arrays. The externally usable interface is specified in com.siemens.pki.cmpracomponent.main.CmpRaComponent.

The UML diagram component and interface design gives an overview about external components and interactions. component and interface design

Dynamic message exchange behavior on the downstream CMP interface and upstream PKCS#10/X.509 interface

In the PKCS#10 case the upstream communication (towards the CA) is synchronous. The UML diagram Sequence diagram for PKCS#10/X.509 gives an overview about instantiation and message exchange between CMP RA component, downstream interface and upstream interface:

Sequence diagram for PKCS#10/X.509

  1. The "Configuration Interface" activates the "Downstream Interface" when instantiating the "RA Component" by calling the instantiateP10X509CmpRaComponent() method.
  2. The "Downstream Interface" sends a DER-encoded CMP p10cr as a byte array to the "RA Component" by calling the Function<byte[], byte[]> method.
  3. The "RA Component" activates the "Upstream Interface" by calling the upstreamP10X509Exchange method with a byte array containing a DER-encoded PKCS#10 CSR and a certificate profile.
  4. The "Upstream Interface" processes the request, returning a byte array containing an X.509 certificate response to the "RA Component."
  5. The "RA Component" then responds to the Function<byte[], byte[]> method call of the "Downstream Interface" in step 2 with a byte array response containing an CMP cp message. Overall, the diagram details the method calls and message exchanges involved in the interaction between the "Configuration Interface," "Downstream Interface," "RA Component," and "Upstream Interface" for certificate management operations.

Dynamic message exchange behavior for downstream and upstream CMP interface

In this case the upstream CMP communication (towards the CA) may be synchronous and/or asynchronous. The UML diagram Sequence diagram for CMP gives an overview about instantiation and message exchange between CMP RA component, downstream interface, and upstream interface:

Sequence diagram for CMP

The diagram outlines an interaction between components in a system, involving the "Configuration Interface", "Downstream Interface", "RA Component", and "Upstream Interface". Here's a detailed breakdown of the steps involved:

  1. The "Configuration Interface" activates the "Downstream Interface" to instantiate the "RA Component" by calling the instantiateCmpRaComponent() method.
  2. The "Downstream Interface" sends a DER-encoded CMP request to the "RA Component" using the processRequest() method.
  3. The "RA Component" activates the "Upstream Interface" to perform the upstreamExchange operation with a DER-encoded CMP request and a certificate profile.
  4. If the interaction is synchronous, the "Upstream Interface" directly sends a DER-encoded CMP response to the "RA Component," which then responds to the "Downstream Interface" with a DER-encoded CMP response using the processRequest() method.
  5. If the interaction is asynchronous with delayed delivery, the "Upstream Interface" sends a null response to the "RA Component" due to the absence of the response. The "RA Component" then responds to the "Downstream Interface" with DER-encoded CMP cr/ir/kur/error response indicating a waiting indication.
  6. In a loop, the "Downstream Interface" sends a DER-encoded CMP polling request to the "RA Component," which responds with a DER-encoded CMP polling poll response.
  7. If the "Upstream Interface" got a DER-encoded CMP response by calling gotResponseAtUpstream() the "RA Component" responds DER-encoded CMP response to the "Downstream Interface."

Configuration interface design

Interfaces to inventory for certification request validation

and status updates, and for persistency

Javadoc API documentation

After the javadoc documentation has been generated locally by invoking mvn javadoc:javadoc, it can be found at target/site/apidocs/com/siemens/pki/cmpracomponent/main/CmpRaComponent.html.

Features of the generic CMP client component

The client extends the generic CMP RA component. It implements the End Entity features specified in the Lightweight Certificate Management Protocol (CMP) Profile reflecting the updates to CMP (RFC 4210) and CRMF (RFC 4211) given in Certificate Management Protocol (CMP) Updates and Certificate Management Protocol (CMP) Algorithms.

Basic feature​s for use in PoCs, reference implementations, and in production

Advanced features, in particular for productive use

Structure of the generic CMP client component

The picture below shows the overall design and relation to JAVA base components:

Structure of the generic CMP client component

Overall software design

Message exchange API design

For simplicity, there is only one upstream interface towards server (CA). In case multiple upstream interfaces are desired:

All CMP messages are exchanged as ASN.1 DER-encoded byte strings.

The transport layer in the embedding client application is responsible for the following:

Component and interface design

The embedding application does not need to know CMP specifics. It can regard incoming and outgoing CMP messages simply as opaque Java byte arrays. The externally usable interface is specified in com.siemens.pki.cmpclientcomponent.main.CmpClient.

The UML diagram component and interface design gives an overview about external components and interactions. component and interface design

Dynamic message exchange behavior for downstream and upstream CMP interface

The UML diagram Sequence diagram for CMP gives an overview about instantiation and message exchange between CMP Client component and upstream interface:

Sequence diagram for CMP

The diagram describes the interaction between an "Embedding Application" and a "Client Instance" using the "UpstreamExchange interface" to perform actions related to certificate management. Here's a detailed explanation of the steps involved in the interaction:

  1. The "Embedding Application" activates and interacts with the "Client Instance" to perform certificate management operations.
  2. The "Client Instance" interacts with the "UpstreamExchange interface" to send and receive messages related to certificate management.
  3. The "Embedding Application" makes a synchronous call to the "Client Instance" to execute the getCACertificates(), getCertificateRequestTemplate(), getCRLs(), getRootCACertificateUpdate(), invokeEnrollment(), or invokeRevocation() methods.
  4. The "Embedding Application" sends a request to the "Client Instance" to invoke the CmpClient method.
  5. The "Client Instance" interacts with the "UpstreamExchange interface" to send and receive messages using the sendReceiveMessage() method. This includes sending a request with specific parameters and receiving a response.
  6. If the communication is synchronous, the "UpstreamExchange interface" directly sends a response to the "Client Instance". If it's asynchronous, there may be a delayed delivery, and the response includes a waiting indication.
  7. In the case of asynchronous communication, the "Client Instance" loops back to the "UpstreamExchange interface" to send a poll request and receive a poll response until the response is received.
  8. After successful enrollment without implicit confirmation, the "Client Instance" sends a certificate confirmation, and the "UpstreamExchange interface" responds with a PKI confirmation.
  9. The "Client Instance" then sends the response of the method call back to the "Embedding Application".

Configuration interface design

For configuration interface details see RA Configuration interface design which is partly reused for client configuration.

Acknowledgements

This work was partly funded by the German Federal Ministry of Education and Research in the project Quoryptan through grant number 16KIS2033.