Add documentation on the Mozilla-JSS Provider #443
Conversation
|
Discussion from #454 should be added here. |
cipherboy
force-pushed
the
add-provider-loader-docs
branch
from
86bfc13
to
5ddd122
Compare
cipherboy
changed the title
docs/usage/jssprovider.md
Outdated
| it. For more information, see the corresponding NSS documentation on these | ||
| values. | ||
|
|
||
| The following initialization values are supported: |
There was a problem hiding this comment.
These params are documented in javadoc. Should we just point to javadoc instead duplicating it here?
There was a problem hiding this comment.
Sure, I think that'd be better.
| `jss.cfg` takes the same `InitializationValues` parameters, except in a | ||
| properties file format. | ||
|
|
||
| ### JSS Config |
There was a problem hiding this comment.
I don't think we actually need the jss. or nss. prefixes, but it's up to you.
There was a problem hiding this comment.
There's other subtrees (ocsp being the deeper one); I think it makes sense then to have a separate jss and nss subtree. For reference, the nss.cfg used by OpenJDK is flat:
name = NSS
nssLibraryDirectory = /usr/lib64
nssDbMode = noDb
attributes = compatibility
handleStartupErrors = ignoreMultipleInitialisation
But they also use camelCase and prefix NSS-specific attributes with nss.
docs/usage/jssprovider.md
Outdated
| try { | ||
| cm = CryptoManager.getInstance(); | ||
| } catch (NotInitializedException nie) { | ||
| CryptoManager.initialize(...); | ||
| cm = CryptoManager.getInstance(); | ||
| } |
There was a problem hiding this comment.
Not sure it's necessary to tell people to change their code this way.
Theoretically people can continue to use the old API which will work
with the old and the new JSS:
CryptoManager.initialize(...);
CryptoManager cm = CryptoManager.getInstance();
Once they no longer need to support the old JSS they can simply drop
CryptoManager.initialize() and switch to java.security.
There was a problem hiding this comment.
This is the section under java.security. Presumably, if they're using this code snippet, they'd prefer a java.security JSS instance over a CryptoManager instance. This describe a fallback when either JSS doesn't support java.security or JSS wasn't initialized that way.
I've added a comment saying they could throw this exception instead of catching it.
I don't think its reasonable to assume everyone is going to switch to java.security right away, and those that will, won't necessarily support it consistently.
cipherboy
force-pushed
the
add-provider-loader-docs
branch
from
5ddd122
to
efe16ac
Compare
|
@edewata I believe this is updated. Thanks for your feedback! Thoughts? |
docs/usage/jssprovider.md
Outdated
| The `Mozilla-JSS` JCA-compatible Provider exposes most of the functionality | ||
| of JSS to external packages. This interface is the recommend interface most | ||
| developers should build against. However, once the dependencies are satisfied | ||
| and JSS's native component are available to the JVM, we still have to load |
| There are two routes to do this: | ||
|
|
||
| 1. Via the `CryptoManager` interface, _and_ | ||
| 2. Via `java.security`, directly loading the `JSSProvider`. |
There was a problem hiding this comment.
JSSProvider -> JSS Provider.
Signed-off-by: Alexander Scheel <ascheel@redhat.com>
Also add clearer InvalidLengthException descriptions. Signed-off-by: Alexander Scheel <ascheel@redhat.com>
cipherboy
force-pushed
the
add-provider-loader-docs
branch
from
efe16ac
to
3eef454
Compare
|
This can always be updated in future PRs. Merging! |
Signed-off-by: Alexander Scheel <ascheel@redhat.com>This begins to document our changes w.r.t.
JSSProviderLoader&c.You can see the rendered documentation here.